This top layer of API functions provides an iterator interface which makes traversing registry data structures easy in both single-threaded and multi-threaded scenarios. More...

Data Structures
struct	REGFI_ITERATOR
	Registry hive iterator. More...
Functions
REGFI_ITERATOR *	regfi_iterator_new (REGFI_FILE *file)
	Creates a new iterator for the provided registry file.
void	regfi_iterator_free (REGFI_ITERATOR *i)
	Frees a registry file iterator previously created by regfi_iterator_new.
bool	regfi_iterator_down (REGFI_ITERATOR *i)
	Traverse deeper into the registry tree at the current subkey.
bool	regfi_iterator_up (REGFI_ITERATOR *i)
	Traverse up to the current key's parent key.
bool	regfi_iterator_to_root (REGFI_ITERATOR *i)
	Traverse up to the root key of the hive.
bool	regfi_iterator_descend (REGFI_ITERATOR i, const char *path)
	Traverse down multiple levels in the registry hive.
const REGFI_NK *	regfi_iterator_cur_key (REGFI_ITERATOR *i)
	Returns the currently referenced key.
bool	regfi_iterator_first_subkey (REGFI_ITERATOR *i)
	Sets the internal subkey index to the first subkey referenced by the current key.
const REGFI_NK *	regfi_iterator_cur_subkey (REGFI_ITERATOR *i)
	Returns the currently indexed subkey.
bool	regfi_iterator_next_subkey (REGFI_ITERATOR *i)
	Increments the internal subkey index to the next key in the subkey-list.
bool	regfi_iterator_find_subkey (REGFI_ITERATOR i, const char name)
	Searches for a subkey with a given name under the current key.
bool	regfi_iterator_first_value (REGFI_ITERATOR *i)
	Sets the internal value index to the first value referenced by the current key.
const REGFI_VK *	regfi_iterator_cur_value (REGFI_ITERATOR *i)
	Returns the currently indexed value.
bool	regfi_iterator_next_value (REGFI_ITERATOR *i)
	Increments the internal value index to the next value in the value-list.
bool	regfi_iterator_find_value (REGFI_ITERATOR i, const char name)
	Searches for a value with a given name under the current key.
const REGFI_NK **	regfi_iterator_ancestry (REGFI_ITERATOR *i)
	Returns the current key and all parent keys as a list of NK records.

Detailed Description

This top layer of API functions provides an iterator interface which makes traversing registry data structures easy in both single-threaded and multi-threaded scenarios.

Function Documentation

REGFI_ITERATOR* regfi_iterator_new ( REGFI_FILE * file )

Creates a new iterator for the provided registry file.

Parameters:

file	The opened registry file the iterator should be created for.

Returns:: A newly allocated REGFI_ITERATOR. Must be free()d with regfi_iterator_free.

References REGFI_ITERATOR::f, REGFI_ITERATOR::key_positions, REGFI_NK::offset, regfi_fetch_num_subkeys(), regfi_fetch_num_values(), regfi_free_record(), regfi_get_rootkey(), REGFI_NK::subkeys_off, REGFI_NK::values_off, and void_stack_new().

void regfi_iterator_free ( REGFI_ITERATOR * i )

Frees a registry file iterator previously created by regfi_iterator_new.

This does not affect the underlying registry file's allocation status.

Parameters:

i	the iterator to be freed

bool regfi_iterator_down ( REGFI_ITERATOR * i )

Traverse deeper into the registry tree at the current subkey.

Parameters:

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.

References REGFI_ITERATOR::f, REGFI_ITERATOR::key_positions, REGFI_NK::offset, regfi_fetch_num_subkeys(), regfi_fetch_num_values(), regfi_free_record(), regfi_iterator_cur_subkey(), REGFI_NK::subkeys_off, REGFI_NK::values_off, and void_stack_push().

Referenced by regfi_iterator_descend().

bool regfi_iterator_up ( REGFI_ITERATOR * i )

Traverse up to the current key's parent key.

Parameters:

i	the iterator

Returns:: true on success, false on failure. Any subkey or value state associated with the current key is lost.

References REGFI_ITERATOR::f, REGFI_ITERATOR::key_positions, and void_stack_pop().

Referenced by regfi_iterator_descend(), and regfi_iterator_to_root().

bool regfi_iterator_to_root ( REGFI_ITERATOR * i )

