Index: trunk/include/regfi.h
===================================================================
--- trunk/include/regfi.h	(revision 257)
+++ trunk/include/regfi.h	(revision 258)
@@ -889,343 +889,4 @@
  * @param fd A file descriptor of an already open file.  Must be seekable.
  *
- * @return A reference to a newly allocated REGFI_FILE structure, if successful;
- *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-REGFI_FILE* regfi_alloc(int fd, REGFI_ENCODING output_encoding);
-
-
-/** Parses file headers returned by supplied callback functions.
- *
- * This interface is useful if you have a registry hive in memory
- * or have some other reason to emulate a real file.
- *
- * @param file_cb A structure defining the callback functions needed to access the file. 
- *
- * @return A reference to a newly allocated REGFI_FILE structure, if successful;
- *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-REGFI_FILE* regfi_alloc_cb(REGFI_RAW_FILE* file_cb,
-			   REGFI_ENCODING output_encoding);
-
-
-/** Frees a hive's data structures without closing the underlying file.
- *
- * @param file The registry structure to free.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-void regfi_free(REGFI_FILE* file);
-
-
-/** Get errors, warnings, and/or verbose information relating to processing of
- *  the given registry file.
- *
- * @return A newly allocated char* which must be free()d by the caller.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-char* regfi_log_get_str();
-
-
-/** Set the verbosity level of messages generated by the library for the 
- *  current thread.
- *
- * @param mask   An integer representing the types of messages desired.
- *               Acceptable values are created through bitwise ORs of 
- *               REGFI_LOG_* values.  For instance, if only errors and
- *               informational messages were desired (but not warnings),
- *               then one would specify: REGFI_LOG_ERROR|REGFI_LOG_INFO
- *               By default the message mask is: REGFI_LOG_ERROR|REGFI_LOG_WARN.
- *
- * @return       true on success and false on failure.  Failure occurs if 
- *               underlying pthread functions fail.  errno is set in this case.
- *
- * Message masks are set in a thread-specific way.  If one were to set a message
- * mask in one thread and then spawn a new thread, then the new thread will have
- * it's message mask reset to the default.  This function may be called at any 
- * time and will take effect immediately for the current thread.
- *
- * @note When a non-zero message mask is set, messages will
- *       accumulate in memory without limit if they are not fetched using
- *       @ref regfi_get_log_str and subsequently freed by the caller.  It is
- *       recommended that messsages be fetched after each regfi API call in
- *       order to provide the most context.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-bool regfi_log_set_mask(uint16_t mask);
-
-
-/** Fetches a hive's root key.
- *
- * @return Returns the root key or NULL on failure.  Key must be freed using
- *         @ref regfi_free_record.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_NK*       regfi_get_rootkey(REGFI_FILE* file);
-
-
-/** Frees a record previously returned by one of the API functions.
- *
- * @param file The file from which the record originated.  
- *             (This is needed for memory management reasons.)
- * 
- * @param record Any of the following record types: REGFI_NK, REGFI_VK, 
- *        REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
- *
- * @note The "const" in the record data type is a bit misleading and is there just for
- * convenience.  Since records returned previously must not be modified by users
- * of the API due to internal caching, these are returned as const, so this
- * function is const to make passing those records back easy.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-void regfi_free_record(REGFI_FILE* file, const void* record);
-
-
-/** Increments reference count on record
- *
- * Adds an extra internal reference to specified record, making it necessary to
- * call regfi_free_record on it an additional time before it is freed.  This is
- * useful in cases where multiple threads/structures need access to a shared record,
- * without requiring them to be in sync with when it is freed.
- *
- * @param file The file from which the record originated.  
- *             (This is needed for memory management reasons.)
- * 
- * @param record Any of the following record types: REGFI_NK, REGFI_VK, 
- *        REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
- *
- * @return Updated record pointer on success, NULL otherwise
- *
- * @note Be sure to use the returned record for further access to the structure
- *       instead of the previous version of the pointer.  E.g.:
- *       @code 
- *       myKey = (const REGFI_NK*)regfi_reference_record(myFile, myKey);
- *       @endcode
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const void* regfi_reference_record(REGFI_FILE* file, const void* record);
-
-
-/** Retrieves number of subkeys referenced by this key.
- *
- * Number of subkeyss in key structure and subkey list structure could differ,
- * so this provides a standard/sane way of determining the number.
- *
- * @param key  the key whose number of subkeys is desired
- *
- * @return Returns the number of subkeys referenced by this key.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-uint32_t regfi_fetch_num_subkeys(const REGFI_NK* key);
-
-
-/** Retrieves number of values referenced by this key.
- *
- * Number of values in key structure and value list structure could differ,
- * so this provides a standard/sane way of determining the number.
- *
- * @param key  the key whose number of values is desired
- *
- * @return Returns the number of values referenced by this key.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-uint32_t regfi_fetch_num_values(const REGFI_NK* key);
-
-
-/** Retrieves classname for a given key.
- *
- * @param file the file from which key is derived
- * @param key the key whose classname is desired
- *
- * @return Returns a newly allocated classname structure, or NULL on failure.
- *         Classname structures must be freed with @ref regfi_free_record.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_CLASSNAME* regfi_fetch_classname(REGFI_FILE* file, 
-					     const REGFI_NK* key);
-
-
-/** Returns the SK (security) record referenced by the supplied key.
- *
- * @param file the file from which key is derived
- * @param key  the key whose SK record is desired
- * 
- * @return A read-only SK structure, or NULL on failure.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_SK* regfi_fetch_sk(REGFI_FILE* file, const REGFI_NK* key);
-
-
-/** Returns the next SK (security) record referenced by the supplied SK record
- *
- * @param file the file from which sk is derived
- * @param sk   the SK record whose next sibling SK record is desired
- * 
- * @return A read-only SK structure, or NULL on failure.
- *
- * @note
- * SK records are included in a circular, doubly-linked list.
- * To iterate over all SK records, be sure to check for the repetition of
- * the SK record you started with to determine when all have been traversed.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_SK* regfi_next_sk(REGFI_FILE* file, const REGFI_SK* sk);
-
-
-/** Returns the previous SK (security) record referenced by the supplied SK record
- *
- * @param file the file from which sk is derived
- * @param sk   the SK record whose previous sibling SK record is desired
- * 
- * @return A read-only SK structure, or NULL on failure.
- *
- * @note
- * SK records are included in a circular, doubly-linked list.
- * To iterate over all SK records, be sure to check for the repetition of
- * the SK record you started with to determine when all have been traversed.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_SK* regfi_prev_sk(REGFI_FILE* file, const REGFI_SK* sk);
-
-
-/** Retrieves data for a given value.
- *
- * @param file the file from which value is derived
- * @param value the value whose data is desired
- *
- * @return Returns a newly allocated data structure, or NULL on failure.
- *         Data structures must be freed with @ref regfi_free_record.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_DATA* regfi_fetch_data(REGFI_FILE* file,
-				   const REGFI_VK* value);
-
-
-/** Locates a specific subkey of a given key.
- *
- * @param file  the file from which key is derived
- * @param key   the key whose subkey is desired
- * @param name  name of the desired subkey
- * @param index a return value: the index of the desired subkey.
- *              undefined on error
- *
- * @return true if the subkey is found, false if an error occurred or if the
- *         specified name could not be found. If an error occurs, messages
- *         will be written explaining the issue. (See regfi_log_get_str.)
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-bool regfi_find_subkey(REGFI_FILE* file, const REGFI_NK* key, 
-		       const char* name, uint32_t* index);
-
-
-/** Locates a specific value of a given key.
- *
- * @param file  the file from which key is derived
- * @param key   the key whose value is desired
- * @param name  name of the desired value
- * @param index a return value: the index of the desired value.  
- *              undefined on error
- *
- * @return true if the value is found, false if an error occurred or if the
- *         specified name could not be found. If an error occurs, messages
- *         will be written explaining the issue. (See regfi_log_get_str.)
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-bool regfi_find_value(REGFI_FILE* file, const REGFI_NK* key,
-		      const char* name, uint32_t* index);
-
-
-/** Retrieves a specific subkey of a given key.
- *
- * @param file  the file from which key is derived
- * @param key   the key whose subkey is desired
- * @param index the index of the desired subkey
- *
- * @return the requested subkey or NULL on error.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_NK* regfi_get_subkey(REGFI_FILE* file, const REGFI_NK* key, 
-				 uint32_t index);
-
-
-/** Retrieves a specific value of a given key.
- *
- * @param file  the file from which key is derived
- * @param key   the key whose value is desired
- * @param index the index of the desired value
- *
- * @return the requested value or NULL on error.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_VK* regfi_get_value(REGFI_FILE* file, const REGFI_NK* key, 
-				uint32_t index);
-
-
-
-/** Uses a key's parent_off reference to retrieve it's parent.
- *
- * @param file  the file from which key is derived
- * @param key   the key whose parent is desired
- *
- * @return the requested subkey or NULL on error.
- *
- * @ingroup regfiBase
- */
-_EXPORT()
-const REGFI_NK* regfi_get_parentkey(REGFI_FILE* file, const REGFI_NK* key);
-
-
-/******************************************************************************/
-/** 
- * @defgroup regfiIteratorLayer Iterator Layer: Primary regfi Library Interface
- *
- * This top layer of API functions provides an iterator interface which makes
- * traversing registry data structures easy in both single-threaded and 
- * multi-threaded scenarios.
- */
-/******************************************************************************/
-
-/** Creates a new iterator for the provided registry file.
- *
- * @param file The opened registry file the iterator should be created for.
- *
  * @param output_encoding Character encoding that strings should be returned in.
  *                        Only supply the REGFI_ENCODING_* constants, as others 
@@ -1236,4 +897,351 @@
  *                        REGFI_ENCODING_UTF8
  *
+ * @return A reference to a newly allocated REGFI_FILE structure, if successful;
+ *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+REGFI_FILE* regfi_alloc(int fd, REGFI_ENCODING output_encoding);
+
+
+/** Parses file headers returned by supplied callback functions.
+ *
+ * This interface is useful if you have a registry hive in memory
+ * or have some other reason to emulate a real file.
+ *
+ * @param file_cb A structure defining the callback functions needed to access the file. 
+ *
+ * @param output_encoding Character encoding that strings should be returned in.
+ *                        Only supply the REGFI_ENCODING_* constants, as others 
+ *                        will be rejected.
+ *                        The following values are currently accepted:
+ *                        REGFI_ENCODING_DEFAULT (currently REGFI_ENCODING_ASCII)
+ *                        REGFI_ENCODING_ASCII
+ *                        REGFI_ENCODING_UTF8
+ *
+ * @return A reference to a newly allocated REGFI_FILE structure, if successful;
+ *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+REGFI_FILE* regfi_alloc_cb(REGFI_RAW_FILE* file_cb,
+			   REGFI_ENCODING output_encoding);
+
+
+/** Frees a hive's data structures without closing the underlying file.
+ *
+ * @param file The registry structure to free.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+void regfi_free(REGFI_FILE* file);
+
+
+/** Get errors, warnings, and/or verbose information relating to processing of
+ *  the given registry file.
+ *
+ * @return A newly allocated char* which must be free()d by the caller.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+char* regfi_log_get_str();
+
+
+/** Set the verbosity level of messages generated by the library for the 
+ *  current thread.
+ *
+ * @param mask   An integer representing the types of messages desired.
+ *               Acceptable values are created through bitwise ORs of 
+ *               REGFI_LOG_* values.  For instance, if only errors and
+ *               informational messages were desired (but not warnings),
+ *               then one would specify: REGFI_LOG_ERROR|REGFI_LOG_INFO
+ *               By default the message mask is: REGFI_LOG_ERROR|REGFI_LOG_WARN.
+ *
+ * @return       true on success and false on failure.  Failure occurs if 
+ *               underlying pthread functions fail.  errno is set in this case.
+ *
+ * Message masks are set in a thread-specific way.  If one were to set a message
+ * mask in one thread and then spawn a new thread, then the new thread will have
+ * it's message mask reset to the default.  This function may be called at any 
+ * time and will take effect immediately for the current thread.
+ *
+ * @note When a non-zero message mask is set, messages will
+ *       accumulate in memory without limit if they are not fetched using
+ *       @ref regfi_log_get_str and subsequently freed by the caller.  It is
+ *       recommended that messsages be fetched after each regfi API call in
+ *       order to provide the most context.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+bool regfi_log_set_mask(uint16_t mask);
+
+
+/** Fetches a hive's root key.
+ *
+ * @return Returns the root key or NULL on failure.  Key must be freed using
+ *         @ref regfi_free_record.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_NK*       regfi_get_rootkey(REGFI_FILE* file);
+
+
+/** Frees a record previously returned by one of the API functions.
+ *
+ * @param file The file from which the record originated.  
+ *             (This is needed for memory management reasons.)
+ * 
+ * @param record Any of the following record types: REGFI_NK, REGFI_VK, 
+ *        REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
+ *
+ * @note The "const" in the record data type is a bit misleading and is there just for
+ * convenience.  Since records returned previously must not be modified by users
+ * of the API due to internal caching, these are returned as const, so this
+ * function is const to make passing those records back easy.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+void regfi_free_record(REGFI_FILE* file, const void* record);
+
+
+/** Increments reference count on record
+ *
+ * Adds an extra internal reference to specified record, making it necessary to
+ * call regfi_free_record on it an additional time before it is freed.  This is
+ * useful in cases where multiple threads/structures need access to a shared record,
+ * without requiring them to be in sync with when it is freed.
+ *
+ * @param file The file from which the record originated.  
+ *             (This is needed for memory management reasons.)
+ * 
+ * @param record Any of the following record types: REGFI_NK, REGFI_VK, 
+ *        REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.
+ *
+ * @return Updated record pointer on success, NULL otherwise
+ *
+ * @note Be sure to use the returned record for further access to the structure
+ *       instead of the previous version of the pointer.  E.g.:
+ *       @code 
+ *       myKey = (const REGFI_NK*)regfi_reference_record(myFile, myKey);
+ *       @endcode
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const void* regfi_reference_record(REGFI_FILE* file, const void* record);
+
+
+/** Retrieves number of subkeys referenced by this key.
+ *
+ * Number of subkeyss in key structure and subkey list structure could differ,
+ * so this provides a standard/sane way of determining the number.
+ *
+ * @param key  the key whose number of subkeys is desired
+ *
+ * @return Returns the number of subkeys referenced by this key.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+uint32_t regfi_fetch_num_subkeys(const REGFI_NK* key);
+
+
+/** Retrieves number of values referenced by this key.
+ *
+ * Number of values in key structure and value list structure could differ,
+ * so this provides a standard/sane way of determining the number.
+ *
+ * @param key  the key whose number of values is desired
+ *
+ * @return Returns the number of values referenced by this key.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+uint32_t regfi_fetch_num_values(const REGFI_NK* key);
+
+
+/** Retrieves classname for a given key.
+ *
+ * @param file the file from which key is derived
+ * @param key the key whose classname is desired
+ *
+ * @return Returns a newly allocated classname structure, or NULL on failure.
+ *         Classname structures must be freed with @ref regfi_free_record.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_CLASSNAME* regfi_fetch_classname(REGFI_FILE* file, 
+					     const REGFI_NK* key);
+
+
+/** Returns the SK (security) record referenced by the supplied key.
+ *
+ * @param file the file from which key is derived
+ * @param key  the key whose SK record is desired
+ * 
+ * @return A read-only SK structure, or NULL on failure.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_SK* regfi_fetch_sk(REGFI_FILE* file, const REGFI_NK* key);
+
+
+/** Returns the next SK (security) record referenced by the supplied SK record
+ *
+ * @param file the file from which sk is derived
+ * @param sk   the SK record whose next sibling SK record is desired
+ * 
+ * @return A read-only SK structure, or NULL on failure.
+ *
+ * @note
+ * SK records are included in a circular, doubly-linked list.
+ * To iterate over all SK records, be sure to check for the repetition of
+ * the SK record you started with to determine when all have been traversed.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_SK* regfi_next_sk(REGFI_FILE* file, const REGFI_SK* sk);
+
+
+/** Returns the previous SK (security) record referenced by the supplied SK record
+ *
+ * @param file the file from which sk is derived
+ * @param sk   the SK record whose previous sibling SK record is desired
+ * 
+ * @return A read-only SK structure, or NULL on failure.
+ *
+ * @note
+ * SK records are included in a circular, doubly-linked list.
+ * To iterate over all SK records, be sure to check for the repetition of
+ * the SK record you started with to determine when all have been traversed.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_SK* regfi_prev_sk(REGFI_FILE* file, const REGFI_SK* sk);
+
+
+/** Retrieves data for a given value.
+ *
+ * @param file the file from which value is derived
+ * @param value the value whose data is desired
+ *
+ * @return Returns a newly allocated data structure, or NULL on failure.
+ *         Data structures must be freed with @ref regfi_free_record.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_DATA* regfi_fetch_data(REGFI_FILE* file,
+				   const REGFI_VK* value);
+
+
+/** Locates a specific subkey of a given key.
+ *
+ * @param file  the file from which key is derived
+ * @param key   the key whose subkey is desired
+ * @param name  name of the desired subkey
+ * @param index a return value: the index of the desired subkey.
+ *              undefined on error
+ *
+ * @return true if the subkey is found, false if an error occurred or if the
+ *         specified name could not be found. If an error occurs, messages
+ *         will be written explaining the issue. (See regfi_log_get_str.)
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+bool regfi_find_subkey(REGFI_FILE* file, const REGFI_NK* key, 
+		       const char* name, uint32_t* index);
+
+
+/** Locates a specific value of a given key.
+ *
+ * @param file  the file from which key is derived
+ * @param key   the key whose value is desired
+ * @param name  name of the desired value
+ * @param index a return value: the index of the desired value.  
+ *              undefined on error
+ *
+ * @return true if the value is found, false if an error occurred or if the
+ *         specified name could not be found. If an error occurs, messages
+ *         will be written explaining the issue. (See regfi_log_get_str.)
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+bool regfi_find_value(REGFI_FILE* file, const REGFI_NK* key,
+		      const char* name, uint32_t* index);
+
+
+/** Retrieves a specific subkey of a given key.
+ *
+ * @param file  the file from which key is derived
+ * @param key   the key whose subkey is desired
+ * @param index the index of the desired subkey
+ *
+ * @return the requested subkey or NULL on error.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_NK* regfi_get_subkey(REGFI_FILE* file, const REGFI_NK* key, 
+				 uint32_t index);
+
+
+/** Retrieves a specific value of a given key.
+ *
+ * @param file  the file from which key is derived
+ * @param key   the key whose value is desired
+ * @param index the index of the desired value
+ *
+ * @return the requested value or NULL on error.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_VK* regfi_get_value(REGFI_FILE* file, const REGFI_NK* key, 
+				uint32_t index);
+
+
+
+/** Uses a key's parent_off reference to retrieve it's parent.
+ *
+ * @param file  the file from which key is derived
+ * @param key   the key whose parent is desired
+ *
+ * @return the requested subkey or NULL on error.
+ *
+ * @ingroup regfiBase
+ */
+_EXPORT()
+const REGFI_NK* regfi_get_parentkey(REGFI_FILE* file, const REGFI_NK* key);
+
+
+/******************************************************************************/
+/** 
+ * @defgroup regfiIteratorLayer Iterator Layer: Primary regfi Library Interface
+ *
+ * This top layer of API functions provides an iterator interface which makes
+ * traversing registry data structures easy in both single-threaded and 
+ * multi-threaded scenarios.
+ */
+/******************************************************************************/
+
+/** Creates a new iterator for the provided registry file.
+ *
+ * @param file The opened registry file the iterator should be created for.
+ *
  * @return A newly allocated REGFI_ITERATOR. 
  *         Must be free()d with regfi_iterator_free.
@@ -1487,6 +1495,6 @@
 _EXPORT()
 REGFI_VK* regfi_load_value(REGFI_FILE* file, uint32_t offset, 
-			       REGFI_ENCODING output_encoding, 
-			       bool strict);
+                           REGFI_ENCODING output_encoding, 
+                           bool strict);
 
 
