Função FltAllocateContext (fltkernel.h)

Artigo
03/15/2024

A rotina FltAllocateContext aloca uma estrutura de contexto para um tipo de contexto especificado.

Sintaxe

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Parâmetros

[in] Filter

Ponteiro de filtro opaco para o chamador. Esse parâmetro é necessário e não pode ser NULL.

[in] ContextType

Um valor FLT_CONTEXT_TYPE que indica o tipo de contexto a ser alocado. ContextType pode ser um dos seguintes:

Valor	Significado
FLT_VOLUME_CONTEXT (0x0001)	Alocar um contexto de volume.
FLT_INSTANCE_CONTEXT (0x0002)	Alocar um contexto de instância.
FLT_FILE_CONTEXT (0x0004)	Alocar um contexto de arquivo.
FLT_STREAM_CONTEXT (0x0008)	Alocar um contexto de fluxo.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Alocar um contexto de identificador de fluxo.
FLT_TRANSACTION_CONTEXT (0x0020)	Alocar um contexto de transação.
FLT_SECTION_CONTEXT (0x0040)	Alocar um contexto de seção. Disponível a partir de Windows 8.

[in] ContextSize

O tamanho, em bytes, da parte do contexto definida pelo driver de minifiltro. Deve ser maior que zero e menor ou igual a MAXUSHORT; para contextos de tamanho fixo, deve ser menor ou igual ao Tamanho especificado na estrutura FLT_CONTEXT_REGISTRATION . Um minifiltro usa essa parte do contexto para manter informações de contexto específicas para si mesma. O FltMgr trata essa parte da estrutura de contexto como opaca. Esse parâmetro é necessário e não pode ser zero.

[in] PoolType

O tipo de pool a ser alocado. Esse parâmetro é necessário e deve ser um dos seguintes. Consulte POOL_TYPE para obter uma descrição detalhada de cada tipo. Confira Comentários para obter mais informações.

Valor	Significado
NonPagedPool	Memória do sistema não pageable. PoolType deverá ser NonPagedPool se ContextType for FLT_VOLUME_CONTEXT.
PagedPool	Memória do sistema paginável.
NonPagedPoolNx	Pool sem execução (NX).

[out] ReturnedContext

Ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto recém-alocado. O chamador é responsável por chamar FltReleaseContext para liberar esse contexto quando ele não for mais necessário.

Retornar valor

FltAllocateContext retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	As informações de alocação para o contexto do tipo especificado não foram fornecidas no momento do registro do filtro. OU, para contextos de tamanho fixo, o ContextSize solicitado é maior que o Tamanho especificado na estrutura FLT_CONTEXT_REGISTRATION para o ContextType especificado.
STATUS_FLT_DELETING_OBJECT	O driver de minifiltro especificado no parâmetro Filter está sendo dividido. Este é um código de erro.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_BUFFER_SIZE	ContextSize não pode ser maior que MAXUSHORT. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um valor inválido foi especificado para o ContextType ou o parâmetro ContextSize . Este é um código de erro.
STATUS_NOT_SUPPORTED	O sistema de arquivos não dá suporte a contextos por fluxo. Este é um código de erro.

Comentários

Para obter mais informações sobre contextos, consulte Sobre contextos de minifiltro.

FltAllocateContext aloca um contexto do tipo especificado do pool especificado. Começando em Windows 11, se a memória para a qual ReturnedContext aponta é zero depende da seguinte maneira:

A memória tem a garantia de ser zero para contextos de tamanho variável.
O conteúdo da memória é definido pela implementação para contextos de tamanho fixo alocados por uma função de retorno de chamada fornecida pelo chamador.
Caso contrário, a memória não pode ser considerada zero para contextos de tamanho fixo devido ao comportamento da lista lookaside. Ou seja, uma entrada retornada da lista lookaside poderá não ser zerada se for a memória que foi liberada anteriormente para a lista lookaside em vez de uma nova alocação.

Antes de Windows 11, o conteúdo do contexto retornado não é zerado.

Definir PoolType como um valor inválido pode resultar em um comportamento inesperado, como fazer com que listas lookaside sejam ignoradas, resultando na perda dos benefícios de desempenho das listas lookaside. Para contextos que têm uma função de retorno de chamada ContextAllocateCallback , o comportamento devido a um PoolType inválido depende da implementação.

Depois que o contexto é alocado, ele pode ser definido em um objeto passando o ponteiro ReturnedContext para a rotina de contexto de conjunto apropriada da tabela a seguir.

Tipo de contexto	Rotina de Set-Context
FLT_FILE_CONTEXT	FltSetFileContext (começando com o Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (começando com Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (começando com o Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Quando um driver de minifiltro chama FltRegisterFilter de sua rotina DriverEntry , ele deve registrar cada tipo de contexto que ele usa. Para obter mais informações, consulte a entrada de referência para a estrutura FLT_CONTEXT_REGISTRATION e Registrando tipos de contexto.

FltAllocateContext não inicializa o conteúdo da parte da estrutura de contexto específica do driver de minifiltro.

Para obter o contexto de um objeto, chame FltGetContexts ou a rotina de contexto de obtenção apropriada da tabela a seguir.

Tipo de contexto	Rotina de Get-Context
FLT_FILE_CONTEXT	FltGetFileContext (começando com o Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (começando com Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (começando com o Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Os contextos são contados por referência e, em um retorno bem-sucedido de FltAllocateContext, o contexto apontado por ReturnedContext foi inicializado para ter uma contagem de referência de 1. Um contexto é liberado automaticamente quando sua contagem de referência atinge zero. Para incrementar a contagem de referência em um contexto, chame FltReferenceContext.

Para diminuir a contagem de referência em um contexto, chame FltReleaseContext.

Como os contextos são contados por referência, geralmente não é necessário excluí-los. Para excluir um contexto explicitamente, chame FltDeleteContext ou a rotina de contexto de exclusão apropriada da tabela a seguir.

Tipo de contexto	Rotina de Delete-Context
FLT_FILE_CONTEXT	FltDeleteFileContext (começando com o Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (começando com Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (começando com o Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext