Função FltAllocateCallbackData (fltkernel.h)

Artigo
08/07/2023

FltAllocateCallbackData aloca uma estrutura de dados de retorno de chamada que um driver de minifiltro pode usar para iniciar uma solicitação de E/S.

Sintaxe

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parâmetros

[in] Instance

Ponteiro de instância opaco para a instância do driver de minifiltro que está iniciando a operação de E/S. Esse parâmetro é necessário e não pode ser NULL.

[in, optional] FileObject

Ponteiro de objeto de arquivo a ser usado na operação de E/S. Esse parâmetro é opcional e pode ser NULL.

[out] RetNewCallbackData

Ponteiro para uma variável alocada pelo chamador que recebe o endereço da estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) recém-alocada.

Retornar valor

FltAllocateCallbackData retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como o seguinte:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData encontrou uma falha de alocação de pool ao tentar alocar a estrutura de dados de retorno de chamada. Este é um código de erro.

Comentários

Um driver de minifiltro pode chamar FltAllocateCallbackData para alocar uma estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) para uma operação de E/S iniciada pelo driver de minifiltro.

Nota A rotina FltAllocateCallbackData não aloca toda a memória que pode ser exigida por uma solicitação de E/S subsequente. Se uma solicitação de E/S, como FltPerformSynchronousIo ou FltPerformAsynchronousIo, exigir memória adicional para alguma estrutura, a solicitação poderá encontrar uma alocação de memória. A rotina FltAllocateCallbackDataEx pode ser usada para evitar esse possível problema, pré-alocando memória para estruturas adicionais a serem usadas em uma solicitação de E/S. Se houver um problema de alocação de memória para a estrutura RetNewCallbackData ou estruturas necessárias adicionais, ela poderá ser tratada no ponto de alocação de dados de retorno de chamada.

As estruturas de dados de retorno de chamada são alocadas do pool nãopagado.

Depois de inicializar os parâmetros da estrutura de dados de retorno de chamada retornada por FltAllocateCallbackData, o chamador inicia a operação de E/S passando a estrutura para FltPerformSynchronousIo ou FltPerformAsynchronousIo. Essas rotinas enviam 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 ) e para 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 rápidas de retorno de chamada de E/S ou FSFilter (filtro do sistema de arquivos).

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

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Quando a estrutura de dados de retorno de chamada alocada por FltAllocateCallbackData não é mais necessária, o chamador é responsável por liberá-la chamando FltFreeCallbackData.