Función FltCbdqInitialize (fltkernel.h)

Artículo
08/07/2023

FltCbdqInitialize inicializa una tabla de distribución de cola de datos de devolución de llamada del controlador minifiltro.

Sintaxis

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

Parámetros

[in] Instance

Puntero de instancia opaco para la instancia cuya cola de datos de devolución de llamada se va a inicializar.

[in, out] Cbdq

Puntero a una cola de datos de devolución de llamada asignada por el controlador de minifiltro.

[in] CbdqInsertIo

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina para insertar la estructura de datos de devolución de llamada especificada en la cola. Esta rutina se declara de la siguiente manera:

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cbd

Puntero a la estructura de datos de devolución de llamada que se va a insertar en la cola.

InsertContext

Puntero de información de contexto que se pasó como parámetro InsertContext a FltCbdqInsertIo.

[in] CbdqRemoveIo

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina para quitar la estructura de datos de devolución de llamada especificada de la cola. Esta rutina se declara de la siguiente manera:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cbd

Puntero a la estructura de datos de devolución de llamada que se va a quitar de la cola.

[in] CbdqPeekNextIo

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. El Administrador de filtros llama a esta función para obtener un puntero a la siguiente operación de E/S que coincida con PeekContext en la cola; o, si Cbd es NULL, para obtener un puntero a la primera operación de E/S coincidente en la cola. El controlador de minifiltro define completamente el significado de PeekContext y define cuándo una operación de E/S coincide con un PeekContext determinado. Esta rutina se declara de la siguiente manera:

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cbd

Puntero a la estructura de datos de devolución de llamada que marca la posición de la cola para empezar a buscar una coincidencia con PeekContext. Si Cbd es NULL, la búsqueda comienza en la cabeza de la cola.

PeekContext

Puntero de información de contexto que se pasó como parámetro PeekContext a FltCbdqRemoveNextIo.

[in] CbdqAcquire

Puntero a una rutina de devolución de llamada de bloqueo de cola proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina para adquirir el bloqueo en la cola antes de intentar insertar o quitar un elemento de la cola. Esta rutina se declara de la siguiente manera:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Irql

Puntero a una variable proporcionada por el sistema que recibe el IRQL actual. La misma variable se pasa a la rutina CbdqRelease correspondiente.

[in] CbdqRelease

Puntero a una rutina de devolución de llamada de bloqueo de cola de liberación proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina para liberar el bloqueo que obtuvo llamando a la rutina CbdqAcquire correspondiente. Esta rutina se declara de la siguiente manera:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Irql

La misma variable proporcionada por el sistema que recibió el IRQL actual que el parámetro Irql a la rutina CbdqAcquire correspondiente.

[in] CbdqCompleteCanceledIo

Puntero a una rutina de cancelación proporcionada por el autor de la llamada. El Administrador de filtros llama a esta rutina para indicar al controlador de minifiltro que complete una operación de E/S cancelada. Esta rutina se declara de la siguiente manera:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Puntero a la cola de datos de devolución de llamada segura para cancelación del controlador minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cbd

Puntero a la estructura de datos de devolución de llamada para la operación de E/S cancelada.

Valor devuelto

FltCbdqInitialize devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado.

Comentarios

La cola de datos de devolución de llamada recién inicializada está en estado habilitado, lo que significa que los elementos de estructura de datos de devolución de llamada se pueden insertar en la cola. La cola se puede deshabilitar llamando a FltCbdqDisable y reenabled llamando a FltCbdqEnable.

Los controladores de minifiltro pueden usar las rutinas FltCbdqXxx para implementar una cola de datos de devolución de llamada para las operaciones de E/S basadas en IRP. Mediante el uso de estas rutinas, los controladores de minifiltro pueden hacer que sus colas sean seguras para cancelar; el sistema controla de forma transparente la cancelación de E/S para los controladores de minifiltro.

