Changeset 257 for trunk/python


Ignore:
Timestamp:
06/16/11 20:13:13 (13 years ago)
Author:
tim
Message:

documentation fixes/additions

Location:
trunk/python/pyregfi
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/python/pyregfi/__init__.py

    r256 r257  
    1111#
    1212# 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:
     13# single file.  The quickest way to get started, is to use the @ref openHive()
     14# function to obtain a Hive object.  For example:
    1615# @code
    1716# >>> import pyregfi
    18 # >>> fh = open('/mnt/win/c/WINDOWS/system32/config/system', 'rb')
    19 # >>> myHive = pyregfi.Hive(fh)
     17# >>> myHive = pyregfi.openHive('/mnt/win/c/WINDOWS/system32/config/system')
    2018# @endcode
    2119#
    … …  
    300298#
    301299class Security(_StructureWrapper):
    302     ## Number of keys referencing this SK record
     300    ## Number of registry Keys referencing this SK record
    303301    ref_count = 1
    304302
    … …  
    306304    offset = 0xCAFEBABE
    307305
    308     ## The @ref SecurityDescriptor for this SK record
     306    ## The @ref winsec.SecurityDescriptor for this SK record
    309307    descriptor = object()
    310308
    … …  
    314312        self.descriptor = winsec.SecurityDescriptor(base.contents.sec_desc.contents)
    315313
    316     ## Loads the "previous" Security record in the hive
     314    ## Loads the "next" Security record in the hive
    317315    #
    318316    # @note
    … …  
    337335## Abstract class for ValueList and SubkeyList
    338336class _GenericList(object):
     337    # XXX: consider implementing keys(), values(), items() and other dictionary methods
    339338    _hive = None
    340339    _key_base = None
    … …  
    373372    ## Retrieves a list element by name
    374373    #
     374    # @param name The name of the subkey or value desired. 
     375    #             This is case-sensitive.
     376    #
     377    # @note The registry format does inherently prevent multiple
     378    #       subkeys or values from having the same name. 
     379    #       This interface simply returns the first match. 
     380    #       Lookups using this method could also fail due to incorrectly
     381    #       encoded strings.
     382    #       To identify any duplicates, use the iterator interface to
     383    #       check every list element.
     384    #
    375385    # @return the first element whose name matches, or None if the element
    376386    #         could not be found
    377387    def __getitem__(self, name):
     388        # XXX: Consider interpreting integer names as offsets in the underlying list
    378389        index = ctypes.c_uint32()
    379390        if isinstance(name, str):
    … …  
    391402        raise KeyError('')
    392403
     404
     405    ## Fetches the requested element by name, or the default value if the lookup
     406    #  fails.
     407    #
    393408    def get(self, name, default):
    394409        try:
    … …  
    426441# @endcode
    427442#
    428 # @note SubkeyLists should never be accessed directly and only exist
    429 #       in association with a parent Key object.  Do not retain references to
    430 #       SubkeyLists.  Instead, access them via their parent Key at all times.
     443# You may also request the len() of a subkeys list.
     444# However keys(), values(), items() and similar methods are not currently
     445# implemented.
    431446class SubkeyList(_GenericList):
    432447    _fetch_num = regfi.regfi_fetch_num_subkeys
    … …  
    447462# @endcode
    448463#
    449 # @note ValueLists should never be accessed directly and only exist
    450 #       in association with a parent Key object.  Do not retain references to
    451 #       ValueLists.  Instead, access them via their parent Key at all times.
     464# You may also request the len() of a values list.
     465# However keys(), values(), items() and similar methods are not currently
     466# implemented.
    452467class ValueList(_GenericList):
    453468    _fetch_num = regfi.regfi_fetch_num_values
    … …  
    460475# access to their subkeys, values, and other metadata.
    461476#
    462 # @note Value instances may provide access to more than the attributes
     477# @note Key instances may provide access to more attributes than are
    463478#       documented here.  However, undocumented attributes may change over time
    464479#       and are not officially supported.  If you need access to an attribute
    465 #       not shown here, see pyregfi.structures.
     480#       not shown here, see @ref pyregfi.structures.
    466481class Key(_StructureWrapper):
    467482    ## A @ref ValueList object representing the list of Values
    … …  
    558573        return None
    559574
     575
     576    ## Checks to see if this Key is the root of its Hive
     577    #
     578    #  @return True if it is, False otherwise
    560579    def is_root(self):
    561580        return (self._hive.root == self)
    … …  
    567586# access to their associated data.
    568587#
    569 # @note Value instances may provide access to more than the attributes
     588# @note Value instances may provide access to more attributes than are
    570589#       documented here.  However, undocumented attributes may change over time
    571590#       and are not officially supported.  If you need access to an attribute
    572 #       not shown here, see pyregfi.structures.
     591#       not shown here, see @ref pyregfi.structures.
    573592class Value(_StructureWrapper):
    574593    ## The raw Value name as an uninterpreted bytearray

  • trunk/python/pyregfi/winsec.py

    r255 r257  
    9797
    9898## Represents a Microsoft access control entry, which are elements of access
    99 #  control lists
     99#  control lists.  For more information, see:
     100#    http://msdn.microsoft.com/en-us/library/aa374868%28v=vs.85%29.aspx
    100101#
    101102#  @note
    … …  
    136137
    137138
     139## A Microsoft security descriptor
     140# For more information, see:
     141#   http://msdn.microsoft.com/en-us/library/aa379563%28v=vs.85%29.aspx
     142#
    138143class SecurityDescriptor(object):
    139144    ## The security descriptor's owner SID, as a string
    … …  
    143148    group = "S-1-2-..."
    144149
    145     ## A list of @ref ACE objects which represents the System ACL
    146     # May be None if a sacl isn't defined
     150    ## The system access control list represented as a list of @ref ACE objects.
     151    #
     152    # Is set to None if a sacl isn't defined
    147153    sacl = []
    148154
    149     ## A list of @ref ACE objects which represents the User ACL
    150     # May be None if a dacl isn't defined
     155    ## The discretionary access control list represented as a list of @ref ACE objects
     156    #
     157    # Is set to None if a dacl isn't defined
    151158    dacl = []
    152159
    … …  
    160167        libc.free(c_str)
    161168
    162         # XXX: add checks for NULL pointers
    163169        self.sacl = None
    164170        if sec_desc.sacl:
Note: See TracChangeset for help on using the changeset viewer.