Changeset 232 for trunk/python/pyregfi/__init__.py

Timestamp:

04/28/11 12:45:10 (13 years ago)

Author:

tim

Message:

added a convenience openHive function in pyregfi
standardized static function names
improvements to scons release script and library versioning

File:

• trunk/python/pyregfi/__init__.py (modified) (13 diffs)

trunk/python/pyregfi/__init__.py

@@ -189 +189 @@
 # should be reported to the user.  Failure to retrieve these could result in 
 # excessive memory consumption.
-def GetLogMessages():
+def getLogMessages():
     msgs = regfi.regfi_log_get_str()
     if not msgs:
@@ -206 +206 @@
 # Example:
 # @code
-# SetLogMask((LOG_TYPES.ERROR, LOG_TYPES.WARN, LOG_TYPES.INFO))
+# setLogMask((LOG_TYPES.ERROR, LOG_TYPES.WARN, LOG_TYPES.INFO))
 # @endcode
 #
@@ -212 +212 @@
 # For more information, see @ref regfi_log_set_mask.
 #
-def SetLogMask(log_types):
+def setLogMask(log_types):
     mask = 0
     for m in log_types:
@@ -219 +219 @@
 
 
+## Opens a file as a registry hive
+#
+# @param path The file path of a hive, as one would provide to the 
+#             open() built-in
+#
+# @return A new Hive instance
+def openHive(path):
+    fh = open(path, 'rb')
+    return Hive(fh)
+
+
 ## Abstract class for most objects returned by the library
 class _StructureWrapper(object):
@@ -228 +239 @@
             raise Exception("Could not create _StructureWrapper,"
                             + " hive is NULL.  Current log:\n"
-                            + GetLogMessages())
+                            + getLogMessages())
         if not base:
             raise Exception("Could not create _StructureWrapper,"
                             + " base is NULL.  Current log:\n"
-                            + GetLogMessages())
+                            + getLogMessages())
         self._hive = hive
         self._base = base
@@ -297 +308 @@
         if not key:
             raise Exception("Could not create _GenericList; key is NULL."
-                            + "Current log:\n" + GetLogMessages())
+                            + "Current log:\n" + getLogMessages())
         
         if not regfi.regfi_reference_record(key._hive.file, key._base):
             raise Exception("Could not create _GenericList; memory error."
-                            + "Current log:\n" + GetLogMessages())
+                            + "Current log:\n" + getLogMessages())
         self._key_base = key._base
         self._length = self._fetch_num(self._key_base)
@@ -650 +661 @@
     minor_version = 5
 
-    # XXX: Possibly add a second or factory function which opens a 
-    #      hive file for you
-
     ## Constructor
+    #
+    # Initialize a new Hive based on a Python file object.  To open a file by 
+    # path, see @ref openHive.
     #
     # @param fh A Python file object.  The constructor first looks for a valid
@@ -660 +671 @@
     #           access.
     #
-    # @note Supplied file must be seekable
+    # @note Supplied file must be seekable.  Do not perform any operation on
+    #       the provided file object while a Hive is using it.  Do not 
+    #       construct multiple Hive instances from the same file object.
+    #       If a file must be accessed by separate code and pyregfi 
+    #       simultaneously, use a separate file descriptor.  Hives are 
+    #       thread-safe, so multiple threads may use a single Hive object.
     def __init__(self, fh):
         # The fileno method may not exist, or it may throw an exception
@@ -678 +694 @@
                 # XXX: switch to non-generic exception
                 raise Exception("Could not open registry file.  Current log:\n"
-                                + GetLogMessages())
+                                + getLogMessages())
         else:
             fh.seek(0)
@@ -689 +705 @@
                 # XXX: switch to non-generic exception
                 raise Exception("Could not open registry file.  Current log:\n"
-                                + GetLogMessages())
+                                + getLogMessages())
 
 
@@ -753 +769 @@
         if not self._iter:
             raise Exception("Could not create iterator.  Current log:\n"
-                            + GetLogMessages())
+                            + getLogMessages())
         self._hive = hive
         self._lock = threading.RLock()
@@ -797 +813 @@
                 self._lock.release()
                 raise Exception('Error traversing iterator downward.'+
-                                ' Current log:\n'+ GetLogMessages())
+                                ' Current log:\n'+ getLogMessages())
 
         regfi.regfi_iterator_first_subkey(self._iter)
@@ -977 +993 @@
         if not result:
             # XXX: Use non-generic exception
-            raise Exception('Could not locate path.\n'+GetLogMessages())
+            raise Exception('Could not locate path.\n'+getLogMessages())