Las rutinas FltCbdqXxx solo se pueden usar para las operaciones de E/S basadas en IRP. Para determinar si una estructura de datos de devolución de llamada determinada representa una operación de E/S basada en IRP, use la macro FLT_IS_IRP_OPERATION .

Los controladores de minifiltro pueden usar cualquier implementación interna para la cola. El Administrador de filtros interactúa con la implementación de la cola del controlador de minifiltro únicamente a través del conjunto de rutinas de envío proporcionadas por FltCbdqInitialize.

El sistema bloquea y desbloquea automáticamente la cola según sea necesario. Los controladores de minifiltro no implementan ningún bloqueo dentro de sus rutinas CbdqInsertIo, CbdqRemoveIo y CbdqPeekNextIo .

Los controladores de minifiltro pueden usar cualquiera de los primitivos de sincronización del sistema operativo como mecanismo de bloqueo en sus rutinas CbdqAcquire y CbdqRelease , como un bloqueo de número, un objeto de exclusión mutua o una variable de recurso. Tenga en cuenta que si un controlador de minifiltro usa un bloqueo de número en lugar de una exclusión mutua o un recurso para proteger la cola, puede llamar a las rutinas FltCbdqXxx en IRQL <= DISPATCH_LEVEL. Si se usa una exclusión mutua o un recurso, el controlador de minifiltro debe ejecutarse en IRQL <= APC_LEVEL cuando llama a cualquiera de estas rutinas excepto FltCbdqInitialize.

El controlador de minifiltro no manipula la cola directamente. En su lugar, llama a FltCbdqInsertIo, FltCbdqRemoveIo y FltCbdqRemoveNextIo para agregar o quitar una estructura de datos de devolución de llamada. Estas rutinas, a su vez, llaman a las funciones de devolución de llamada que el controlador de minifiltro proporcionó a FltCbdqInitialize.

Los controladores de minifiltro deben implementar las rutinas de cola de la siguiente manera.

Rutina cbdq	Implementación
CbdqInsertIo	Inserte la estructura de datos de devolución de llamada especificada en la cola.
CbdqRemoveIo	Quite la estructura de datos de devolución de llamada especificada de la cola.
CbdqPeekNextIo	Esta rutina debe permitir que el sistema recorra en bucle las estructuras de datos de devolución de llamada con peekContext coincidente en la cola. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) debe devolver la primera entrada coincidente en la cola y CbdqPeekNextIo(Cbdq, Cbd,PeekContext) debe devolver la siguiente entrada coincidente después de la estructura de datos de devolución de llamada especificada en la cola. El controlador de minifiltro define completamente el significado de PeekContext y define cuándo una estructura de datos de devolución de llamada coincide con un valor PeekContext .
CbdqAcquire	Esta rutina debe bloquear la cola para que ningún otro subproceso pueda acceder a ella. Los controladores de minifiltro pueden usar cualquier mecanismo de bloqueo para bloquear la cola. Si el controlador de minifiltro usa la rutina KeAcquireSpinLock , el controlador de minifiltro puede usar la ubicación de memoria a la que apunta el parámetro Irql de la rutina para almacenar el IRQL. De lo contrario, los controladores de minifiltro pueden omitir ese parámetro.
CbdqRelease	Esta rutina debe desbloquear la cola creada por CbdqAcquire. Si el controlador de minifiltro usó un bloqueo de giro y devolvió el valor IRQL en el parámetro Irql de CbdqAcquire, el sistema pasa ese valor en el parámetro Irql de CbdqRelease. El controlador de minifiltro puede usar IRQL para desbloquear el bloqueo de número llamando a KeReleaseSpinLock. De lo contrario, los controladores de minifiltro pueden omitir el parámetro Irql .
CbdqCompleteCanceledIo	Esta rutina debe completar una operación de E/S cancelada. Normalmente, los controladores de minifiltro simplemente pueden llamar a FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). Los controladores de minifiltro no necesitan quitar la cola de la estructura de datos de devolución de llamada: el Administrador de filtros llama automáticamente a la cola CbdqRemoveIo antes de llamar a CbdqCompleteCanceledIo.