Base Layer: Essential Functions and Data Structures

These functions are either necessary for normal use of the regfi API or just don't fit particularly well in any of the other layers. More...

## Data Structures

struct | REGFI_CLASSNAME
| Class name structure (used in storing SysKeys) More...
struct | REGFI_DATA
| Data record structure. More...
struct | REGFI_VK
| Value structure. More...
struct | REGFI_SK
| Security structure. More...
struct | REGFI_NK
| Key structure. More...
struct | REGFI_FILE
| Registry hive file data structure. More...

## Functions

const char * | regfi_version ()
| Returns the current regfi library version. More...
REGFI_FILE * | regfi_alloc (int fd, REGFI_ENCODING output_encoding)
| Parses file headers of an already open registry hive file and allocates related structures for further parsing. More...
REGFI_FILE * | regfi_alloc_cb (REGFI_RAW_FILE *file_cb, REGFI_ENCODING output_encoding)
| Parses file headers returned by supplied callback functions. More...
void | regfi_free (REGFI_FILE *file)
| Frees a hive's data structures without closing the underlying file. More...
char * | regfi_log_get_str ()
| Get errors, warnings, and/or verbose information relating to processing of the given registry file. More...
bool | regfi_log_set_mask (uint16_t mask)
| Set the verbosity level of messages generated by the library for the current thread. More...
const REGFI_NK * | regfi_get_rootkey (REGFI_FILE *file)
| Fetches a hive's root key. More...
void | regfi_free_record (REGFI_FILE *file, const void *record)
| Frees a record previously returned by one of the API functions. More...
const void * | regfi_reference_record (REGFI_FILE *file, const void *record)
| Increments reference count on record. More...
uint32_t | regfi_fetch_num_subkeys (const REGFI_NK *key)
| Retrieves number of subkeys referenced by this key. More...
uint32_t | regfi_fetch_num_values (const REGFI_NK *key)
| Retrieves number of values referenced by this key. More...
const REGFI_CLASSNAME * | regfi_fetch_classname (REGFI_FILE *file, const REGFI_NK *key)
| Retrieves classname for a given key. More...
const REGFI_SK * | regfi_fetch_sk (REGFI_FILE *file, const REGFI_NK *key)
| Returns the SK (security) record referenced by the supplied key. More...
const REGFI_SK * | regfi_next_sk (REGFI_FILE *file, const REGFI_SK *sk)
| Returns the next SK (security) record referenced by the supplied SK record. More...
const REGFI_SK * | regfi_prev_sk (REGFI_FILE *file, const REGFI_SK *sk)
| Returns the previous SK (security) record referenced by the supplied SK record. More...
const REGFI_DATA * | regfi_fetch_data (REGFI_FILE *file, const REGFI_VK *value)
| Retrieves data for a given value. More...
bool | regfi_find_subkey (REGFI_FILE *file, const REGFI_NK *key, const char *name, uint32_t *index)
| Locates a specific subkey of a given key. More...
bool | regfi_find_value (REGFI_FILE *file, const REGFI_NK *key, const char *name, uint32_t *index)
| Locates a specific value of a given key. More...
const REGFI_NK * | regfi_get_subkey (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
| Retrieves a specific subkey of a given key. More...
const REGFI_VK * | regfi_get_value (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
| Retrieves a specific value of a given key. More...
const REGFI_NK * | regfi_get_parentkey (REGFI_FILE *file, const REGFI_NK *key)
| Uses a key's parent_off reference to retrieve it's parent. More...

## Detailed Description

These functions are either necessary for normal use of the regfi API or just don't fit particularly well in any of the other layers.

## Function Documentation

## regfi_version()

const char* regfi_version | ( |  | ) |

Returns the current regfi library version.

Returns
  A string indicating the version.

## regfi_alloc()

REGFI_FILE* regfi_alloc | ( | int | fd,
|  | REGFI_ENCODING | output_encoding
| ) |  |

Parses file headers of an already open registry hive file and allocates related structures for further parsing.

Parameters

  fd | A file descriptor of an already open file. Must be seekable.
  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

Returns
  A reference to a newly allocated REGFI_FILE structure, if successful; NULL on error. Use regfi_free to free the returned REGFI_FILE.

## regfi_alloc_cb()

REGFI_FILE* regfi_alloc_cb | ( | REGFI_RAW_FILE * | file_cb,
|  | 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.

Parameters

  file_cb | A structure defining the callback functions needed to access the file.
  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

Returns
  A reference to a newly allocated REGFI_FILE structure, if successful; NULL on error. Use regfi_free to free the returned REGFI_FILE.

## regfi_free()

void regfi_free | ( | REGFI_FILE * | file | ) |

Frees a hive's data structures without closing the underlying file.

Parameters

  file | The registry structure to free.

## regfi_log_get_str()

char* regfi_log_get_str | ( |  | ) |

Get errors, warnings, and/or verbose information relating to processing of the given registry file.

Returns
  A newly allocated char* which must be free()d by the caller.

## regfi_log_set_mask()

bool regfi_log_set_mask | ( | uint16_t | mask | ) |

Set the verbosity level of messages generated by the library for the current thread.

Parameters

  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.

Returns
  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 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.

## regfi_get_rootkey()

const REGFI_NK* regfi_get_rootkey | ( | REGFI_FILE * | file | ) |

Fetches a hive's root key.

Returns
  Returns the root key or NULL on failure. Key must be freed using regfi_free_record.

## regfi_free_record()

void regfi_free_record | ( | REGFI_FILE * | file,
|  | const void * | record
| ) |  |

Frees a record previously returned by one of the API functions.

Parameters

  file | The file from which the record originated. (This is needed for memory management reasons.)
  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.

Referenced by regfi_find_subkey(), regfi_find_value(), and regfi_iterator_down().

## regfi_reference_record()

const void* regfi_reference_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.

Parameters

  file | The file from which the record originated. (This is needed for memory management reasons.)
  record | Any of the following record types: REGFI_NK, REGFI_VK, REGFI_SK, REGFI_DATA, and REGFI_CLASSNAME records.

Returns
  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.:
  myKey = (const REGFI_NK*)regfi_reference_record(myFile, myKey);

## regfi_fetch_num_subkeys()

uint32_t regfi_fetch_num_subkeys | ( | const REGFI_NK * | key | ) |

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.

Parameters

  key | the key whose number of subkeys is desired

Returns
  Returns the number of subkeys referenced by this key.

References REGFI_NK::num_subkeys, and REGFI_NK::subkeys.

Referenced by regfi_find_subkey(), and regfi_get_subkey().

## regfi_fetch_num_values()

uint32_t regfi_fetch_num_values | ( | 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.

Parameters

  key | the key whose number of values is desired

Returns
  Returns the number of values referenced by this key.

References REGFI_NK::num_values, and REGFI_NK::values.

Referenced by regfi_find_value(), and regfi_get_value().

## regfi_fetch_classname()

const REGFI_CLASSNAME* regfi_fetch_classname | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key
| ) |  |

Retrieves classname for a given key.

Parameters

  file | the file from which key is derived
  key | the key whose classname is desired

Returns
  Returns a newly allocated classname structure, or NULL on failure. Classname structures must be freed with regfi_free_record.

References REGFI_NK::classname_off.

## regfi_fetch_sk()

const REGFI_SK* regfi_fetch_sk | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key
| ) |  |

Returns the SK (security) record referenced by the supplied key.

Parameters

  file | the file from which key is derived
  key | the key whose SK record is desired

Returns
  A read-only SK structure, or NULL on failure.

References REGFI_NK::sk_off.

## regfi_next_sk()

const REGFI_SK* regfi_next_sk | ( | REGFI_FILE * | file,
|  | const REGFI_SK * | sk
| ) |  |

Returns the next SK (security) record referenced by the supplied SK record.

Parameters

  file | the file from which sk is derived
  sk | the SK record whose next sibling SK record is desired

Returns
  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.

References REGFI_SK::next_sk_off.

## regfi_prev_sk()

const REGFI_SK* regfi_prev_sk | ( | REGFI_FILE * | file,
|  | const REGFI_SK * | sk
| ) |  |

Returns the previous SK (security) record referenced by the supplied SK record.

Parameters

  file | the file from which sk is derived
  sk | the SK record whose previous sibling SK record is desired

Returns
  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.

References REGFI_SK::prev_sk_off.

## regfi_fetch_data()

const REGFI_DATA* regfi_fetch_data | ( | REGFI_FILE * | file,
|  | const REGFI_VK * | value
| ) |  |

Retrieves data for a given value.

Parameters

  file | the file from which value is derived
  value | the value whose data is desired

Returns
  Returns a newly allocated data structure, or NULL on failure. Data structures must be freed with regfi_free_record.

References REGFI_VK::data_in_offset, REGFI_VK::data_off, REGFI_VK::data_size, and regfi_load_data().

## regfi_find_subkey()

bool regfi_find_subkey | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key,
|  | const char * | name,
|  | uint32_t * | index
| ) |  |

Locates a specific subkey of a given key.

Parameters

  file | the file from which key is derived
  key | the key whose subkey is desired
  name | name of the desired subkey (case-insensitive)
  index | a return value: the index of the desired subkey. undefined on error

Returns
  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.)

