source: trunk/python/pyregfi/__init__.py @ 253

Last change on this file since 253 was 253, checked in by tim, 13 years ago

added preliminary interface to security descriptors in pyregfi
misc bug fixes

File size: 34.6 KB
Line 
1#!/usr/bin/env python
2
3## @package pyregfi
4# Python interface to the regfi library.
5#
6
7## @mainpage API Documentation
8#
9# The pyregfi module provides a Python interface to the @ref regfi Windows
10# registry library. 
11#
12# The library operates on registry hives, each of which is contained within a
13# single file.  To get started, one must first open the registry hive file with
14# the open() or file() Python built-in functions (or equivalent) and then pass
15# the resulting file object to pyregfi. For example:
16# @code
17# >>> import pyregfi
18# >>> fh = open('/mnt/win/c/WINDOWS/system32/config/system', 'rb')
19# >>> myHive = pyregfi.Hive(fh)
20# @endcode
21#
22# Using this Hive object, one can begin investigating what top-level keys
23# exist by starting with the root Key attribute:
24# @code
25# >>> for key in myHive.root.subkeys:
26# ...   print(key.name)
27# ControlSet001
28# ControlSet003
29# LastKnownGoodRecovery
30# MountedDevices
31# Select
32# Setup
33# WPA
34# @endcode
35#
36# From there, accessing subkeys and values by name is a simple matter of:
37# @code
38# >>> myKey = myHive.root.subkeys['Select']
39# >>> myValue = myKey.values['Current']
40# @endcode
41#
42# The data associated with a Value can be obtained through the fetch_data()
43# method:
44# @code
45# >>> print(myValue.fetch_data())
46# 1
47# @endcode
48#
49# While useful for simple exercises, using the subkeys object for deeply nested
50# paths is not efficient and doesn't make for particularly attractive code. 
51# Instead, a special-purpose HiveIterator class is provided for simplicity of
52# use and fast access to specific known paths:
53# @code
54# >>> myIter = pyregfi.HiveIterator(myHive)
55# >>> myIter.descend(['ControlSet001','Control','NetworkProvider','HwOrder'])
56# >>> myKey = myIter.current_key()
57# >>> print(myKey.values['ProviderOrder'].fetch_data())
58# RDPNP,LanmanWorkstation,WebClient
59# @endcode
60#
61# The first two lines above can be simplified in some "syntactic sugar" provided
62# by the Hive.subtree() method.  Also, as one might expect, the HiveIterator
63# also acts as an iterator, producing keys in a depth-first order.
64# For instance, to traverse all keys under the ControlSet003\\Services key,
65# printing their names as we go, we could do:
66# @code
67# >>> for key in Hive.subtree(['ControlSet003','Services']):
68# >>>   print(key.name)
69# Services
70# Abiosdsk
71# abp480n5
72# Parameters
73# PnpInterface
74# ACPI
75# [...]
76# @endcode
77#
78# Note that "Services" was printed first, since the subtree is traversed as a
79# "preordering depth-first" search starting with the HiveIterator's current_key(). 
80# As one might expect, traversals of subtrees stops when all elements in a
81# specific subtree (and none outside of it) have been traversed.
82#
83# For more information, peruse the various attributes and methods available on
84# the Hive, HiveIterator, Key, Value, and Security classes.
85#
86# @note @ref regfi is a read-only library by design and there
87# are no plans to implement write support.
88#
89# @note At present, pyregfi has been tested with Python versions 2.6 and 3.1
90#
91# @note Developers strive to make pyregfi thread-safe.
92#
93# @note Key and Value names are case-sensitive in regfi and pyregfi
94#
95import sys
96import time
97import ctypes
98import ctypes.util
99import threading
100from pyregfi.structures import *
101
102
103## An enumeration of registry Value data types
104#
105# @note This is a static class, there is no need to instantiate it.
106#       Just access its attributes directly as DATA_TYPES.SZ, etc
107class DATA_TYPES(object):
108    ## None / Unknown
109    NONE                       =  0
110    ## String
111    SZ                         =  1
112    ## String with %...% expansions
113    EXPAND_SZ                  =  2
114    ## Binary buffer
115    BINARY                     =  3
116    ## 32 bit integer (little endian)
117    DWORD                      =  4 # DWORD, little endian
118    ## 32 bit integer (little endian)
119    DWORD_LE                   =  4
120    ## 32 bit integer (big endian)
121    DWORD_BE                   =  5 # DWORD, big endian
122    ## Symbolic link
123    LINK                       =  6
124    ## List of strings
125    MULTI_SZ                   =  7
126    ## Unknown structure
127    RESOURCE_LIST              =  8
128    ## Unknown structure
129    FULL_RESOURCE_DESCRIPTOR   =  9
130    ## Unknown structure
131    RESOURCE_REQUIREMENTS_LIST = 10
132    ## 64 bit integer
133    QWORD                      = 11 # 64-bit little endian
134
135
136## An enumeration of log message types
137#
138# @note This is a static class, there is no need to instantiate it.
139#       Just access its attributes directly as LOG_TYPES.INFO, etc
140class LOG_TYPES(object):
141    ## Informational messages, useful in debugging
142    INFO  =  0x01
143    ## Non-critical problems in structure parsing or intepretation
144    WARN  =  0x04
145    ## Major failures
146    ERROR =  0x10
147
148
149def _buffer2bytearray(char_pointer, length):
150    if length == 0 or char_pointer == None:
151        return None
152   
153    ret_val = bytearray(length)
154    for i in range(0,length):
155        ret_val[i] = char_pointer[i][0]
156
157    return ret_val
158
159
160def _strlist2charss(str_list):
161    ret_val = []
162    for s in str_list:
163        ret_val.append(s.encode('utf-8', 'replace'))
164
165    ret_val = (ctypes.c_char_p*(len(str_list)+1))(*ret_val)
166    # Terminate the char** with a NULL pointer
167    ret_val[-1] = 0
168
169    return ret_val
170
171
172def _charss2strlist(chars_pointer):
173    ret_val = []
174    i = 0
175    s = chars_pointer[i]
176    while s:
177        ret_val.append(s.decode('utf-8', 'replace'))
178        i += 1
179        s = chars_pointer[i]
180
181    return ret_val
182
183
184
185## Returns the (py)regfi library version
186#
187# @return A string indicating the version
188def getVersion():
189    return regfi.regfi_version()
190
191
192## Retrieves messages produced by regfi during parsing and interpretation
193#
194# The regfi C library may generate log messages stored in a special thread-safe
195# global data structure.  These messages should be retrieved periodically or
196# after each major operation by callers to determine if any errors or warnings
197# should be reported to the user.  Failure to retrieve these could result in
198# excessive memory consumption.
199def getLogMessages():
200    msgs = regfi.regfi_log_get_str()
201    if not msgs:
202        return ''
203    return msgs.decode('utf-8')
204
205
206## Sets the types of log messages to record
207#
208# @param log_types A sequence of message types that regfi should generate.
209#                  Message types can be found in the LOG_TYPES enumeration.
210#
211# @return True on success, False on failure.  Failures are rare, but could
212#         indicate that global logging is not operating as expected.
213#
214# Example:
215# @code
216# setLogMask((LOG_TYPES.ERROR, LOG_TYPES.WARN, LOG_TYPES.INFO))
217# @endcode
218#
219# The message mask is a global (all hives, iterators), thread-specific value.
220# For more information, see @ref regfi_log_set_mask.
221#
222def setLogMask(log_types):
223    mask = 0
224    for m in log_types:
225        mask |= m
226    return regfi.regfi_log_set_mask(mask)
227
228
229## Opens a file as a registry hive
230#
231# @param path The file path of a hive, as one would provide to the
232#             open() built-in
233#
234# @return A new Hive instance
235def openHive(path):
236    fh = open(path, 'rb')
237    return Hive(fh)
238
239
240## Abstract class for most objects returned by the library
241class _StructureWrapper(object):
242    _hive = None
243    _base = None
244
245    def __init__(self, hive, base):
246        if not hive:
247            raise Exception("Could not create _StructureWrapper,"
248                            + " hive is NULL.  Current log:\n"
249                            + getLogMessages())
250        if not base:
251            raise Exception("Could not create _StructureWrapper,"
252                            + " base is NULL.  Current log:\n"
253                            + getLogMessages())
254        self._hive = hive
255        self._base = base
256
257
258    # Memory management for most regfi structures is taken care of here
259    def __del__(self):
260        regfi.regfi_free_record(self._hive.file, self._base)
261
262
263    # Any attribute requests not explicitly defined in subclasses gets passed
264    # to the equivalent REGFI_* structure defined in structures.py
265    def __getattr__(self, name):
266        return getattr(self._base.contents, name)
267
268   
269    ## Test for equality
270    #
271    # Records returned by pyregfi may be compared with one another.  For example:
272    # @code
273    #  >>> key2 = key1.subkeys['child']
274    #  >>> key1 == key2
275    #  False
276    #  >>> key1 != key2
277    #  True
278    #  >>> key1 == key2.get_parent()
279    #  True
280    # @endcode
281    def __eq__(self, other):
282        return (type(self) == type(other)) and (self.offset == other.offset)
283
284
285    def __ne__(self, other):
286        return (not self.__eq__(other))
287
288
289class Key():
290    pass
291
292
293class Value():
294    pass
295
296
297
298## Represents a registry SK record which contains a security descriptor
299#
300class Security(_StructureWrapper):
301    ## Number of keys referencing this SK record
302    ref_count = 1
303
304    ## The absolute file offset of the SK record's cell in the Hive file
305    offset = 0xCAFEBABE
306
307    ## The @ref SecurityDescriptor for this SK record
308    descriptor = object()
309
310    def __init__(self, hive, base):
311        super(Security, self).__init__(hive, base)
312        # XXX: add checks for NULL pointers
313        self.descriptor = winsec.SecurityDescriptor(base.contents.sec_desc.contents)
314
315    ## Loads the "previous" Security record in the hive
316    #
317    # @note
318    # SK records are included in a circular, doubly-linked list.
319    # To iterate over all SK records, be sure to check for the repetition of
320    # the SK record you started with to determine when all have been traversed.
321    def next_security(self):
322        return Security(self._hive,
323                        regfi.regfi_next_sk(self._hive.file, self._base))
324
325    ## Loads the "previous" Security record in the hive
326    #
327    # @note
328    # SK records are included in a circular, doubly-linked list.
329    # To iterate over all SK records, be sure to check for the repetition of
330    # the SK record you started with to determine when all have been traversed.
331    def prev_security(self):
332        return Security(self._hive,
333                        regfi.regfi_prev_sk(self._hive.file, self._base))
334
335
336## Abstract class for ValueList and SubkeyList
337class _GenericList(object):
338    _hive = None
339    _key_base = None
340    _length = None
341    _current = None
342
343    # implementation-specific functions for SubkeyList and ValueList
344    _fetch_num = None
345    _find_element = None
346    _get_element = None
347    _constructor = None
348
349    def __init__(self, key):
350        if not key:
351            raise Exception("Could not create _GenericList; key is NULL."
352                            + "Current log:\n" + getLogMessages())
353
354        base = regfi.regfi_reference_record(key._hive.file, key._base)
355        if not base:
356            raise Exception("Could not create _GenericList; memory error."
357                            + "Current log:\n" + getLogMessages())
358        self._key_base = cast(base, type(key._base))
359        self._length = self._fetch_num(self._key_base)
360        self._hive = key._hive
361
362   
363    def __del__(self):
364        regfi.regfi_free_record(self._hive.file, self._key_base)
365
366
367    ## Length of list
368    def __len__(self):
369        return self._length
370
371
372    ## Retrieves a list element by name
373    #
374    # @return the first element whose name matches, or None if the element
375    #         could not be found
376    def __getitem__(self, name):
377        index = ctypes.c_uint32()
378        if isinstance(name, str):
379            name = name.encode('utf-8')
380
381        if name != None:
382            name = create_string_buffer(bytes(name))
383
384        if self._find_element(self._hive.file, self._key_base, 
385                              name, byref(index)):
386            return self._constructor(self._hive,
387                                     self._get_element(self._hive.file,
388                                                       self._key_base,
389                                                       index))
390        raise KeyError('')
391
392    def get(self, name, default):
393        try:
394            return self[name]
395        except KeyError:
396            return default
397   
398    def __iter__(self):
399        self._current = 0
400        return self
401   
402    def __next__(self):
403        if self._current >= self._length:
404            raise StopIteration('')
405
406        elem = self._get_element(self._hive.file, self._key_base,
407                                 ctypes.c_uint32(self._current))
408        self._current += 1
409        return self._constructor(self._hive, elem)
410   
411    # For Python 2.x
412    next = __next__
413
414
415## The list of subkeys associated with a Key
416#
417# This attribute is both iterable:
418# @code
419#   for k in myKey.subkeys:
420#     ...
421# @endcode
422# and accessible as a dictionary:
423# @code
424#   mySubkey = myKey.subkeys["keyName"]
425# @endcode
426#
427# @note SubkeyLists should never be accessed directly and only exist
428#       in association with a parent Key object.  Do not retain references to
429#       SubkeyLists.  Instead, access them via their parent Key at all times.
430class SubkeyList(_GenericList):
431    _fetch_num = regfi.regfi_fetch_num_subkeys
432    _find_element = regfi.regfi_find_subkey
433    _get_element = regfi.regfi_get_subkey
434
435
436## The list of values associated with a Key
437#
438# This attribute is both iterable:
439# @code
440#   for v in myKey.values:
441#     ...
442# @endcode
443# and accessible as a dictionary:
444# @code
445#   myValue = myKey.values["valueName"]
446# @endcode
447#
448# @note ValueLists should never be accessed directly and only exist
449#       in association with a parent Key object.  Do not retain references to
450#       ValueLists.  Instead, access them via their parent Key at all times.
451class ValueList(_GenericList):
452    _fetch_num = regfi.regfi_fetch_num_values
453    _find_element = regfi.regfi_find_value
454    _get_element = regfi.regfi_get_value
455
456
457## Registry key
458# These represent registry keys (@ref REGFI_NK records) and provide
459# access to their subkeys, values, and other metadata.
460#
461# @note Value instances may provide access to more than the attributes
462#       documented here.  However, undocumented attributes may change over time
463#       and are not officially supported.  If you need access to an attribute
464#       not shown here, see pyregfi.structures.
465class Key(_StructureWrapper):
466    ## A @ref ValueList object representing the list of Values
467    #  stored on this Key
468    values = None
469
470    ## A @ref SubkeyList object representing the list of subkeys
471    #  stored on this Key
472    subkeys = None
473
474    ## The raw Key name as an uninterpreted bytearray
475    name_raw = (b"...")
476   
477    ## The name of the Key as a (unicode) string
478    name = "..."
479   
480    ## The absolute file offset of the Key record's cell in the Hive file
481    offset = 0xCAFEBABE
482
483    ## This Key's last modified time represented as the number of seconds
484    #  since the UNIX epoch in UTC; similar to what time.time() returns
485    modified = 1300000000.123456
486
487    ## The NK record's flags field
488    flags = 0x10110001
489
490    def __init__(self, hive, base):
491        super(Key, self).__init__(hive, base)
492        self.values = ValueList(self)
493        self.subkeys = SubkeyList(self)
494
495    def __getattr__(self, name):
496        if name == "name":
497            ret_val = super(Key, self).__getattr__(name)
498
499            if not ret_val:
500                ret_val = self.name_raw
501            else:
502                ret_val = ret_val.decode('utf-8', 'replace')
503               
504        elif name == "name_raw":
505            ret_val = super(Key, self).__getattr__(name)
506            length = super(Key, self).__getattr__('name_length')
507            ret_val = _buffer2bytearray(ret_val, length)
508       
509        elif name == "modified":
510            ret_val = regfi.regfi_nt2unix_time(byref(self._base.contents.mtime))
511
512        else:
513            ret_val = super(Key, self).__getattr__(name)
514
515        return ret_val
516
517
518    ## Retrieves the Security properties for this key
519    def fetch_security(self):
520        return Security(self._hive,
521                        regfi.regfi_fetch_sk(self._hive.file, self._base))
522
523
524    ## Retrieves the class name for this key
525    #
526    # Class names are typically stored as UTF-16LE strings, so these are decoded
527    # into proper python (unicode) strings.  However, if this fails, a bytearray
528    # is instead returned containing the raw buffer stored for the class name.
529    #
530    # @return The class name as a string or bytearray.  None if a class name
531    #         doesn't exist or an unrecoverable error occurred during retrieval.
532    def fetch_classname(self):
533        ret_val = None
534        cn_p = regfi.regfi_fetch_classname(self._hive.file, self._base)
535        if cn_p:
536            cn_struct = cn_p.contents
537            if cn_struct.interpreted:
538                ret_val = cn_struct.interpreted.decode('utf-8', 'replace')
539            else:
540                ret_val = _buffer2bytearray(cn_struct.raw,
541                                            cn_struct.size)
542            regfi.regfi_free_record(self._hive.file, cn_p)
543
544        return ret_val
545
546
547    ## Retrieves this key's parent key
548    #
549    # @return The parent's Key instance or None if current key is root
550    #         (or an error occured)
551    def get_parent(self):
552        if self.is_root():
553            return None
554        parent_base = regfi.regfi_get_parentkey(self._hive.file, self._base)
555        if parent_base:
556            return Key(self._hive, parent_base)
557        return None
558
559    def is_root(self):
560        return (self._hive.root == self)
561
562
563## Registry value (metadata)
564#
565# These represent registry values (@ref REGFI_VK records) and provide
566# access to their associated data.
567#
568# @note Value instances may provide access to more than the attributes
569#       documented here.  However, undocumented attributes may change over time
570#       and are not officially supported.  If you need access to an attribute
571#       not shown here, see pyregfi.structures.
572class Value(_StructureWrapper):
573    ## The raw Value name as an uninterpreted bytearray
574    name_raw = (b"...")
575   
576    ## The name of the Value as a (unicode) string
577    name = "..."
578   
579    ## The absolute file offset of the Value record's cell in the Hive file
580    offset = 0xCAFEBABE
581
582    ## The length of data advertised in the VK record
583    data_size = 0xCAFEBABE
584
585    ## An integer which represents the data type for this Value's data
586    # Typically this value is one of 12 types defined in @ref DATA_TYPES,
587    # but in some cases (the SAM hive) it may be used for other purposes
588    type = DATA_TYPES.NONE
589
590    ## The VK record's flags field
591    flags = 0x10110001
592
593    ## Retrieves the Value's data according to advertised type
594    #
595    # Data is loaded from its cell(s) and then interpreted based on the data
596    # type recorded in the Value.  It is not uncommon for data to be stored with
597    # the wrong type or even with invalid types.  If you have difficulty
598    # obtaining desired data here, use @ref fetch_raw_data().
599    #
600    # @return The interpreted representation of the data as one of several
601    #         possible Python types, as listed below.  None if any failure
602    #         occurred during extraction or conversion.
603    #
604    # @retval string for SZ, EXPAND_SZ, and LINK
605    # @retval int for DWORD, DWORD_BE, and QWORD
606    # @retval list(string) for MULTI_SZ
607    # @retval bytearray for NONE, BINARY, RESOURCE_LIST,
608    #         FULL_RESOURCE_DESCRIPTOR, and RESOURCE_REQUIREMENTS_LIST
609    #
610    def fetch_data(self):
611        ret_val = None
612        data_p = regfi.regfi_fetch_data(self._hive.file, self._base)
613        if not data_p:
614            return None
615        data_struct = data_p.contents
616
617        if data_struct.interpreted_size == 0:
618            ret_val = None
619        elif data_struct.type in (DATA_TYPES.SZ, DATA_TYPES.EXPAND_SZ, DATA_TYPES.LINK):
620            # Unicode strings
621            ret_val = data_struct.interpreted.string.decode('utf-8', 'replace')
622        elif data_struct.type in (DATA_TYPES.DWORD, DATA_TYPES.DWORD_BE):
623            # 32 bit integers
624            ret_val = data_struct.interpreted.dword
625        elif data_struct.type == DATA_TYPES.QWORD:
626            # 64 bit integers
627            ret_val = data_struct.interpreted.qword
628        elif data_struct.type == DATA_TYPES.MULTI_SZ:
629            ret_val = _charss2strlist(data_struct.interpreted.multiple_string)
630        elif data_struct.type in (DATA_TYPES.NONE, DATA_TYPES.RESOURCE_LIST,
631                                  DATA_TYPES.FULL_RESOURCE_DESCRIPTOR,
632                                  DATA_TYPES.RESOURCE_REQUIREMENTS_LIST,
633                                  DATA_TYPES.BINARY):
634            ret_val = _buffer2bytearray(data_struct.interpreted.none,
635                                        data_struct.interpreted_size)
636
637        regfi.regfi_free_record(self._hive.file, data_p)
638        return ret_val
639   
640
641    ## Retrieves raw representation of Value's data
642    #
643    # @return A bytearray containing the data
644    #
645    def fetch_raw_data(self):
646        ret_val = None
647        # XXX: should we load the data without interpretation instead?
648        data_p = regfi.regfi_fetch_data(self._hive.file, self._base)
649        if not data_p:
650            return None
651
652        data_struct = data_p.contents
653        ret_val = _buffer2bytearray(data_struct.raw,
654                                    data_struct.size)
655        regfi.regfi_free_record(self._hive.file, data_p)
656        return ret_val
657
658
659    def __getattr__(self, name):
660        ret_val = super(Value, self).__getattr__(name)
661        if name == "name":
662            if not ret_val:
663                ret_val = self.name_raw
664            else:
665                ret_val = ret_val.decode('utf-8', 'replace')
666
667        elif name == "name_raw":
668            length = super(Value, self).__getattr__('name_length')
669            ret_val = _buffer2bytearray(ret_val, length)
670
671        return ret_val
672
673
674# Avoids chicken/egg class definitions.
675# Also makes for convenient code reuse in these lists' parent classes.
676SubkeyList._constructor = Key
677ValueList._constructor = Value
678
679
680
681## Represents a single registry hive (file)
682class Hive():
683    file = None
684    raw_file = None
685    _root = None
686
687    ## The root Key of this Hive
688    root = None
689
690    ## This Hives's last modified time represented as the number of seconds
691    #  since the UNIX epoch in UTC; similar to what time.time() returns
692    modified = 1300000000.123456
693
694    ## First sequence number
695    sequence1 = 12345678
696
697    ## Second sequence number
698    sequence2 = 12345678
699
700    ## Major version
701    major_version = 1
702
703    ## Minor version
704    minor_version = 5
705
706    ## Constructor
707    #
708    # Initialize a new Hive based on a Python file object.  To open a file by
709    # path, see @ref openHive.
710    #
711    # @param fh A Python file object.  The constructor first looks for a valid
712    #           fileno attribute on this object and uses it if possible. 
713    #           Otherwise, the seek and read methods are used for file
714    #           access.
715    #
716    # @note Supplied file must be seekable.  Do not perform any operation on
717    #       the provided file object while a Hive is using it.  Do not
718    #       construct multiple Hive instances from the same file object.
719    #       If a file must be accessed by separate code and pyregfi
720    #       simultaneously, use a separate file descriptor.  Hives are
721    #       thread-safe, so multiple threads may use a single Hive object.
722    def __init__(self, fh):
723        # The fileno method may not exist, or it may throw an exception
724        # when called if the file isn't backed with a descriptor.
725        fn = None
726        try:
727            # XXX: Native calls to Windows filenos don't seem to work. 
728            #      Need to investigate why.
729            if not is_win32 and hasattr(fh, 'fileno'):
730                fn = fh.fileno()
731        except:
732            pass
733
734        if fn != None:
735            self.file = regfi.regfi_alloc(fn, REGFI_ENCODING_UTF8)
736            if not self.file:
737                # XXX: switch to non-generic exception
738                raise Exception("Could not open registry file.  Current log:\n"
739                                + getLogMessages())
740        else:
741            fh.seek(0)
742            self.raw_file = structures.REGFI_RAW_FILE()
743            self.raw_file.fh = fh
744            self.raw_file.seek = seek_cb_type(self.raw_file.cb_seek)
745            self.raw_file.read = read_cb_type(self.raw_file.cb_read)
746            self.file = regfi.regfi_alloc_cb(pointer(self.raw_file), REGFI_ENCODING_UTF8)
747            if not self.file:
748                # XXX: switch to non-generic exception
749                raise Exception("Could not open registry file.  Current log:\n"
750                                + getLogMessages())
751
752
753    def __getattr__(self, name):
754        if name == "root":
755            # XXX: This creates reference loops.  Need to cache better inside regfi
756            #if self._root == None:
757            #    self._root = Key(self, regfi.regfi_get_rootkey(self.file))
758            #return self._root
759            return Key(self, regfi.regfi_get_rootkey(self.file))
760
761        elif name == "modified":
762            return regfi.regfi_nt2unix_time(byref(self._base.contents.mtime))
763
764        return getattr(self.file.contents, name)
765
766   
767    def __del__(self):
768        regfi.regfi_free(self.file)
769        if self.raw_file != None:
770            self.raw_file = None
771
772
773    def __iter__(self):
774        return HiveIterator(self)
775
776
777    ## Creates a @ref HiveIterator initialized at the specified path in
778    #  the hive.
779    #
780    # @param path A list of Key names which represent an absolute path within
781    #             the Hive
782    #
783    # @return A @ref HiveIterator which is positioned at the specified path.
784    #
785    # @exception Exception If the path could not be found/traversed
786    def subtree(self, path):
787        hi = HiveIterator(self)
788        hi.descend(path)
789        return hi
790
791
792## A special purpose iterator for registry hives
793#
794# Iterating over an object of this type causes all keys in a specific
795# hive subtree to be returned in a depth-first manner. These iterators
796# are typically created using the @ref Hive.subtree() function on a @ref Hive
797# object.
798#
799# HiveIterators can also be used to manually traverse up and down a
800# registry hive as they retain information about the current position in
801# the hive, along with which iteration state for subkeys and values for
802# every parent key.  See the @ref up and @ref down methods for more
803# information.
804class HiveIterator():
805    _hive = None
806    _iter = None
807    _iteration_root = None
808    _lock = None
809
810    def __init__(self, hive):
811        self._iter = regfi.regfi_iterator_new(hive.file)
812        if not self._iter:
813            raise Exception("Could not create iterator.  Current log:\n"
814                            + getLogMessages())
815        self._hive = hive
816        self._lock = threading.RLock()
817   
818    def __getattr__(self, name):
819        self._lock.acquire()
820        ret_val = getattr(self._iter.contents, name)
821        self._lock.release()
822        return ret_val
823
824    def __del__(self):
825        self._lock.acquire()
826        regfi.regfi_iterator_free(self._iter)
827        self._lock.release()
828
829    def __iter__(self):
830        self._lock.acquire()
831        self._iteration_root = None
832        self._lock.release()
833        return self
834
835    def __next__(self):
836        self._lock.acquire()
837        if self._iteration_root == None:
838            self._iteration_root = self.current_key().offset
839        elif not regfi.regfi_iterator_down(self._iter):
840            up_ret = regfi.regfi_iterator_up(self._iter)
841            while (up_ret and
842                   not regfi.regfi_iterator_next_subkey(self._iter)):
843                if self._iteration_root == self.current_key().offset:
844                    self._iteration_root = None
845                    self._lock.release()
846                    raise StopIteration('')
847                up_ret = regfi.regfi_iterator_up(self._iter)
848
849            if not up_ret:
850                self._iteration_root = None
851                self._lock.release()
852                raise StopIteration('')
853           
854            # XXX: Use non-generic exception
855            if not regfi.regfi_iterator_down(self._iter):
856                self._lock.release()
857                raise Exception('Error traversing iterator downward.'+
858                                ' Current log:\n'+ getLogMessages())
859
860        regfi.regfi_iterator_first_subkey(self._iter)
861        ret_val = self.current_key()
862        self._lock.release()
863
864        return ret_val
865
866
867    # For Python 2.x
868    next = __next__
869
870    # XXX: Should add sanity checks on some of these traversal functions
871    #      to throw exceptions if a traversal/retrieval *should* have worked
872    #      but failed for some reason.
873
874    ## Descends the iterator to a subkey
875    #
876    # Descends the iterator one level to the current subkey, or a subkey
877    # specified by name.
878    #
879    # @param subkey_name If specified, locates specified subkey by name
880    #                    (via find_subkey()) and descends to it.
881    #
882    # @return True if successful, False otherwise
883    def down(self, subkey_name=None):
884        ret_val = None
885        if subkey_name == None:
886            self._lock.acquire()
887            ret_val = regfi.regfi_iterator_down(self._iter)
888        else:
889            if name != None:
890                name = name.encode('utf-8')
891            self._lock.acquire()
892            ret_val = (regfi.regfi_iterator_find_subkey(self._iter, name) 
893                       and regfi.regfi_iterator_down(self._iter))
894       
895        self._lock.release()
896        return ret_val
897
898
899    ## Causes the iterator to ascend to the current Key's parent
900    #
901    # @return True if successful, False otherwise
902    #
903    # @note The state of current subkeys and values at this level in the tree
904    #       is lost as a side effect.  That is, if you go up() and then back
905    #       down() again, current_subkey() and current_value() will return
906    #       default selections.
907    def up(self):
908        self._lock.acquire()
909        ret_val = regfi.regfi_iterator_up(self._iter)
910        self._lock.release()
911        return ret_val
912
913
914    ## Selects first subkey of current key
915    #
916    # @return A Key instance for the first subkey. 
917    #         None on error or if the current key has no subkeys.
918    def first_subkey(self):
919        ret_val = None
920        self._lock.acquire()
921        if regfi.regfi_iterator_first_subkey(self._iter):
922            ret_val = self.current_subkey()
923        self._lock.release()
924        return ret_val
925
926
927    ## Selects first value of current Key
928    #
929    # @return A Value instance for the first value. 
930    #         None on error or if the current key has no values.
931    def first_value(self):
932        ret_val = None
933        self._lock.acquire()
934        if regfi.regfi_iterator_first_value(self._iter):
935            ret_val = self.current_value()
936        self._lock.release()
937        return ret_val
938
939
940    ## Selects the next subkey in the current Key's list
941    #
942    # @return A Key instance for the next subkey.
943    #         None if there are no remaining subkeys or an error occurred.
944    def next_subkey(self):
945        ret_val = None
946        self._lock.acquire()
947        if regfi.regfi_iterator_next_subkey(self._iter):
948            ret_val = self.current_subkey()
949        self._lock.release()
950        return ret_val
951
952
953    ## Selects the next value in the current Key's list
954   
955    # @return A Value instance for the next value.
956    #         None if there are no remaining values or an error occurred.
957    def next_value(self):
958        ret_val = None
959        self._lock.acquire()
960        if regfi.regfi_iterator_next_value(self._iter):
961            ret_val = self.current_value()
962        self._lock.release()
963        return ret_val
964
965
966    ## Selects the first subkey which has the specified name
967    #
968    # @return A Key instance for the selected key.
969    #         None if it could not be located or an error occurred.
970    def find_subkey(self, name):
971        if name != None:
972            name = name.encode('utf-8')
973        ret_val = None
974        self._lock.acquire()
975        if regfi.regfi_iterator_find_subkey(self._iter, name):
976            ret_val = self.current_subkey()
977        self._lock.release()
978        return ret_val
979
980
981    ## Selects the first value which has the specified name
982    #
983    # @return A Value instance for the selected value.
984    #         None if it could not be located or an error occurred.
985    def find_value(self, name):
986        if name != None:
987            name = name.encode('utf-8')
988        ret_val = None
989        self._lock.acquire()
990        if regfi.regfi_iterator_find_value(self._iter, name):
991            ret_val = self.current_value()
992        self._lock.release()
993        return ret_val
994
995    ## Retrieves the currently selected subkey
996    #
997    # @return A Key instance of the current subkey
998    def current_subkey(self):
999        self._lock.acquire()
1000        ret_val = Key(self._hive, regfi.regfi_iterator_cur_subkey(self._iter))
1001        self._lock.release()
1002        return ret_val
1003
1004    ## Retrieves the currently selected value
1005    #
1006    # @return A Value instance of the current value
1007    def current_value(self):
1008        self._lock.acquire()
1009        ret_val = Value(self._hive, regfi.regfi_iterator_cur_value(self._iter))
1010        self._lock.release()
1011        return ret_val
1012
1013    ## Retrieves the current key
1014    #
1015    # @return A Key instance of the current position of the iterator
1016    def current_key(self):
1017        self._lock.acquire()
1018        ret_val = Key(self._hive, regfi.regfi_iterator_cur_key(self._iter))
1019        self._lock.release()
1020        return ret_val
1021
1022    ## Traverse downward multiple levels
1023    #
1024    # This is more efficient than calling down() multiple times
1025    #
1026    # @param path A list of Key names which represent the path to descend
1027    #
1028    # @exception Exception If path could not be located
1029    def descend(self, path):
1030        cpath = _strlist2charss(path)
1031
1032        self._lock.acquire()
1033        result = regfi.regfi_iterator_descend(self._iter, cpath)
1034        self._lock.release()
1035        if not result:
1036            # XXX: Use non-generic exception
1037            raise Exception('Could not locate path.\n'+getLogMessages())
1038
1039    ## Obtains a list of the current key's ancestry
1040    #
1041    # @return A list of all parent keys starting with the root Key and ending
1042    #         with the current Key
1043    def ancestry(self):
1044        self._lock.acquire()
1045        result = regfi.regfi_iterator_ancestry(self._iter)
1046        self._lock.release()
1047
1048        ret_val = []
1049        i = 0
1050        k = result[i]
1051        while k:
1052            k = cast(regfi.regfi_reference_record(self._hive.file, k), POINTER(REGFI_NK))
1053            ret_val.append(Key(self._hive, k))
1054            i += 1
1055            k = result[i]
1056
1057        regfi.regfi_free_record(self._hive.file, result)
1058        return ret_val
1059
1060    ## Obtains the current path of the iterator
1061    #
1062    # @return A list of key names starting with the root up to and
1063    #         including the current key
1064    #
1065    def current_path(self):
1066        ancestry = self.ancestry()
1067        return [str(a.name) for a in ancestry]
1068
1069
1070# Freeing symbols defined for the sake of documentation
1071del Value.name,Value.name_raw,Value.offset,Value.data_size,Value.type,Value.flags
1072del Key.name,Key.name_raw,Key.offset,Key.modified,Key.flags
1073del Hive.root,Hive.modified,Hive.sequence1,Hive.sequence2,Hive.major_version,Hive.minor_version
1074del Security.ref_count,Security.offset,Security.descriptor
Note: See TracBrowser for help on using the repository browser.