Função FltCreateSectionForDataScan (fltkernel.h)

Artigo
08/07/2023

A rotina FltCreateSectionForDataScan cria um objeto de seção para um arquivo. Opcionalmente, o gerenciador de filtros pode sincronizar E/S com a seção criada.

Sintaxe

NTSTATUS FLTAPI FltCreateSectionForDataScan(
  [in]            PFLT_INSTANCE      Instance,
  [in]            PFILE_OBJECT       FileObject,
  [in]            PFLT_CONTEXT       SectionContext,
  [in]            ACCESS_MASK        DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  PLARGE_INTEGER     MaximumSize,
  [in]            ULONG              SectionPageProtection,
  [in]            ULONG              AllocationAttributes,
  [in]            ULONG              Flags,
  [out]           PHANDLE            SectionHandle,
  [out]           PVOID              *SectionObject,
  [out, optional] PLARGE_INTEGER     SectionFileSize
);

Parâmetros

[in] Instance

O ponteiro de instância opaco para a instância do driver de minifiltro cujo contexto deve ser recuperado.

[in] FileObject

O objeto de arquivo para um arquivo aberto. O objeto de seção será apoiado pelo arquivo especificado. Esse parâmetro é necessário e não pode ser NULL.

[in] SectionContext

Um ponteiro para um contexto de seção alocado anteriormente.

[in] DesiredAccess

O tipo de acesso para o objeto de seção como um ou mais dos sinalizadores de ACCESS_MASK a seguir.

Sinalizador	Permite que o chamador
SECTION_MAP_READ	Ler exibições da seção.
SECTION_MAP_WRITE	Escreva exibições da seção.
SECTION_QUERY	Consulte o objeto section para obter informações sobre a seção. Os drivers devem definir esse sinalizador.
SECTION_ALL_ACCESS	Todas as ações definidas pelos sinalizadores anteriores, bem como as definidas por STANDARD_RIGHTS_REQUIRED. Para obter mais informações sobre STANDARD_RIGHTS_REQUIRED, consulte ACCESS_MASK.

[in, optional] ObjectAttributes

Um ponteiro para uma estrutura de OBJECT_ATTRIBUTES opcional que especifica o nome do objeto e outros atributos. Use a macro InitializeObjectAttributes para inicializar essa estrutura.

[in, optional] MaximumSize

Esse parâmetro é reservado para uso futuro.

[in] SectionPageProtection

A proteção a ser colocada em cada página da seção. Especifique um dos valores a seguir. Esse parâmetro é necessário e não pode ser zero.

Sinalizador	Significado
PAGE_READONLY	Habilita o acesso somente leitura à região confirmada das páginas. Uma tentativa de gravar na região confirmada resulta em uma violação de acesso. Se o sistema diferenciar o acesso somente leitura e executar o acesso, uma tentativa de executar o código na região confirmada resultará em uma violação de acesso.
PAGE_READWRITE	Habilita o acesso de leitura e gravação à região confirmada das páginas.

[in] AllocationAttributes

Bitmasks dos sinalizadores SEC_XXX determinam os atributos de alocação da seção. Especifique um ou mais dos valores a seguir. Esse parâmetro é necessário e não pode ser zero.

Sinalizador	Significado
SEC_COMMIT	Aloca armazenamento físico na memória ou no arquivo de paginação no disco para todas as páginas de uma seção. Essa é a configuração padrão. Observe que esse sinalizador é necessário e não pode ser omitido.
SEC_FILE	O arquivo especificado pelo parâmetro FileObject é um arquivo mapeado.

[in] Flags

Esse parâmetro é reservado para uso futuro.

[out] SectionHandle

Um ponteiro para uma variável alocada pelo chamador que recebe um identificador opaco para a seção. Por padrão, o identificador de seção é um identificador de usuário. Se o chamador precisar de um identificador de kernel, ele deverá passar um ponteiro para uma estrutura de OBJECT_ATTRIBUTES inicializada no parâmetro ObjectAttributes com o sinalizador OBJ_KERNEL_HANDLE definido.

[out] SectionObject

Um ponteiro para uma variável alocada pelo chamador que recebe um ponteiro opaco para o objeto de seção.

[out, optional] SectionFileSize

Um ponteiro para uma variável alocada pelo chamador que recebe o tamanho, em bytes, do arquivo no momento em que o objeto de seção foi criado. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

FltCreateSectionForDataScan retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes.

