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

Requisitos

   
Plataforma de Destino Universal
Cabeçalho fltkernel.h (include Fltkernel.h)
Biblioteca FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

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