Changeset 185 for trunk/include/regfi.h


Ignore:
Timestamp:
03/22/10 22:22:07 (14 years ago)
Author:
tim
Message:

reworked logging API again to simplify interface

updated regfi-threadtest to work with more recent commits

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/regfi.h

    r184 r185  
    4848 *
    4949 * Most users will find that a combination of the Base Layer and the Iterator Layer
    50  * will be sufficient for accessing registry hive files.  Those who are wiling
     50 * will be sufficient for accessing registry hive files.  Those who are willing
    5151 * to dive deep into registry data structures, for instance to recover deleted
    5252 * data structures or to research Windows registry behavior in detail, will
    … …  
    7979
    8080
     81
     82
    8183/******************************************************************************/
    8284/* Constants for use while interacting with the library                       */
    … …  
    8789#define REGFI_LOG_WARN  0x0004
    8890#define REGFI_LOG_ERROR 0x0010
     91#define REGFI_DEFAULT_LOG_MASK REGFI_LOG_ERROR|REGFI_LOG_WARN
    8992
    9093typedef uint8_t REGFI_ENCODING;
    … …  
    146149
    147150/* Global thread-local storage key */
    148 pthread_key_t REGFI_LOG_KEY;
     151pthread_key_t regfi_log_key;
    149152
    150153/* Header sizes and magic number lengths for various records */
    … …  
    877880
    878881
    879 /** Enables regfi library logging for the current thread.
    880  *
    881  * XXX: finish documenting
    882  *
    883  * @ingroup regfiBase
    884  */
    885 void regfi_log_start(uint16_t mask);
    886 
    887 
    888882/** Get errors, warnings, and/or verbose information relating to processing of
    889883 *  the given registry file.
    … …  
    896890
    897891
    898 /** Set the verbosity level of errors and warnings generated by the library
    899  *  (as accessible via regfi_get_messages).
    900  *
    901  * This may be called at any time and will take effect immediately.
    902  *
    903  * @param mask   an integer representing the types of messages desired.
     892/** Set the verbosity level of messages generated by the library for the
     893 *  current thread.
     894 *
     895 * @param mask   An integer representing the types of messages desired.
    904896 *               Acceptable values are created through bitwise ORs of
    905  *               REGFI_MSG_* values.  For instance, if only errors and
     897 *               REGFI_LOG_* values.  For instance, if only errors and
    906898 *               informational messages were desired (but not warnings),
    907  *               then one would specify: REGFI_MSG_ERROR|REGFI_MSG_INFO
    908  *               New REGFI_FILE structures are created with:
    909  *                REGFI_MSG_ERROR|REGFI_MSG_WARN
    910  *               Note that error and warning messages will continue to
    911  *               accumulate in memory if they are not fetched using
    912  *               regfi_get_messages and then freed by the caller.
    913  *               To disable error messages entirely, supply 0, which
    914  *               will prevent message accumulation. 
     899 *               then one would specify: REGFI_LOG_ERROR|REGFI_LOG_INFO
     900 *               By default the message mask is: REGFI_LOG_ERROR|REGFI_LOG_WARN.
     901 *
     902 * @return       true on success and false on failure.  Failure occurs if
     903 *               underlying pthread functions fail.  errno is set in this case.
     904 *
     905 * Message masks are set in a thread-specific way.  If one were to set a message
     906 * mask in one thread and then spawn a new thread, then the new thread will have
     907 * it's message mask reset to the default.  This function may be called at any
     908 * time and will take effect immediately for the current thread.
     909 *
     910 * @note When a non-zero message mask is set, messages will
     911 *       accumulate in memory without limit if they are not fetched using
     912 *       @ref regfi_get_log_str and subsequently freed by the caller.  It is
     913 *       recommended that messsages be fetched after each regfi API call in
     914 *       order to provide the most context.
    915915 *
    916916 * @ingroup regfiBase
    917917 */
    918 void regfi_log_set_mask(uint16_t mask);
    919 
    920 
    921 /** Disables regfi library logging for the current thread.
    922  *
    923  * XXX: finish documenting
    924  *
    925  * @ingroup regfiBase
    926  */
    927 void regfi_log_stop();
     918bool regfi_log_set_mask(uint16_t mask);
    928919
    929920
    … …  
    10771068 *         subkey, or NULL on failure.  Failure may be due to a lack of any
    10781069 *         subkeys or other errors.  Newly allocated keys must be freed with
    1079  *         regfi_free_record.
     1070 *         @ref regfi_free_record.
    10801071 *
    10811072 * @ingroup regfiIteratorLayer
    … …  
    10901081 * @return A newly allocated key structure for the currently referenced subkey,
    10911082 *         or NULL on failure.  Newly allocated keys must be freed with
    1092  *         regfi_free_record.
     1083 *         @ref regfi_free_record.
    10931084 *
    10941085 * @ingroup regfiIteratorLayer
    … …  
    11031094 *
    11041095 * @return A newly allocated key structure for the next subkey or NULL on
    1105  *         failure.  Newly allocated keys must be freed with regfi_free_record.
     1096 *         failure.  Newly allocated keys must be freed with
     1097 *         @ref regfi_free_record.
    11061098 *
    11071099 * @ingroup regfiIteratorLayer
    … …  
    11321124 *          value, or NULL on failure.  Failure may be due to a lack of any
    11331125 *          values or other errors.  Newly allocated keys must be freed with
    1134  *          regfi_free_record.
     1126 *          @ref regfi_free_record.
    11351127 *
    11361128 * @ingroup regfiIteratorLayer
    … …  
    11451137 * @return A newly allocated value structure for the currently referenced value,
    11461138 *         or NULL on failure.  Newly allocated values must be freed with
    1147  *         regfi_free_record.
     1139 *         @ref regfi_free_record.
    11481140 *
    11491141 * @ingroup regfiIteratorLayer
    … …  
    11581150 *
    11591151 * @return  A newly allocated key structure for the next value or NULL on
    1160  *          failure.  Newly allocated keys must be freed with regfi_free_record.
     1152 *          failure.  Newly allocated keys must be freed with
     1153 *          @ref regfi_free_record.
    11611154 *
    11621155 * @ingroup regfiIteratorLayer
    … …  
    11851178 *
    11861179 * @return Returns a newly allocated classname structure, or NULL on failure.
    1187  *         Classname structures must be freed with regfi_free_record.
     1180 *         Classname structures must be freed with @ref regfi_free_record.
    11881181 *
    11891182 * @ingroup regfiIteratorLayer
    … …  
    11991192 *
    12001193 * @return Returns a newly allocated data structure, or NULL on failure.
    1201  *         Data structures must be freed with regfi_free_record.
     1194 *         Data structures must be freed with @ref regfi_free_record.
    12021195 *
    12031196 * @ingroup regfiIteratorLayer
Note: See TracChangeset for help on using the changeset viewer.