Traverse up to the root key of the hive.

Parameters:

i	the iterator

Returns:: true on success, false on failure.

References regfi_iterator_up().

bool regfi_iterator_descend	(	REGFI_ITERATOR *	i,
		const char **	path
	)

Traverse down multiple levels in the registry hive.

XXX: This currently only accepts ASCII key names. Need to look into accepting other encodings.

Parameters:

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

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.

References regfi_iterator_down(), regfi_iterator_find_subkey(), and regfi_iterator_up().

const REGFI_NK* regfi_iterator_cur_key ( REGFI_ITERATOR * i )

Returns the currently referenced key.

Parameters:

i	the iterator

Returns:: A read-only key structure for the current key, or NULL on failure. Data structures must be freed with regfi_free_record.

References REGFI_ITERATOR::f, and regfi_load_key().

Referenced by regfi_iterator_cur_subkey(), regfi_iterator_cur_value(), regfi_iterator_find_subkey(), and regfi_iterator_find_value().

bool regfi_iterator_first_subkey ( REGFI_ITERATOR * i )

Sets the internal subkey index to the first subkey referenced by the current key.

Parameters:

i	the iterator

Returns:: True if the current key has any subkeys, false otherwise.

const REGFI_NK* regfi_iterator_cur_subkey ( REGFI_ITERATOR * i )

Returns the currently indexed subkey.

Parameters:

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

References REGFI_ITERATOR::f, regfi_free_record(), regfi_get_subkey(), and regfi_iterator_cur_key().

Referenced by regfi_iterator_down().

bool regfi_iterator_next_subkey ( REGFI_ITERATOR * i )

Increments the internal subkey index to the next key in the subkey-list.

Parameters:

i	the iterator

Returns:: True if another subkey should exist, false otherwise.

bool regfi_iterator_find_subkey	(	REGFI_ITERATOR *	i,
		const char *	name
	)

Searches for a subkey with a given name under the current key.

Parameters:

i	the iterator
name	subkey name to search for

Returns:: True if such a subkey was found, false otherwise. If a subkey is found, the current subkey index is set to that subkey. Otherwise, the subkey index remains at the same location as before the call.

References REGFI_ITERATOR::f, regfi_find_subkey(), regfi_free_record(), and regfi_iterator_cur_key().

Referenced by regfi_iterator_descend().

bool regfi_iterator_first_value ( REGFI_ITERATOR * i )

Sets the internal value index to the first value referenced by the current key.

Parameters:

i	the iterator

Returns:: True if the current key has any values, false otherwise.

const REGFI_VK* regfi_iterator_cur_value ( REGFI_ITERATOR * i )

Returns the currently indexed value.

Parameters:

i	the iterator

Returns:: A newly allocated value structure for the currently referenced value, or NULL on failure. Newly allocated values must be freed with regfi_free_record.

References REGFI_ITERATOR::f, regfi_free_record(), regfi_get_value(), and regfi_iterator_cur_key().

bool regfi_iterator_next_value ( REGFI_ITERATOR * i )

Increments the internal value index to the next value in the value-list.

Parameters:

i	the iterator

Returns:: True if another value should exist, false otherwise.

bool regfi_iterator_find_value	(	REGFI_ITERATOR *	i,
		const char *	name
	)

Searches for a value with a given name under the current key.

Parameters:

i	the iterator
name	value name to search for

Returns:: True if such a value was found, false otherwise. If a value is found, the current value index is set to that value. Otherwise, the value index remains at the same location as before the call.

References REGFI_ITERATOR::f, regfi_find_value(), regfi_free_record(), and regfi_iterator_cur_key().

const REGFI_NK** regfi_iterator_ancestry ( REGFI_ITERATOR * i )

Returns the current key and all parent keys as a list of NK records.

Parameters:

i	the iterator

Returns:: An array of NK record pointers terminated by a NULL pointer. This array may be passed directly to regfi_free_record to free the entire array.

Note:: In order to use an element of the array independently from the array (that is, to hold a pointer to an individual NK record while freeing the remaining array), callers must first use regfi_reference_record on the elements to be kept.

References REGFI_ITERATOR::f, REGFI_ITERATOR::key_positions, regfi_load_key(), void_stack_iterator_free(), void_stack_iterator_new(), void_stack_iterator_next(), and void_stack_size().

Data Structures

Functions

Detailed Description

Function Documentation