Функция RtlEnumerateGenericTableLikeADirectory (ntddk.h)

Статья
02/26/2024

Подпрограмма RtlEnumerateGenericTableLikeADirectory возвращает элементы универсальной таблицы по одному в порядке сортировки.

Синтаксис

NTSYSAPI PVOID RtlEnumerateGenericTableLikeADirectory(
  [in]           PRTL_AVL_TABLE          Table,
  [in, optional] PRTL_AVL_MATCH_FUNCTION MatchFunction,
  [in, optional] PVOID                   MatchData,
  [in]           ULONG                   NextFlag,
  [in, out]      PVOID                   *RestartKey,
  [in, out]      PULONG                  DeleteCount,
  [in]           PVOID                   Buffer
);

Параметры

[in] Table

Указатель на таблицу Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE), которая будет перечислена.

[in, optional] MatchFunction

Функция сопоставления, которая определяет, какие записи следует вернуть. Если не указано, возвращаются все узлы.

[in, optional] MatchData

Данные, передаваемые в функцию сопоставления.

[in] NextFlag

Если параметр RestartKey не имеет значение NULL, значение TRUE указывает, что перечисление пропускает элемент. Если значение FALSE , перечисление возобновляется с того места, где оно осталось в предыдущем вызове RtlEnumerateGenericTableLikeADirectory. Если параметр RestartKey имеет значение NULL, значение TRUE указывает RtlEnumerateGenericTableLikeADirectory вернуть следующую запись в дереве после записи, которая соответствует данным в буфере. Значение FALSE указывает RtlEnumerateGenericTableLikeADirectory вернуть запись в дереве, которая соответствует данным в буфере.

[in, out] RestartKey

Значение , определяющее, где начать или возобновить перечисление универсальных элементов таблицы. Если параметр RestartKey имеет значение NULL, перечисление начинается или возобновляется с позиции, описанной в разделе Буфер. Если значение не равно NULL, перечисление возобновляется с точки, указывающей RestartKey . При возврате RestartKey содержит значение, указывающее место в дереве, где осталось перечисление. При следующем вызове RtlEnumerateGenericTableLikeADirectory вызывающий объект должен передать то же значение обратно в , чтобы сообщить RtlEnumerateGenericTableLikeADirectory , где возобновить перечисление. В следующем примере кода показано, как это сделать:

NextFlag = FALSE;
RestartKey = NULL;
DeleteCount = 0;
// Initialize Buffer for start/resume point
Buffer = ...
for (ptr = NULL; ptr != NULL;  ) {
  // Value returned in RestartKey will be passed back in
  // on following call (iteration):
  ptr = RtlEnumerateGenericTableLikeADirectory(
      &MyTable, NULL, NULL, TRUE, &RestartKey,
      &DeleteCount, &Buffer, sizeof(LONG) );
      ...
  // The value output in RestartKey will still be in
  // RestartKey when the
  // RtlEnumerationGenericTableLikeADirectory routine
  // is called in the next iteration of this loop.
  // This ensures that the enumeration will pick up
  // where it left off.
}

Если узел удаляется из дерева между вызовами RtlEnumerateGenericTableLikeADirectory, перечисление возобновляется из позиции в дереве, описанной в буфере, независимо от значения RestartKey.

[in, out] DeleteCount

В выходных данных значение, указывающее текущее количество записей, удаленных из таблицы. Вызывающий объект должен передать это значение обратно при следующем вызове RtlEnumerateGenericTableLikeADirectory. Это значение помогает подпрограмме RtlEnumerateGenericTableLikeADirectory определить, произошли ли удаления из таблицы между вызовами RtlEnumerateGenericTableLikeADirectory. Если произошло удаление, перечисление возобновляется с записью таблицы, которая соответствует данным в буфере, а не с записью таблицы, указанной параметром RestartKey. Если параметр RestartKey имеет значение NULL, этот параметр не влияет на перечисление..

[in] Buffer

Ключевое выражение, определяющее, с чего начать перечисление, если RestartKey имеет значение NULL. Вызывающий объект может передать сохраненный ключ, соответствующий определенной записи в таблице, и перечисление начнется с записи, указанной сохраненным ключом, при условии , что RestartKey имеет значение NULL , а NextFlag — FALSE. Чтобы вернуть ключ, который сразу же следует за сохраненным ключом, передайте сюда ключ, установите для параметра RestartKeyзначение NULL , а для NextFlag — значение TRUE. Если сохраненный ключ был удален, перечисление начнется со следующего совпадаемого ключа.

Возвращаемое значение

Подпрограмма RtlEnumerateGenericTableLikeADirectory возвращает указатель на определяемую пользователем структуру, связанную со следующим элементом таблицы в перечислении. Если новых элементов для возврата больше нет, возвращается значение NULL.

Подпрограмма RtlEnumerateGenericTableLikeADirectory предоставляет безопасные средства для перечисления универсальной таблицы между операциями вставки и удаления. Начиная с первого совпадающего имени ключа , RtlEnumerateGenericTableLikeADirectory возвращает каждое имя в таблице ровно один раз, если только имя не было вставлено или удалено во время перечисления. Если имя ключа вставляется или удаляется во время перечисления (т. е. между вызовами RtlEnumerateGenericTableLikeADirectory), оно может быть включено в перечисление или не может быть включено. Включение таких имен зависит от состояния имени, когда RtlEnumerateGenericTableLikeADirectory обрабатывает диапазон каталогов, в котором найдено имя.

Существует четыре подпрограммы, которые можно использовать для перечисления универсальной таблицы:

По умолчанию операционная система использует деревья splay для реализации универсальных таблиц, но подпрограмма RtlEnumerateGenericTableLikeADirectory работает только с деревьями Adelson-Velsky/Landis (AVL). Чтобы настроить в универсальных подпрограммах таблицы использование деревьев AVL вместо деревьев splay в драйвере, вставьте следующую инструкцию define в общий файл заголовка перед включением Ntddk.h:

 #define RTL_USE_AVL_TABLES 0

Если RTL_USE_AVL_TABLES не определен, необходимо использовать форму AVL универсальных подпрограмм таблиц.

Вызывающие элементы RtlEnumerateGenericTableLikeADirectory должны выполняться в среде IRQL <= APC_LEVEL если выполняется одно из следующих условий:

Память, выделенная вызывающим объектом в table или в буфере , доступна на страницы.
Функция MatchFunction , предоставляемая вызывающим элементом, содержит код, доступный для страниц.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h, Ntifs.h, FltKernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL (см. раздел "Примечания")

См. также раздел

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable

Share via