estrutura FLT_CONTEXT_REGISTRATION (fltkernel.h)

Artigo
03/01/2024

A estrutura FLT_CONTEXT_REGISTRATION é usada para registrar tipos de contexto.

Sintaxe

typedef struct _FLT_CONTEXT_REGISTRATION {
  FLT_CONTEXT_TYPE               ContextType;
  FLT_CONTEXT_REGISTRATION_FLAGS Flags;
  PFLT_CONTEXT_CLEANUP_CALLBACK  ContextCleanupCallback;
  SIZE_T                         Size;
  ULONG                          PoolTag;
  PFLT_CONTEXT_ALLOCATE_CALLBACK ContextAllocateCallback;
  PFLT_CONTEXT_FREE_CALLBACK     ContextFreeCallback;
  PVOID                          Reserved1;
} FLT_CONTEXT_REGISTRATION, *PFLT_CONTEXT_REGISTRATION;

Membros

ContextType

O tipo de contexto. Esse membro é necessário e deve ser um dos seguintes valores:

FLT_FILE_CONTEXT (somente Windows Vista e posterior.)

FLT_INSTANCE_CONTEXT

FLT_STREAM_CONTEXT

FLT_STREAMHANDLE_CONTEXT

FLT_SECTION_CONTEXT (somente Windows 8 e posterior.)

FLT_TRANSACTION_CONTEXT (somente Windows Vista e posterior.)

FLT_VOLUME_CONTEXT

Flags

Uma máscara de bits de sinalizadores que especifica como o gerenciador de filtros aloca um novo contexto de uma lista lookaside de contextos de tamanho fixo. Esse membro pode ser zero ou o valor a seguir.

Sinalizador	Significado
FLTFL_CONTEXT_REGISTRATION_NO_EXACT_SIZE_MATCH	Se o minifiltro usar contextos de tamanho fixo e esse sinalizador for especificado, o gerenciador de filtros alocará um contexto da lista lookaside se o tamanho do contexto na lista lookaside for maior ou igual ao tamanho solicitado. Caso contrário, o gerenciador de filtros alocará um contexto da lista lookaside somente se o tamanho do contexto na lista lookaside for igual ao tamanho solicitado.

Sinalizador

Significado

FLTFL_CONTEXT_REGISTRATION_NO_EXACT_SIZE_MATCH

Se o minifiltro usar contextos de tamanho fixo e esse sinalizador for especificado, o gerenciador de filtros alocará um contexto da lista lookaside se o tamanho do contexto na lista lookaside for maior ou igual ao tamanho solicitado. Caso contrário, o gerenciador de filtros alocará um contexto da lista lookaside somente se o tamanho do contexto na lista lookaside for igual ao tamanho solicitado.

ContextCleanupCallback

Um ponteiro para uma rotina ContextCleanupCallback definida por minifiltro do tipo PFLT_CONTEXT_CLEANUP_CALLBACK. O gerenciador de filtros chama essa rotina imediatamente antes de excluir o contexto. Se o minifiltro não tiver memória ou ponteiros para limpo dentro do contexto, esse membro será opcional e poderá ser NULL.

Size

O tamanho, em bytes, da parte definida por minifiltro do contexto, se o minifiltro usar contextos de tamanho fixo. Zero é um valor de tamanho válido. Se o minifiltro usar contextos de tamanho variável, esse membro será necessário e deverá ser definido como FLT_VARIABLE_SIZED_CONTEXTS.

PoolTag

Um valor de marca de pool a ser usado para o contexto. Essa marca, que é especificada como uma cadeia de caracteres de um a quatro caracteres ASCII de 7 bits, aparece em qualquer despejo de falha do sistema que ocorre. Se o membro ContextAllocateCallback for NULL, esse membro será necessário e não poderá ser zero.

ContextAllocateCallback

Ponteiro para uma rotina ContextAllocateCallback definida por minifiltro do tipo PFLT_CONTEXT_ALLOCATE_CALLBACK. Esse membro é opcional e pode ser NULL. Se não for NULL, os membros Size e PoolTag serão ignorados.

ContextFreeCallback

Um ponteiro para uma rotina ContextFreeCallback definida por minifiltro do tipo PFLT_CONTEXT_FREE_CALLBACK. Esse membro é opcional e pode ser NULL. Se não for NULL, os membros Size e PoolTag serão ignorados.

Reserved1

Reservado para uso do sistema. Os minifiltros devem definir esse membro como NULL.

Comentários

Quando um minifiltro chama FltRegisterFilter de sua rotina DriverEntry , ele deve registrar cada tipo de contexto que usa.

Para registrar esses tipos de contexto, o minifiltro cria uma matriz de comprimento variável de estruturas FLT_CONTEXT_REGISTRATION e armazena um ponteiro para a matriz no membro ContextRegistration da estrutura FLT_REGISTRATION que o minifiltro passa como o parâmetro Registration de FltRegisterFilter. O último elemento dessa matriz deve ser {FLT_CONTEXT_END}.

Para cada tipo de contexto que o minifiltro usa, o minifiltro deve fornecer pelo menos uma estrutura FLT_CONTEXT_REGISTRATION, de acordo com as seguintes regras:

Se o minifiltro fornecer uma estrutura FLT_CONTEXT_REGISTRATION com um membro ContextAllocateCallback não NULL, ele não poderá fornecer nenhuma estrutura de FLT_CONTEXT_REGISTRATION adicional para esse tipo de contexto.
Se o minifiltro fornecer duas ou mais estruturas de FLT_CONTEXT_REGISTRATION idênticas, somente a primeira será usada. Os outros serão ignorados.
Apenas um FLT_CONTEXT_REGISTRATION estrutura com um membro Size de FLT_VARIABLE_SIZED_CONTEXTS pode ser fornecido para cada tipo de contexto.
Não é possível fornecer mais de três estruturas de FLT_CONTEXT_REGISTRATION com um membro Size diferente de FLT_VARIABLE_SIZED_CONTEXTS para cada tipo de contexto.