Função FltCbdqInsertIo (fltkernel.h)

Artigo
08/07/2023

FltCbdqInsertIo insere a estrutura de dados de retorno de chamada para uma operação de E/S na fila de dados de retorno de chamada de um driver de filtro.

Sintaxe

NTSTATUS FLTAPI FltCbdqInsertIo(
  [in, out]      PFLT_CALLBACK_DATA_QUEUE            Cbdq,
  [in]           PFLT_CALLBACK_DATA                  Cbd,
  [in, optional] PFLT_CALLBACK_DATA_QUEUE_IO_CONTEXT Context,
  [in, optional] PVOID                               InsertContext
);

Parâmetros

[in, out] Cbdq

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

[in] Cbd

Ponteiro para a estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) para que a operação de E/S seja enfileirada. A operação deve ser uma operação de E/S baseada em IRP.

[in, optional] Context

Variável fornecida pelo chamador que recebe um ponteiro de contexto opaco para a solicitação de E/S. Os drivers de filtro podem usar esse ponteiro para identificar um item específico na fila para que ele possa ser removido chamando FltCbdqRemoveIo. Se o driver de filtro não for necessário para remover solicitações de E/S específicas da fila, esse parâmetro poderá ser NULL.

[in, optional] InsertContext

Ponteiro de contexto a ser passado para a rotina de retorno de chamada CbdqInsertIo do driver de filtro.

Retornar valor

FltCbdqInsertIo retorna STATUS_SUCCESS quando a estrutura de dados de retorno de chamada foi inserida na fila de dados de retorno de chamada ou um valor NTSTATUS apropriado, como o seguinte:

Código de retorno	Descrição
STATUS_FLT_CBDQ_DISABLED	A estrutura de dados de retorno de chamada não foi inserida na fila de dados de retorno de chamada porque a fila está desabilitada no momento. Para reabilitar a fila, chame FltCbdqEnable. Este é um código de erro.

Observação

No caso de êxito, FltCbdqInsertIo retorna qualquer retorno de chamada InsertIo do filtro; por exemplo, um filtro pode retornar STATUS_SUCCESS ou STATUS_PENDING para indicar êxito. É importante que o filtro seja auto-consistente em qualquer valor usado para indicar êxito.

Comentários

FltCbdqInsertIo insere a estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) especificada na fila de dados de retorno de chamada de um driver de filtro.

Observe que há uma condição de corrida potencial entre um driver de filtro inserindo os dados de retorno de chamada e o IRP associado sendo cancelado. Isso pode ser evitado invocando imediatamente a rotina de cancelamento da fila se o IRP já tiver sido cancelado.

Os drivers de filtro 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 filtro podem tornar suas filas cancel-safe; o sistema manipula de forma transparente o cancelamento de E/S para os drivers de filtro.

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 .

Uma fila de dados de retorno de chamada é inicializada chamando FltCbdqInitialize. FltCbdqInsertIo usa as funções fornecidas na tabela de expedição da fila para bloquear a fila e inserir a estrutura de dados de retorno de chamada na fila. A operação de inserção em si é executada pela rotina CbdqInsertIo da fila.

Consulte FltCbdqInitialize para obter detalhes sobre como criar uma fila de dados de retorno de chamada. Use FltCbdqRemoveIo para remover uma solicitação de E/S específica da fila ou FltCbdqRemoveNextIo para remover a próxima solicitação de E/S disponível.

Se a fila estiver protegida por um bloqueio de rotação em vez de um objeto mutex ou variável de recurso, o chamador de FltCbdqInsertIo poderá estar em execução em IRQL <= DISPATCH_LEVEL. Se um mutex ou recurso for usado, o chamador deverá estar em execução em IRQL <= APC_LEVEL.