Index: trunk/include/regfi.h
===================================================================
--- trunk/include/regfi.h	(revision 182)
+++ trunk/include/regfi.h	(revision 184)
@@ -78,4 +78,7 @@
 #include "lru_cache.h"
 
+
+/******************************************************************************/
+/* Constants for use while interacting with the library                       */
 /******************************************************************************/
 
@@ -84,7 +87,4 @@
 #define REGFI_LOG_WARN  0x0004
 #define REGFI_LOG_ERROR 0x0010
-
-/* For internal use */
-pthread_key_t REGFI_LOG_KEY;
 
 typedef uint8_t REGFI_ENCODING;
@@ -119,4 +119,12 @@
 
 
+
+/******************************************************************************/
+/* Various resource limits and related constants                              */
+/******************************************************************************/
+
+/* Flags determining whether or not to cache various record types internally */
+#define REGFI_CACHE_SK             0
+
 /* This maximum depth is described here:
  * http://msdn.microsoft.com/en-us/library/ms724872%28VS.85%29.aspx
@@ -132,4 +140,11 @@
 #define REGFI_MAX_SUBKEY_DEPTH     255
 
+
+/******************************************************************************/
+/* Symbols for internal use                                                   */
+/******************************************************************************/
+
+/* Global thread-local storage key */
+pthread_key_t REGFI_LOG_KEY;
 
 /* Header sizes and magic number lengths for various records */
@@ -236,4 +251,10 @@
 #define TIME_FIXUP_CONSTANT (369.0*365.25*24*60*60-(3.0*24*60*60+6.0*60*60))
 
