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:
| 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 do 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. 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. Consulte Comentários para obter mais informações.
| Valor | Significado |
|---|---|
| NonPagedPool | Memória do sistema não pageable. PoolType deve ser NonPagedPool se ContextType estiver FLT_VOLUME_CONTEXT. |
| do PagedPool | Memória do sistema paginável. |
| NonPagedPoolNx | Pool não executado (NX) nãopagado. |
[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 de retorno
FltAllocateContext retorna STATUS_SUCCESS ou um valor de 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 de FLT_CONTEXT_REGISTRATION para o ContextTypeespecificado. |
| STATUS_FLT_DELETING_OBJECT | O driver de minifiltro especificado no parâmetro Filter está sendo derrubado. 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. |
Observações
Para obter mais informações sobre contextos, consulte Sobre contextos de minifiltro.
FltAllocateContext aloca um contexto do tipo especificado do pool especificado. A partir do Windows 11, se a memória que ReturnedContext aponta é zero depende da seguinte maneira:
- A memória é garantida como 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, não é possível supor que a memória seja 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 do Windows 11, o conteúdo do contexto retornado não é zerado.
Definir poolType para 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 conjunto-contexto apropriada da tabela a seguir.
Quando um driver de minifiltro chama FltRegisterFilter de sua rotina de DriverEntry, ele deve registrar cada tipo de contexto usado. Para obter mais informações, consulte a entrada de referência para a estrutura de FLT_CONTEXT_REGISTRATION e Registrando tipos de contexto.
FltAllocateContext não inicializa o conteúdo da parte da estrutura de contexto específica para o 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
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| biblioteca | FltMgr.lib |
| de DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |