Função FltCbdqInitialize (fltkernel.h)

Artigo
08/07/2023

FltCbdqInitialize inicializa a tabela de expedição de fila de dados de retorno de chamada de um driver de minifiltro.

Sintaxe

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

Ponteiro de instância opaca para a instância cuja fila de dados de retorno de chamada deve ser inicializada.

[in, out] Cbdq

Ponteiro para uma fila de dados de retorno de chamada alocada pelo driver de minifiltro.

[in] CbdqInsertIo

Ponteiro para uma rotina de retorno de chamada de inserção fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina para inserir a estrutura de dados de retorno de chamada especificada na fila. Essa rotina é declarada da seguinte maneira:

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

Cbdq

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Cbd

Ponteiro para a estrutura de dados de retorno de chamada a ser inserida na fila.

InsertContext

Ponteiro de informações de contexto que foi passado como o parâmetro InsertContext para FltCbdqInsertIo.

[in] CbdqRemoveIo

Ponteiro para uma rotina de retorno de chamada de remoção fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina para remover a estrutura de dados de retorno de chamada especificada da fila. Essa rotina é declarada da seguinte maneira:

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

Cbdq

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Cbd

Ponteiro para a estrutura de dados de retorno de chamada a ser removida da fila.

[in] CbdqPeekNextIo

Ponteiro para uma rotina de retorno de chamada de espiada fornecida pelo chamador. O Gerenciador de Filtros chama essa função para obter um ponteiro para a próxima operação de E/S correspondente a PeekContext na fila; ou, se o Cbd for NULL, para obter um ponteiro para a primeira operação de E/S correspondente na fila. O driver de minifiltro define totalmente o significado de PeekContext e define quando uma operação de E/S corresponde a um determinado PeekContext. Essa rotina é declarada da seguinte maneira:

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

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Cbd

Ponteiro para a estrutura de dados de retorno de chamada marcando a posição na fila para começar a pesquisar uma correspondência para PeekContext. Se o CBD for NULL, a pesquisa começará no início da fila.

PeekContext

Ponteiro de informações de contexto que foi passado como o parâmetro PeekContext para FltCbdqRemoveNextIo.

[in] CbdqAcquire

Ponteiro para uma rotina de retorno de chamada de bloqueio de fila fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina para adquirir o bloqueio na fila antes de tentar inserir ou remover um item da fila. Essa rotina é declarada da seguinte maneira:

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

Cbdq

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Irql

Ponteiro para uma variável fornecida pelo sistema que recebe o IRQL atual. A mesma variável é passada para a rotina de CbdqRelease correspondente.

[in] CbdqRelease

Ponteiro para uma rotina de retorno de chamada de bloqueio de fila de liberação fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina para liberar o bloqueio obtido chamando a rotina cbdqAcquire correspondente. Essa rotina é declarada da seguinte maneira:

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

Cbdq

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Irql

A mesma variável fornecida pelo sistema que recebeu o IRQL atual que o parâmetro Irql para a rotina de CbdqAcquire correspondente.

[in] CbdqCompleteCanceledIo

Ponteiro para uma rotina de cancelamento fornecida pelo chamador. O Gerenciador de Filtros chama essa rotina para sinalizar para o driver de minifiltro para concluir uma operação de E/S cancelada. Essa rotina é declarada da seguinte maneira:

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

Cbdq

Ponteiro para a fila de dados de retorno de chamada cancel-safe do driver de minifiltro. Essa fila deve ter sido inicializada chamando FltCbdqInitialize.

Cbd

Ponteiro para a estrutura de dados de retorno de chamada para a operação de E/S cancelada.

Retornar valor

FltCbdqInitialize retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado.

Comentários

A fila de dados de retorno de chamada recém-inicializada está no estado habilitado, o que significa que os itens da estrutura de dados de retorno de chamada podem ser inseridos na fila. A fila pode ser desabilitada chamando FltCbdqDisable e reenabled chamando FltCbdqEnable.

Os drivers de minifiltro podem usar as rotinas fltCbdqXxx para implementar uma fila de dados de retorno de chamada para operações de E/S baseadas em IRP. Usando essas rotinas, os drivers de minifiltro podem tornar suas filas canceladas seguras; o sistema manipula de forma transparente o cancelamento de E/S para os drivers de minifiltro.

As rotinas fltCbdqXxx só podem ser usadas para operações de E/S baseadas em IRP. Para determinar se uma determinada estrutura de dados de retorno de chamada representa uma operação de E/S baseada em IRP, use a macro FLT_IS_IRP_OPERATION .

Os drivers de minifiltro podem usar qualquer implementação interna para a fila. O Gerenciador de Filtros interage com a implementação da fila do driver de minifiltro somente por meio do conjunto de rotinas de expedição fornecidas por FltCbdqInitialize.

O sistema bloqueia e desbloqueia automaticamente a fila conforme necessário. Os drivers de minifiltro não implementam nenhum bloqueio dentro de suas rotinas CbdqInsertIo, CbdqRemoveIo e CbdqPeekNextIo .

Os drivers de minifiltro podem usar qualquer um dos primitivos de sincronização do sistema operacional como o mecanismo de bloqueio em suas rotinas CbdqAcquire e CbdqRelease , como um bloqueio de rotação, um objeto mutex ou uma variável de recurso. Observe que, se um driver de minifiltro usa um bloqueio de rotação em vez de um mutex ou recurso para proteger a fila, ele pode chamar as rotinas fltCbdqXxx em IRQL <= DISPATCH_LEVEL. Se um mutex ou recurso for usado, o driver de minifiltro deverá estar em execução em IRQL <= APC_LEVEL quando chamar qualquer uma dessas rotinas, exceto FltCbdqInitialize.

O driver de minifiltro não manipula a fila diretamente. Em vez disso, ele chama FltCbdqInsertIo, FltCbdqRemoveIo e FltCbdqRemoveNextIo para adicionar ou remover uma estrutura de dados de retorno de chamada. Essas rotinas, por sua vez, chamam as funções de retorno de chamada que o driver de minifiltro forneceu ao FltCbdqInitialize.

Os drivers de minifiltro devem implementar as rotinas de fila da seguinte maneira.

Rotina cbdq	Implementação
CbdqInsertIo	Insira a estrutura de dados de retorno de chamada especificada na fila.
CbdqRemoveIo	Remova a estrutura de dados de retorno de chamada especificada da fila.
CbdqPeekNextIo	Essa rotina deve permitir que o sistema faça loop pelas estruturas de dados de retorno de chamada com PeekContext correspondente na fila. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) deve retornar a primeira entrada correspondente na fila e CbdqPeekNextIo(Cbdq, Cbd, PeekContext) deve retornar a próxima entrada correspondente após a estrutura de dados de retorno de chamada fornecida na fila. O driver de minifiltro define totalmente o significado de PeekContext e define quando uma estrutura de dados de retorno de chamada corresponde a um valor PeekContext .
CbdqAcquire	Essa rotina deve bloquear a fila para que nenhum outro thread possa acessá-la. Os drivers de minifiltro podem usar qualquer mecanismo de bloqueio para bloquear a fila. Se o driver de minifiltro usar a rotina KeAcquireSpinLock , o driver de minifiltro poderá usar o local de memória apontado pelo parâmetro Irql da rotina para armazenar o IRQL. Caso contrário, os drivers de minifiltro podem ignorar esse parâmetro.
CbdqRelease	Essa rotina deve desbloquear a fila criada por CbdqAcquire. Se o driver de minifiltro usou um bloqueio de rotação e retornou o valor IRQL no parâmetro Irql de CbdqAcquire, o sistema passará esse valor no parâmetro Irql de CbdqRelease. O driver de minifiltro pode usar o IRQL para desbloquear o bloqueio de rotação chamando KeReleaseSpinLock. Caso contrário, os drivers de minifiltro podem ignorar o parâmetro Irql .
CbdqCompleteCanceledIo	Essa rotina deve concluir uma operação de E/S cancelada. Normalmente, os drivers de minifiltro podem chamar FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). Os drivers de minifiltro não precisam desativar a estrutura de dados de retorno de chamada – o Gerenciador de Filtros chama automaticamente o CbdqRemoveIo da fila antes de chamar CbdqCompleteCanceledIo.