Função FltCreateSectionForDataScan (fltkernel.h)
A rotina
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.
| Bandeira | 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 de seção 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.
| Bandeira | 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 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
As máscaras de bits dos sinalizadores de XXX SEC_
| Bandeira | Significado |
|---|---|
| SEC_COMMIT | Aloca o armazenamento físico na memória ou no arquivo de paginação em 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 por 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
[out] SectionObject
Um ponteiro para uma variável alocada por chamador que recebe um ponteiro opaco para o objeto de seção.
[out, optional] SectionFileSize
Um ponteiro para uma variável alocada por 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.
Valor de retorno
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 |
| STATUS_FILE_LOCK_CONFLICT | O arquivo especificado pelo parâmetro FileObject |
| 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 |
| 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 pelo Instance já tem uma seção aberta para o fluxo. Há suporte para apenas uma seção por fluxo e, portanto, por instância. |
Observações
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 no objeto (SectionHandle) na tabela de identificador de processo do thread 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 que ObjectAttributes aponta é um identificador de kernel e só pode ser acessado no 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 viver em um aplicativo no 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 do 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 opcional de retorno de chamada para notificações desses eventos. O driver de minifiltro implementa um PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK para receber essas notificações. As notificações de conflito serão habilitadas se o SectionNotificationCallback membro 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.
Nota
Um retorno de chamada de notificação de seção pode ocorrer antes de fltCreateSectionForDataScan retorna. 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 (
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 de CreateFileMapping do
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 é 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 |
|---|---|
| de cliente com suporte mínimo | Windows 8 |
| da Plataforma de Destino |
Universal |
| cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| biblioteca | FltMgr.lib |
| IRQL | <= APC_LEVEL |
Consulte também
ObDereferenceObject