References REGFI_NK::name, regfi_fetch_num_subkeys(), regfi_free_record(), and regfi_get_subkey().

## regfi_find_value()

bool regfi_find_value | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key,
|  | const char * | name,
|  | uint32_t * | index
| ) |  |

Locates a specific value of a given key.

Parameters

  file | the file from which key is derived
  key | the key whose value is desired
  name | name of the desired value (case-insensitive)
  index | a return value: the index of the desired value. undefined on error

Returns
  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.)

References REGFI_VK::name, regfi_fetch_num_values(), regfi_free_record(), and regfi_get_value().

## regfi_get_subkey()

const REGFI_NK* regfi_get_subkey | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key,
|  | uint32_t | index
| ) |  |

Retrieves a specific subkey of a given key.

Parameters

  file | the file from which key is derived
  key | the key whose subkey is desired
  index | the index of the desired subkey

Returns
  the requested subkey or NULL on error.

References regfi_fetch_num_subkeys(), regfi_load_key(), and REGFI_NK::subkeys.

Referenced by regfi_find_subkey().

## regfi_get_value()

const REGFI_VK* regfi_get_value | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key,
|  | uint32_t | index
| ) |  |

Retrieves a specific value of a given key.

Parameters

  file | the file from which key is derived
  key | the key whose value is desired
  index | the index of the desired value

Returns
  the requested value or NULL on error.

References regfi_fetch_num_values(), regfi_load_value(), and REGFI_NK::values.

Referenced by regfi_find_value().

## regfi_get_parentkey()

const REGFI_NK* regfi_get_parentkey | ( | REGFI_FILE * | file,
|  | const REGFI_NK * | key
| ) |  |

Uses a key's parent_off reference to retrieve it's parent.

Parameters

  file | the file from which key is derived
  key | the key whose parent is desired

Returns
  the requested subkey or NULL on error.

References REGFI_NK::parent_off.