Changeset 166 for trunk/include/regfi.h

Timestamp:

12/15/09 22:18:05 (14 years ago)

Author:

tim

Message:

fixed a bug in big data parsing
broke up some of REGFI_FILE initialization
started added more regfi API documentation

File:

• trunk/include/regfi.h (modified) (4 diffs)

trunk/include/regfi.h

@@ -519 +519 @@
 /*                         Main iterator API                                  */
 /******************************************************************************/
+
+/* regfi_open: Attempts to open a registry hive and allocate related data
+ *             structures.
+ *
+ * Arguments:
+ *   filename -- A string containing the relative or absolute path of the
+ *               registry hive to be opened.
+ *
+ * Returns:
+ *   A reference to a newly allocated REGFI_FILE structure, if successful. 
+ *   NULL on error.
+ */
 REGFI_FILE*           regfi_open(const char* filename);
-int                   regfi_close(REGFI_FILE* r);
+
+
+/* regfi_alloc: Parses file headers of an already open registry hive file and 
+ *              allocates related structures for further parsing.
+ *
+ * Arguments:
+ *   fd       -- A file descriptor of an already open file.  Must be seekable.
+ *
+ * Returns:
+ *   A reference to a newly allocated REGFI_FILE structure, if successful. 
+ *   NULL on error.
+ */
+REGFI_FILE*           regfi_alloc(int fd);
+
+
+/* regfi_close: Closes and frees an open registry hive.
+ *
+ * Arguments:
+ *   file     -- The registry structure to close.
+ *
+ * Returns:
+ *   0 on success, -1 on failure with errno set.  
+ *   errno codes are similar to those of close(2).
+ */
+int                   regfi_close(REGFI_FILE* file);
+
+
+/* regfi_free: Frees a hive's data structures without closing the underlying
+ *             file.
+ *
+ * Arguments:
+ *   file     -- The registry structure to free.
+ */
+void                  regfi_free(REGFI_FILE* file);
+
 
 /* regfi_get_messages: Get errors, warnings, and/or verbose information
@@ -533 +579 @@
 char*                 regfi_get_messages(REGFI_FILE* file);
 
+
+/* regfi_set_message_mask: Set the verbosity level of errors and warnings
+ *                         generated by the library 
+ *                         (as accessible via regfi_get_messages).
+ *
+ * Arguments:
+ *   file     -- the structure for the registry file
+ *   mask     -- an integer representing the types of messages desired.
+ *               Acceptable values are created through bitwise ORs of 
+ *               REGFI_MSG_* values.  For instance, if only errors and
+ *               informational messages were desired (but not warnings),
+ *               then one would specify: REGFI_MSG_ERROR|REGFI_MSG_INFO
+ *               New REGFI_FILE structures are created with:
+ *                REGFI_MSG_ERROR|REGFI_MSG_WARN
+ *               Note that error and warning messages will continue to
+ *               accumulate in memory if they are not fetched using
+ *               regfi_get_messages and then freed by the caller.
+ *               To disable error messages entirely, supply 0, which
+ *               will prevent message accumulation.  
+ *
+ * This may be called at any time and will take effect immediately.
+ */
 void                  regfi_set_message_mask(REGFI_FILE* file, uint16 mask);
 
@@ -549 +617 @@
  *                      REGFI_ENCODING_UTF8
  *
- *                      XXX: This encoding only applies to specific data 
- *                           strings currently, but should apply to key 
- *                           names and value names in the future.
- *
  * Returns:
  *   A newly allocated REGFI_ITERATOR. Must be free()d with regfi_iterator_free.
@@ -558 +622 @@
 REGFI_ITERATOR*       regfi_iterator_new(REGFI_FILE* file,
                                          REGFI_ENCODING output_encoding);
+
+
+/* regfi_iterator_free: Frees a registry file iterator previously created by 
+ *                      regfi_iterator_new.
+ *
+ * This does not affect the underlying registry file's allocation status.
+ *
+ * Arguments:
+ *   file            -- the iterator to be freed
+ */
 void                  regfi_iterator_free(REGFI_ITERATOR* i);
+
+
+/* regfi_iterator_down: Traverse deeper into the registry tree at the
+ *                      current subkey.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   true on success, false on failure.  Note that subkey and value indexes
+ *   are preserved.  That is, if a regfi_iterator_up call occurs later
+ *   (reversing the effect of this call) then the subkey and value referenced
+ *   prior to the regfi_iterator_down call will still be referenced.  This 
+ *   makes depth-first iteration particularly easy.
+ */
 bool                  regfi_iterator_down(REGFI_ITERATOR* i);
+
+
+/* regfi_iterator_up: Traverse up to the current key's parent key.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   true on success, false on failure.  Any subkey or value state
+ *   associated with the current key is lost.
+ */
 bool                  regfi_iterator_up(REGFI_ITERATOR* i);
+
+
+/* regfi_iterator_to_root: Traverse up to the root key of the hive.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   true on success, false on failure.
+ */
 bool                  regfi_iterator_to_root(REGFI_ITERATOR* i);
 
+
+/* regfi_iterator_walk_path: Traverse down multiple levels in the registry hive.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *   path         -- a list of key names representing the path.  This list must
+ *                   contain NUL terminated strings.  The list itself is
+ *                   terminated with a NULL pointer.  All path elements must be
+ *                   keys; value names are not accepted (even as the last
+ *                   element).
+ *
+ * XXX: This currently only accepts ASCII key names.  Need to look into
+ *      accepting other encodings.
+ *
+ * Returns:
+ *   true on success, false on failure.  If any element of path is not found,
+ *   false will be returned and the iterator will remain in its original
+ *   position.
+ */
 bool                  regfi_iterator_walk_path(REGFI_ITERATOR* i, 
                                                const char** path);
+
+
+/* regfi_iterator_cur_key: Returns the currently referenced key.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   A read-only key structure for the current key, or NULL on failure.
+ */
 const REGFI_NK_REC*   regfi_iterator_cur_key(REGFI_ITERATOR* i);
+
+
+/* regfi_iterator_cur_sk: Returns the SK (security) record referenced by the 
+ *                        current key.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   A read-only SK structure, or NULL on failure.
+ */
 const REGFI_SK_REC*   regfi_iterator_cur_sk(REGFI_ITERATOR* i);
 
+
+/* regfi_iterator_first_subkey: Sets the internal subkey index to the first
+ *                              subkey referenced by the current key.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   A read-only key structure for the newly referenced first subkey, 
+ *   or NULL on failure.  Failure may be due to a lack of any subkeys or other
+ *   errors.
+ */
 REGFI_NK_REC*         regfi_iterator_first_subkey(REGFI_ITERATOR* i);
+
+
+/* regfi_iterator_cur_subkey: Returns the currently indexed subkey.
+ *
+ * Arguments:
+ *   i            -- the iterator
+ *
+ * Returns:
+ *   A newly allocated key structure for the currently referenced subkey,
+ *   or NULL on failure.  Newly allocated keys must be freed with 
+ *   regfi_free_key.
+ */
 REGFI_NK_REC*         regfi_iterator_cur_subkey(REGFI_ITERATOR* i);
 REGFI_NK_REC*         regfi_iterator_next_subkey(REGFI_ITERATOR* i);