Código de retorno	Descrição
STATUS_END_OF_FILE	O tamanho do arquivo especificado pelo parâmetro FileObject é zero.
STATUS_FILE_LOCK_CONFLICT	O arquivo especificado pelo parâmetro FileObject está bloqueado.
STATUS_INSUFFICIENT_RESOURCES	FltCreateSectionForDataScan encontrou uma falha de alocação de pool.
STATUS_INVALID_FILE_FOR_SECTION	O arquivo especificado pelo parâmetro FileObject não dá suporte a seções.
STATUS_INVALID_PARAMETER	O minifiltro não está registrado.
STATUS_INVALID_PARAMETER_8	O valor especificado para o parâmetro SectionPageProtection é inválido.
STATUS_INVALID_PARAMETER_9	O chamador especificou um valor inválido para o parâmetro AllocationAttributes .
STATUS_NOT_SUPPORTED	O volume anexado a essa instância não dá suporte a contextos de seção.
STATUS_PRIVILEGE_NOT_HELD	O chamador não tinha os privilégios necessários para criar um objeto de seção com o acesso especificado no parâmetro DesiredAccess .
STATUS_FILE_IS_A_DIRECTORY	O arquivo especificado pelo parâmetro FileObject é um diretório.
STATUS_FLT_CONTEXT_ALREADY_DEFINED	A instância de filtro especificada pela Instância já tem uma seção aberta para o fluxo. Há suporte para apenas uma seção por fluxo e, portanto, por instância.

Comentários

Antes de chamar FltCreateSectionForDataScan, um minifiltro deve primeiro registrar seu volume para verificação de dados chamando FltRegisterForDataScan. Assim como acontece com outros elementos de contexto de filtro, SectionContext é alocado pela primeira vez com FltAllocateContext.

FltCreateSectionForDataScan insere o identificador para o objeto (SectionHandle) na tabela de identificador de processo para o thread em que FltCreateSectionForDataScan é chamado.

Os identificadores podem ser identificadores de usuário ou identificadores de kernel. Um identificador criado com OBJ_KERNEL_HANDLE definido na estrutura OBJECT_ATTRIBUTES para a qual ObjectAttributes aponta é um identificador de kernel e só pode ser acessado do modo kernel. Um identificador criado sem o sinalizador OBJ_KERNEL_HANDLE é um identificador de usuário, que pode ser acessado do modo de usuário ou kernel. Um filtro pode criar um identificador de usuário e, em seguida, passá-lo para um aplicativo de modo de usuário para processamento. Por exemplo, um mecanismo de verificação de vírus pode residir em um aplicativo de modo de usuário e ser alimentado com identificadores de usuário de um filtro do sistema de arquivos.

Determinadas situações podem ocorrer em que manter uma seção aberta é incompatível com a E/S do arquivo atual. Em particular, a E/S de arquivo que dispara uma limpeza de cache pode causar incoerência de cache se a limpeza do cache for impedida devido a uma seção aberta. Um minifiltro pode fornecer uma rotina de retorno de chamada opcional para notificações desses eventos. O driver de minifiltro implementa uma PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK para receber essas notificações. As notificações de conflito serão habilitadas se o membro SectionNotificationCallback do FLT_REGISTRATION estiver definido como essa rotina de retorno de chamada quando o minifiltro for registrado. Quando uma notificação é recebida, a seção pode ser fechada para permitir que a operação de E/S conflitante continue.

Observação

Um retorno de chamada de notificação de seção pode ocorrer antes que FltCreateSectionForDataScan retorne. Um minifiltro deve ser capaz de receber o retorno de chamada e lidar com o caso em que SectionHandle e SectionObject ainda não são válidos.

Quando o objeto de seção criado por essa rotina não for mais necessário, feche o identificador do objeto de seção (SectionHandle) chamando a rotina ZwClose e desreferenciando o próprio objeto de seção (SectionObject) chamando a rotina ObDereferenceObject .

Para obter informações de visão geral sobre como criar seções mapeadas e exibições de memória, consulte Objetos de seção e exibições. Além disso, consulte a documentação da rotina CreateFileMapping no SDK do Microsoft Windows.

Importante

Os minifiltros não devem excluir explicitamente um contexto de seção passado para FltCreateSectionForDataScan. Não chame FltDeleteContext depois que um contexto de seção for passado para FltCreateSectionForDataScan. Um contexto de seção é desalocado e removido de um fluxo chamando FltCloseSectionForDataScan nesse caso.

Em geral, as seções devem ser criadas como somente leitura. Em particular, se um arquivo somente leitura estiver em uma transação e um minifiltro não criar uma seção somente leitura, uma gravação na seção será descartada e não será incluída como parte da transação.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
IRQL	<= APC_LEVEL