estrutura FLT_CALLBACK_DATA (fltkernel.h)

Artigo
08/07/2023

A estrutura FLT_CALLBACK_DATA representa uma operação de E/S. O Gerenciador de Filtros e os minifiltros usam essa estrutura para iniciar e processar operações de E/S.

Sintaxe

typedef struct _FLT_CALLBACK_DATA {
  FLT_CALLBACK_DATA_FLAGS     Flags;
  PETHREAD                    Thread;
  PFLT_IO_PARAMETER_BLOCK     Iopb;
  IO_STATUS_BLOCK             IoStatus;
  struct _FLT_TAG_DATA_BUFFER *TagData;
  union {
    struct {
      LIST_ENTRY QueueLinks;
      PVOID      QueueContext[2];
    };
    PVOID FilterContext[4];
  };
  KPROCESSOR_MODE             RequestorMode;
} FLT_CALLBACK_DATA, *PFLT_CALLBACK_DATA;

Membros

Flags

Máscara de bits de sinalizadores que descrevem a operação de E/S.

Os minifiltros podem definir o sinalizador a seguir.

Sinalizador	Significado
FLTFL_CALLBACK_DATA_DIRTY	Um minifiltro define esse sinalizador (chamando FltSetCallbackDataDirty) para indicar que ele modificou o conteúdo da estrutura de dados de retorno de chamada. (Para obter mais informações, consulte a seção Comentários a seguir.)

Observação

Somente o Gerenciador de Filtros pode definir os sinalizadores a seguir.

Quando o Gerenciador de Filtros inicializa a estrutura de dados de retorno de chamada, ele define um dos sinalizadores a seguir para especificar o tipo de operação de E/S que a estrutura de dados de retorno de chamada representa.

Sinalizador	Significado
FLTFL_CALLBACK_DATA_FAST_IO_OPERATION	A estrutura de dados de retorno de chamada representa uma operação rápida de E/S.
FLTFL_CALLBACK_DATA_FS_FILTER_OPERATION	A estrutura de dados de retorno de chamada representa uma operação de retorno de chamada de minifiltro do sistema de arquivos.
FLTFL_CALLBACK_DATA_IRP_OPERATION	A estrutura de dados de retorno de chamada representa uma operação baseada em IRP (pacote de solicitação de E/S).

Observação

Somente o Gerenciador de Filtros pode definir os sinalizadores a seguir.

Quando o Gerenciador de Filtros inicializa a estrutura de dados de retorno de chamada, ele também pode definir os sinalizadores a seguir.

Sinalizador	Significado
FLTFL_CALLBACK_DATA_GENERATED_IO	A estrutura de dados de retorno de chamada representa uma operação de E/S gerada por um minifiltro. Esse sinalizador é válido apenas para operações baseadas em IRP.
FLTFL_CALLBACK_DATA_REISSUED_IO	A estrutura de dados de retorno de chamada representa uma operação de E/S que está sendo reempresada por um minifiltro. (Para reemissar uma operação de E/S, um minifiltro chama FltReissueSynchronousIo.) Esse sinalizador é válido apenas para operações baseadas em IRP.
FLTFL_CALLBACK_DATA_SYSTEM_BUFFER	O buffer para a operação de E/S foi alocado do pool nãopagado. Esse sinalizador pode ser definido para qualquer tipo de operação de E/S. Os minifiltros nunca devem definir esse sinalizador.

Observação

Somente o Gerenciador de Filtros pode definir os sinalizadores a seguir.

Quando o Gerenciador de Filtros executa o processamento de conclusão para a operação de E/S que a estrutura de dados de retorno de chamada representa, ele define um ou ambos os sinalizadores a seguir.

