Função FltAllocateContext (fltkernel.h)

Artigo
09/24/2022
3 minutos para o fim da leitura

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. (Definir esse parâmetro como um valor inválido faz com que o sistema execute uma ASSERT em um build verificado.)

[in] ContextType

O tipo de contexto a ser alocado. ContextType pode ser um dos seguintes:

FLT_FILE_CONTEXT (começando com o Windows Vista)
FLT_INSTANCE_CONTEXT
FLT_SECTION_CONTEXT (começando com Windows 8)
FLT_STREAM_CONTEXT
FLT_STREAMHANDLE_CONTEXT
FLT_TRANSACTION_CONTEXT (começando com o Windows Vista)
FLT_VOLUME_CONTEXT

[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 driver de minifiltro usa essa parte do contexto para manter informações de contexto específicas para o driver de minifiltro. O gerenciador de filtros 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:

NonPagedPool
PagedPool (deve ser NonPagedPool se ContextType for FLT_VOLUME_CONTEXT)

Definir esse parâmetro como um valor inválido faz com que o sistema execute uma ASSERT em um build verificado.

[out] ReturnedContext

Ponteiro para uma variável alocada por 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.

Valor retornado

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 do 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. O conteúdo do contexto retornado não é zero.

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 (somente Windows 8 e posterior)
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 de FLT_CONTEXT_REGISTRATION e os tipos de contexto De registro.

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 decrementar 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