Função FltCreateSectionForDataScan (fltkernel.h)
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 |