Função FltPerformAsynchronousIo (fltkernel.h)

Artigo
08/07/2023

Um driver de minifiltro chama FltPerformAsynchronousIo para iniciar uma operação de E/S assíncrona.

Sintaxe

NTSTATUS FLTAPI FltPerformAsynchronousIo(
  [in, out] PFLT_CALLBACK_DATA               CallbackData,
  [in]      PFLT_COMPLETED_ASYNC_IO_CALLBACK CallbackRoutine,
  [in]      PVOID                            CallbackContext
);

Parâmetros

[in, out] CallbackData

Ponteiro para uma estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) alocada por uma chamada anterior para FltAllocateCallbackData. Esse parâmetro é necessário e não pode ser NULL. O chamador é responsável por liberar essa estrutura quando ela não for mais necessária chamando FltFreeCallbackData.

[in] CallbackRoutine

Ponteiro para uma rotina de retorno de chamada do tipo PFLT_COMPLETED_ASYNC_IO_CALLBACK a ser chamada quando a operação de E/S for concluída. Observação: o Gerenciador de Filtros chama essa rotina depois de chamar as rotinas de retorno de chamada de postoperation (PFLT_POST_OPERATION_CALLBACK) de todos os drivers de minifiltro cujas instâncias estão anexadas abaixo da instância inicial (especificada no parâmetro Instance para FltAllocateCallbackData). Esse parâmetro é necessário e não pode ser NULL. O Gerenciador de Filtros sempre chama essa rotina, mesmo quando FltPerformAsynchronousIo falha.

[in] CallbackContext

Ponteiro de contexto a ser passado para a CallbackRoutine Esse parâmetro é opcional e pode ser NULL.

Retornar valor

FltPerformAsynchronousIo retorna STATUS_SUCCESS para indicar que a operação de E/S foi concluída pelo sistema de arquivos e a rotina de retorno de chamada para a qual CallbackRoutine aponta foi chamada. Caso contrário, ele retornará um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_INVALID_ASYNCHRONOUS_REQUEST	IRP_MJ_CREATE solicitações não podem ser executadas de forma assíncrona. Este é um código de erro.
STATUS_PENDING	A operação retornou STATUS_PENDING. O Gerenciador de Filtros chamará a rotina de retorno de chamada para a qual CallbackRoutine aponta quando a operação de E/S for concluída. Esse código indica apenas que a operação foi iniciada.
STATUS_FLT_IO_COMPLETE	A operação foi concluída pela rotina de retorno de chamada de pré-operação do driver de minifiltro cujas instâncias estão anexadas abaixo da instância inicial.

Comentários

Um driver de minifiltro chama FltPerformAsynchronousIo para iniciar uma operação de E/S assíncrona depois de chamar FltAllocateCallbackData para alocar uma estrutura de dados de retorno de chamada para a operação.

FltPerformAsynchronousIo envia a operação de E/S somente para as instâncias de driver de minifiltro anexadas abaixo da instância inicial (especificada no parâmetro Instance para FltAllocateCallbackData) e o sistema de arquivos. Os drivers de minifiltro anexados acima da instância especificada não recebem a operação de E/S.

Os drivers de minifiltro só podem iniciar operações de E/S baseadas em IRP. Eles não podem iniciar operações de retorno de chamada de E/S ou FSFilter (filtro do sistema de arquivos) rápidas.

Os drivers de minifiltro devem usar FltPerformAsynchronousIo somente para operações de E/S assíncronas para as quais rotinas como a seguinte não podem ser usadas:

IRP_MJ_CREATE solicitações não podem ser executadas de forma assíncrona.

A estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) pode ser liberada ou reutilizado a qualquer momento após a rotina de retorno de chamada para a qual CallbackRoutine aponta ter sido chamada. O chamador pode liberar a estrutura de dados de retorno de chamada chamando FltFreeCallbackData ou prepará-la para reutilização chamando FltReuseCallbackData.

Observação

STATUS_SUCCESS e STATUS_FLT_IO_COMPLETE indicam que a operação de E/S foi concluída, mas não indicam o status final da operação de E/S. Para determinar a operação real status retornada pelos drivers de minifiltro subjacentes, drivers de filtro e sistema de arquivos, a CallbackRoutine deve examinar o membro IoStatus da estrutura de dados de retorno de chamada recebida no parâmetro CallbackContext do CallbackRoutine.

Como o Gerenciador de Filtros sempre chama a rotina de retorno de chamada para a qual CallbackRoutine aponta, mesmo quando FltPerformAsynchronousIo falha, o driver de minifiltro pode executar as operações de liberação ou reutilização diretamente na rotina de retorno de chamada.

O chamador de FltPerformAsynchronousIo pode estar em execução em IRQL <= APC_LEVEL se o sinalizador IRP_PAGING_IO estiver definido no membro IrpFlags da estrutura FLT_IO_PARAMETER_BLOCK da operação. (Esse sinalizador só é válido para operações de IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_QUERY_INFORMATION e IRP_MJ_SET_INFORMATION.) Caso contrário, o chamador deverá estar em execução no IRQL PASSIVE_LEVEL.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
DLL	Fltmgr.sys
IRQL	Consulte a seção Observações.