+
+
+/******************************************************************************/
+/* Structures                                                                 */
+/******************************************************************************/
+
 typedef struct _regfi_nttime
 {
@@ -825,5 +846,5 @@
  *
  * @return A reference to a newly allocated REGFI_FILE structure, if successful;
- *         NULL on error.
+ *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
  *
  * @ingroup regfiBase
@@ -840,5 +861,5 @@
  *
  * @return A reference to a newly allocated REGFI_FILE structure, if successful;
- *         NULL on error.
+ *         NULL on error.  Use regfi_free to free the returned REGFI_FILE.
  *
  * @ingroup regfiBase
@@ -909,21 +930,17 @@
 /* Dispose of previously parsed records */
 
-/** Frees a key structure previously returned by one of the API functions
- *
- * XXX: finish documenting
+/** Frees a record previously returned by one of the API functions.
+ *
+ * Can be used to free REGFI_NK_REC, REGFI_VK_REC, REGFI_SK_REC, REGFI_DATA, and
+ * REGFI_CLASSNAME records.
+ *
+ * @note The "const" in the 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 back in easy.
  *
  * @ingroup regfiBase
  */
-void                  regfi_free_key(REGFI_NK_REC* nk);
-
-
-/** Frees a value structure previously returned by one of the API functions
- *
- * XXX: finish documenting
- *
- * @ingroup regfiBase
- */
-void                  regfi_free_value(REGFI_VK_REC* vk);
-
+void regfi_free_record(const void* record);
 
 
@@ -1038,5 +1055,5 @@
  * @ingroup regfiIteratorLayer
  */
-const REGFI_NK_REC*   regfi_iterator_cur_key(REGFI_ITERATOR* i);
+const REGFI_NK_REC* regfi_iterator_cur_key(REGFI_ITERATOR* i);
 
 
@@ -1049,5 +1066,5 @@
  * @ingroup regfiIteratorLayer
  */
-const REGFI_SK_REC*   regfi_iterator_cur_sk(REGFI_ITERATOR* i);
+const REGFI_SK_REC* regfi_iterator_cur_sk(REGFI_ITERATOR* i);
 
 
@@ -1060,9 +1077,9 @@
  *         subkey, or NULL on failure.  Failure may be due to a lack of any
  *         subkeys or other errors.  Newly allocated keys must be freed with
- *         regfi_free_key.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_NK_REC*         regfi_iterator_first_subkey(REGFI_ITERATOR* i);
+ *         regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_NK_REC* regfi_iterator_first_subkey(REGFI_ITERATOR* i);
 
 
@@ -1073,9 +1090,9 @@
  * @return A newly allocated key structure for the currently referenced subkey,
  *         or NULL on failure.  Newly allocated keys must be freed with 
- *         regfi_free_key.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_NK_REC*         regfi_iterator_cur_subkey(REGFI_ITERATOR* i);
+ *         regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_NK_REC* regfi_iterator_cur_subkey(REGFI_ITERATOR* i);
 
 
@@ -1086,9 +1103,9 @@
  *
  * @return A newly allocated key structure for the next subkey or NULL on
- *         failure.  Newly allocated keys must be freed with regfi_free_key.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_NK_REC*         regfi_iterator_next_subkey(REGFI_ITERATOR* i);
+ *         failure.  Newly allocated keys must be freed with regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_NK_REC* regfi_iterator_next_subkey(REGFI_ITERATOR* i);
 
 
@@ -1104,6 +1121,6 @@
  * @ingroup regfiIteratorLayer
  */
-bool                  regfi_iterator_find_subkey(REGFI_ITERATOR* i, 
-						 const char* subkey_name);
+bool regfi_iterator_find_subkey(REGFI_ITERATOR* i, const char* subkey_name);
+
 
 /** Sets the internal value index to the first value referenced by the current
@@ -1115,9 +1132,9 @@
  *          value, or NULL on failure.  Failure may be due to a lack of any
  *          values or other errors.  Newly allocated keys must be freed with
- *          regfi_free_value.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_VK_REC*         regfi_iterator_first_value(REGFI_ITERATOR* i);
+ *          regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_VK_REC* regfi_iterator_first_value(REGFI_ITERATOR* i);
 
 
@@ -1128,9 +1145,9 @@
  * @return A newly allocated value structure for the currently referenced value,
  *         or NULL on failure.  Newly allocated values must be freed with 
- *         regfi_free_value.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_VK_REC*         regfi_iterator_cur_value(REGFI_ITERATOR* i);
+ *         regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_VK_REC* regfi_iterator_cur_value(REGFI_ITERATOR* i);
 
 
@@ -1141,9 +1158,9 @@
  *
  * @return  A newly allocated key structure for the next value or NULL on 
- *          failure.  Newly allocated keys must be freed with regfi_free_value.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_VK_REC*         regfi_iterator_next_value(REGFI_ITERATOR* i);
+ *          failure.  Newly allocated keys must be freed with regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_VK_REC* regfi_iterator_next_value(REGFI_ITERATOR* i);
 
 
@@ -1168,10 +1185,10 @@
  *
  * @return Returns a newly allocated classname structure, or NULL on failure.
- *         Classname structures must be freed with regfi_free_classname.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_CLASSNAME*      regfi_iterator_fetch_classname(REGFI_ITERATOR* i, 
-						     const REGFI_NK_REC* key);
+ *         Classname structures must be freed with regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_CLASSNAME* regfi_iterator_fetch_classname(REGFI_ITERATOR* i, 
+						      const REGFI_NK_REC* key);
 
 
@@ -1182,10 +1199,10 @@
  *
  * @return Returns a newly allocated data structure, or NULL on failure.
- *         Data structures must be freed with regfi_free_data.
- *
- * @ingroup regfiIteratorLayer
- */
-REGFI_DATA*           regfi_iterator_fetch_data(REGFI_ITERATOR* i, 
-						const REGFI_VK_REC* value);
+ *         Data structures must be freed with regfi_free_record.
+ *
+ * @ingroup regfiIteratorLayer
+ */
+const REGFI_DATA* regfi_iterator_fetch_data(REGFI_ITERATOR* i,
+					    const REGFI_VK_REC* value);
 
 
@@ -1276,21 +1293,4 @@
 					   uint32_t type, REGFI_DATA* data);
 
-
-/** Frees the memory associated with a REGFI_CLASSNAME data structure.
- *
- * XXX: finish documenting
- *
- * @ingroup regfiGlueLayer
- */
-void                  regfi_free_classname(REGFI_CLASSNAME* classname);
-
-
-/** Frees the memory associated with a REGFI_DATA data structure.
- *
- * XXX: finish documenting
- *
- * @ingroup regfiGlueLayer
- */
-void                  regfi_free_data(REGFI_DATA* data);
 
 
@@ -1434,5 +1434,4 @@
 REGFI_NK_REC*         regfi_rootkey(REGFI_FILE* file, 
 				    REGFI_ENCODING output_encoding);
-void                  regfi_subkeylist_free(REGFI_SUBKEY_LIST* list);
 
 off_t                 regfi_raw_seek(REGFI_RAW_FILE* self, 