Sinalizador	Significado
FLTFL_CALLBACK_DATA_DRAINING_IO	O Gerenciador de Filtros define esse sinalizador para indicar que ele está esvaziando o nó de conclusão para a operação de E/S. Esse sinalizador é válido somente durante a conclusão de E/S.
FLTFL_CALLBACK_DATA_POST_OPERATION	O Gerenciador de Filtros define esse sinalizador para indicar que ele está chamando rotinas de retorno de chamada pós-operação (PFLT_POST_OPERATION_CALLBACK) registradas para a operação. Esse sinalizador é válido somente durante a conclusão de E/S.

Thread

Ponteiro para o thread que iniciou a operação de E/S. Esse campo pode ser NULL.

Iopb

Ponteiro para uma estrutura FLT_IO_PARAMETER_BLOCK que contém os parâmetros para a operação de E/S.

IoStatus

Uma estrutura IO_STATUS_BLOCK que contém status e informações para a operação de E/S. Um minifiltro pode modificar o conteúdo dessa estrutura apenas em uma rotina de retorno de chamada pré-operação (PFLT_PRE_OPERATION_CALLBACK) da qual está prestes a retornar FLT_PREOP_COMPLETE ou em uma rotina de retorno de chamada pós-operação (PFLT_POST_OPERATION_CALLBACK) da qual está prestes a retornar FLT_POSTOP_FINISHED_PROCESSING. Caso contrário, o conteúdo dessa estrutura normalmente é definido pelo Gerenciador de Filtros.

TagData

Ponteiro para uma estrutura de FLT_TAG_DATA_BUFFER que contém dados de ponto de nova análise para a operação de E/S. Esse ponteiro é válido apenas no caminho pós-criação. Portanto, somente a rotina de retorno de chamada pós-operação de um minifiltro pode alterar o valor desse membro. A rotina de retorno de chamada pós-criação de um minifiltro pode alterar esse membro para apontar para uma estrutura de FLT_TAG_DATA_BUFFER diferente. No entanto, se ele alterar o membro para apontar para uma estrutura diferente, ele deverá primeiro chamar ExFreePool para liberar a estrutura existente para evitar um vazamento de memória do pool.

QueueLinks

Links de fila que um minifiltro pode usar quando a fila de dados de retorno de chamada do Gerenciador de Filtros é usada para aguardar a operação de E/S.

QueueContext[2]

Matriz de ponteiros de informações de contexto que um minifiltro pode usar quando a fila do Gerenciador de Filtros é usada para aguardar a operação de E/S.

FilterContext[4]

Matriz de ponteiros de informações de contexto que um minifiltro pode usar quando uma fila diferente da fila do Gerenciador de Filtros é usada para aguardar a operação de E/S.

RequestorMode

Indica o modo de execução do processo que iniciou a operação de E/S, KernelMode ou UserMode.

Comentários

Um minifiltro registra rotinas de retorno de chamada pré-operação (PFLT_PRE_OPERATION_CALLBACK) e pós-operação (PFLT_POST_OPERATION_CALLBACK) para um ou mais tipos de operações de E/S. Quando o Gerenciador de Filtros chama uma dessas rotinas de retorno de chamada, ele passa uma estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) como o primeiro parâmetro. Essa estrutura representa a operação de E/S.

A rotina de retorno de chamada de pré-operação ou pós-operação de um minifiltro pode modificar o conteúdo da estrutura de dados de retorno de chamada, exceto para os membros Thread e RequestorMode . Se isso acontecer, ele deverá chamar FltSetCallbackDataDirty, a menos que também tenha modificado o conteúdo do membro IoStatus . Caso contrário, os valores modificados serão ignorados.

Um minifiltro pode iniciar uma operação de E/S chamando uma rotina de suporte, como FltReadFile ou chamando FltAllocateCallbackData para alocar uma estrutura de dados de retorno de chamada; inicializando os parâmetros de E/S da estrutura e passando a estrutura para FltPerformSynchronousIo ou FltPerformAsynchronousIo.

Uma operação de E/S iniciada por minifiltro é enviada apenas para as instâncias de minifiltro anexadas abaixo da instância de chamada e para o sistema de arquivos. Os minifiltros anexados acima da instância especificada não recebem a operação de E/S.

Os minifiltros 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.