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.
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.
REGFI_FILE *	regfi_alloc_cb (REGFI_RAW_FILE *file_cb, REGFI_ENCODING output_encoding)
	Parses file headers returned by supplied callback functions.
void	regfi_free (REGFI_FILE *file)
	Frees a hive's data structures without closing the underlying file.
char *	regfi_log_get_str ()
	Get errors, warnings, and/or verbose information relating to processing of the given registry file.
bool	regfi_log_set_mask (uint16_t mask)
	Set the verbosity level of messages generated by the library for the current thread.
const REGFI_NK *	regfi_get_rootkey (REGFI_FILE *file)
	Fetches a hive's root key.
void	regfi_free_record (REGFI_FILE *file, const void *record)
	Frees a record previously returned by one of the API functions.
const void *	regfi_reference_record (REGFI_FILE *file, const void *record)
	Increments reference count on record.
uint32_t	regfi_fetch_num_subkeys (const REGFI_NK *key)
	Retrieves number of subkeys referenced by this key.
uint32_t	regfi_fetch_num_values (const REGFI_NK *key)
	Retrieves number of values referenced by this key.
const REGFI_CLASSNAME *	regfi_fetch_classname (REGFI_FILE *file, const REGFI_NK *key)
	Retrieves classname for a given key.
const REGFI_SK *	regfi_fetch_sk (REGFI_FILE *file, const REGFI_NK *key)
	Returns the SK (security) record referenced by the supplied key.
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.
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.
const REGFI_DATA *	regfi_fetch_data (REGFI_FILE *file, const REGFI_VK *value)
	Retrieves data for a given value.
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.
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.
const REGFI_NK *	regfi_get_subkey (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
	Retrieves a specific subkey of a given key.
const REGFI_VK *	regfi_get_value (REGFI_FILE *file, const REGFI_NK *key, uint32_t index)
	Retrieves a specific value of a given key.
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.

---

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

const char* regfi_version

(

)

Returns the current regfi library version.

Returns:

A string indicating the version.

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.

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

References REGFI_HBIN::block_size, REGFI_HBIN::file_off, lru_cache_create_ctx(), range_list_add(), range_list_free(), range_list_new(), and REGFI_FILE::string_encoding.

Referenced by regfi_alloc().

void regfi_free

(

REGFI_FILE *

file

)

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

Parameters:

file	The registry structure to free.

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.

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.

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.

References REGFI_NK::flags, range_list_get(), range_list_size(), and regfi_load_key().

Referenced by regfi_iterator_new().

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(), regfi_iterator_cur_subkey(), regfi_iterator_cur_value(), regfi_iterator_down(), regfi_iterator_find_subkey(), regfi_iterator_find_value(), and regfi_iterator_new().

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);

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, REGFI_NK::offset, and REGFI_NK::subkeys.

Referenced by regfi_find_subkey(), regfi_get_subkey(), regfi_iterator_down(), and regfi_iterator_new().

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, REGFI_NK::offset, and REGFI_NK::values.

Referenced by regfi_find_value(), regfi_get_value(), regfi_iterator_down(), and regfi_iterator_new().

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_length, REGFI_NK::classname_off, REGFI_CLASSNAME::interpreted, REGFI_CLASSNAME::offset, REGFI_NK::offset, REGFI_CLASSNAME::raw, regfi_parse_classname(), REGFI_CLASSNAME::size, and REGFI_FILE::string_encoding.

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_load_sk(), and REGFI_NK::sk_off.

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, and regfi_load_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, and regfi_load_sk().

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, REGFI_VK::offset, regfi_interpret_data(), regfi_load_data(), and REGFI_VK::type.

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

Referenced by regfi_iterator_find_subkey().

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

Referenced by regfi_iterator_find_value().

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(), and regfi_iterator_cur_subkey().

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(), and regfi_iterator_cur_value().

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, and regfi_load_key().