Função FltAllocateContext (fltkernel.h)

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:

[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.

[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:

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.

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.

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.

Requisitos

Confira também

FLT_CONTEXT_REGISTRATION

FltCloseSectionForDataScan

FltCreateSectionForDataScan

FltDeleteContext

FltDeleteFileContext

FltDeleteInstanceContext

FltDeleteStreamContext

FltDeleteStreamHandleContext

FltDeleteTransactionContext

FltDeleteVolumeContext

FltGetContexts

FltGetFileContext

FltGetInstanceContext

FltGetSectionContext

FltGetStreamContext

FltGetStreamHandleContext

FltGetTransactionContext

FltGetVolumeContext

FltReferenceContext

FltRegisterFilter

FltReleaseContext

FltSetFileContext

FltSetInstanceContext

FltSetStreamContext

FltSetStreamHandleContext

FltSetTransactionContext

FltSetVolumeContext