Loading...
Searching...
No Matches
Iterator Layer: Primary regfi Library Interface

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

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

## regfi_iterator_free()

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

## regfi_iterator_down()

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

## regfi_iterator_up()

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

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

## regfi_iterator_descend()

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

## regfi_iterator_cur_key()

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

## regfi_iterator_first_subkey()

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.

## regfi_iterator_cur_subkey()

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

## regfi_iterator_next_subkey()

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.

## regfi_iterator_find_subkey()

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

## regfi_iterator_first_value()

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.

## regfi_iterator_cur_value()

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

## regfi_iterator_next_value()

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.

## regfi_iterator_find_value()

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

## regfi_iterator_ancestry()

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