Función RtlEnumerateGenericTableLikeADirectory (ntddk.h)

La rutina RtlEnumerateGenericTableLikeADirectory devuelve los elementos de una tabla genérica, uno a uno, en orden de intercalación.

Sintaxis

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

Parámetros

[in] Table

Puntero a la tabla Adelson-Velsky/Landis (AVL) (RTL_AVL_TABLE) que se enumerará.

[in, optional] MatchFunction

Función match que determina las entradas que se van a devolver. Si no se especifica, se devuelven todos los nodos.

[in, optional] MatchData

Datos que se van a pasar a la función match.

[in] NextFlag

Si RestartKey no es NULL, un valor de TRUE indica que la enumeración omitirá un elemento. Si false , la enumeración se reanuda donde se dejó en la llamada anterior a RtlEnumerateGenericTableLikeADirectory. Si RestartKey es NULL, un valor de TRUE indica a RtlEnumerateGenericTableLikeADirectory que devuelva la siguiente entrada en el árbol después de la entrada que coincida con los datos en Buffer. Un valor de FALSE indica a RtlEnumerateGenericTableLikeADirectory que devuelva la entrada en el árbol que coincida con los datos del búfer.

[in, out] RestartKey

Valor que determina dónde comenzar o reanudar la enumeración de elementos de tabla genéricos. Si RestartKey es NULL, la enumeración comienza o se reanuda desde la posición descrita en Buffer. Si no es NULL, la enumeración se reanuda desde el punto que Indica RestartKey . Al devolver, RestartKey contiene un valor que indica el lugar en el árbol donde se dejó la enumeración. En la siguiente llamada a RtlEnumerateGenericTableLikeADirectory , el llamador debe volver a pasar el mismo valor en para informar a RtlEnumerateGenericTableLikeADirectory donde reanudar la enumeración. En el ejemplo de código siguiente se muestra cómo hacerlo:

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

Si se elimina un nodo del árbol entre llamadas a RtlEnumerateGenericTableLikeADirectory, la enumeración se reanuda desde la posición del árbol que se describe en Buffer, independientemente del valor de RestartKey.

[in, out] DeleteCount

En la salida, un valor que indica el recuento actual de entradas eliminadas de la tabla. El llamador debe volver a pasar este valor en la siguiente llamada a RtlEnumerateGenericTableLikeADirectory. Este valor ayuda a la rutina RtlEnumerateGenericTableLikeADirectory a determinar si se han producido eliminaciones de la tabla entre llamadas a RtlEnumerateGenericTableLikeADirectory. Si se han producido eliminaciones, la enumeración se reanuda con la entrada de tabla que coincide con los datos de Buffer y no con la entrada de tabla indicada por RestartKey. Si RestartKey es NULL, este parámetro no tiene ningún efecto en la enumeración.

[in] Buffer

Expresión de clave que determina dónde comenzar la enumeración, cuando RestartKey es NULL. El autor de la llamada puede pasar una clave guardada que coincida con una entrada determinada en la tabla y la enumeración comenzará en la entrada especificada por la clave guardada, siempre que RestartKey sea NULL y NextFlag sea FALSE. Para devolver la clave que sigue inmediatamente a una clave guardada, pase la clave aquí, establezca RestartKey en NULL y NextFlag en TRUE. Si se ha eliminado la clave guardada, la enumeración comenzará con la siguiente clave coincidente.

Valor devuelto

La rutina RtlEnumerateGenericTableLikeADirectory devuelve un puntero a una estructura definida por el usuario asociada al siguiente elemento de tabla de la enumeración. Si no hay más elementos nuevos para devolver el valor devuelto es NULL.

Comentarios

La rutina RtlEnumerateGenericTableLikeADirectory proporciona un medio seguro para enumerar una tabla genérica entre operaciones de inserción y eliminación entre mezclas. A partir del primer nombre de clave coincidente, RtlEnumerateGenericTableLikeADirectory devuelve cada nombre de la tabla exactamente una vez, a menos que se inserte o elimine el nombre durante la enumeración. Cuando se inserta o elimina un nombre de clave durante una enumeración (es decir, entre llamadas a RtlEnumerateGenericTableLikeADirectory), podría o no incluirse en la enumeración. Si estos nombres se incluyen dependen del estado del nombre cuando RtlEnumerateGenericTableLikeADirectory procesa el intervalo de directorios en el que se encuentra el nombre.

Hay cuatro rutinas que puede usar para enumerar una tabla genérica:

De forma predeterminada, el sistema operativo usa árboles de reproducción para implementar tablas genéricas, pero la rutina RtlEnumerateGenericTableLikeADirectory solo funciona con árboles Adelson-Velsky/Landis (AVL). Para configurar las rutinas de tabla genéricas para usar árboles AVL en lugar de árboles de reproducción en el controlador, inserte la siguiente instrucción define en un archivo de encabezado común antes de incluir Ntddk.h:

 #define RTL_USE_AVL_TABLES 0

Si no se define RTL_USE_AVL_TABLES, debe usar el formato AVL de las rutinas de tabla genéricas.

Los autores de llamadas de RtlEnumerateGenericTableLikeADirectory deben ejecutarse en IRQL <= APC_LEVEL si alguna de las condiciones siguientes contiene:

• La memoria asignada por el autor de la llamada en Table o at Buffer es paginable.

• MatchFunction proporcionado por el autor de la llamada contiene código paginable.

Requisitos

Consulte también

RtlEnumerateGenericTable

RtlEnumerateGenericTableWithoutSplaying

RtlGetElementGenericTable