Función FltCbdqInitialize (fltkernel.h)

FltCbdqInitialize inicializa una tabla de distribución de cola de datos de devolución de llamada del controlador de 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 de inserción 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 de minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cdb

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 de minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cdb

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 PeekContext en la cola; o bien, 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 de minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cdb

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 al principio 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 de 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 correspondiente CbdqRelease.

[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 de 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 correspondiente al CbdqAcquire rutina.

[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 para completar 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 de minifiltro. Esta cola debe haberse inicializado llamando a FltCbdqInitialize.

Cdb

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.

Observaciones

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 fltCbdqDisable llamando a FltCbdqEnable.

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

Las rutinas de 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 distribución 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 CbdqInsertIo, CbdqRemoveIoy CbdqPeekNextIo rutinas.

Los controladores de minifiltro pueden usar cualquiera de los primitivos de sincronización del sistema operativo como mecanismo de bloqueo en su CbdqAcquire y rutinas de cbdqRelease, como un bloqueo de giro, objeto de exclusión mutuao variable de recursos. 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 de 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 llame a cualquiera de estas rutinas excepto FltCbdqInitialize.

El controlador de minifiltro no manipula directamente la cola. En su lugar, llama a FltCbdqInsertIo, FltCbdqRemoveIoy 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 las estructuras de datos de devolución de llamada con coincidencias PeekContext en la cola. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) debe devolver la primera entrada coincidente en la cola, y CbdqPeekNextIo(Cbdq, Cbd, PeekContext) deben 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 de 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 de 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 giro 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 estructura de datos de devolución de llamada: el Administrador de filtros llama automáticamente a la CbdqRemoveIo antes de llamar a CbdqCompleteCanceledIo.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
encabezado de	fltkernel.h (incluya Fltkernel.h)
irQL	Cualquier nivel

Consulte también

FLT_CALLBACK_DATA

FLT_CALLBACK_DATA_QUEUE

FLT_IS_IRP_OPERATION

fltCbdqDisable

FltCbdqEnable

FltCbdqInsertIo

FltCbdqRemoveIo

FltCbdqRemoveNextIo

FltCompletePendedPreOperation

keAcquireSpinLock

keReleaseSpinLock