Função FltCreateFileEx2 (fltkernel.h)

Artigo
03/08/2023

Os drivers de minifiltro chamam FltCreateFileEx2 para criar um novo arquivo ou abrir um arquivo existente. Essa rotina inclui um parâmetro de contexto de criação opcional (ECP).

Sintaxe

NTSTATUS FLTAPI FltCreateFileEx2(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ACCESS_MASK               DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in, optional]  PLARGE_INTEGER            AllocationSize,
  [in]            ULONG                     FileAttributes,
  [in]            ULONG                     ShareAccess,
  [in]            ULONG                     CreateDisposition,
  [in]            ULONG                     CreateOptions,
  [in, optional]  PVOID                     EaBuffer,
  [in]            ULONG                     EaLength,
  [in]            ULONG                     Flags,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parâmetros

[in] Filter

Um ponteiro de filtro opaco para o chamador.

[in, optional] Instance

Um ponteiro de instância opaco para a instância do driver de minifiltro para a qual a solicitação de criação deve ser enviada. A instância deve ser anexada ao volume em que o arquivo ou diretório reside. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a solicitação será enviada para o objeto do dispositivo na parte superior da pilha de driver do sistema de arquivos para o volume. Se esse parâmetro não for NULL, a solicitação será enviada apenas para instâncias de driver de minifiltro anexadas abaixo da instância especificada.

[out] FileHandle

Um ponteiro para uma variável alocada pelo chamador que recebe o identificador de arquivo se a chamada para FltCreateFileEx2 for bem-sucedida.

[out, optional] FileObject

Um ponteiro para uma variável alocada pelo chamador que recebe o ponteiro do objeto de arquivo se a chamada para FltCreateFileEx2 for bem-sucedida. Esse parâmetro é opcional e pode ser NULL.

[in] DesiredAccess

Uma máscara de bits de sinalizadores que especifica o tipo de acesso ao arquivo ou diretório exigido pelo chamador. Consulte o parâmetro DesiredAccess de IoCreateFileEx para obter mais informações sobre esse parâmetro e para obter a lista de valores de sinalizador.

[in] ObjectAttributes

Ponteiro para uma estrutura de OBJECT_ATTRIBUTES opaca que já está inicializada com InitializeObjectAttributes. Consulte o parâmetro ObjectAttributes de IoCreateFileEx para obter mais informações e para obter uma descrição de cada membro da estrutura.

[out] IoStatusBlock

Ponteiro para uma estrutura de IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. Consulte o parâmetro IoStatusBlock de IoCreateFileEx para obter mais informações sobre esse parâmetro.

[in, optional] AllocationSize

Opcionalmente, especifica o tamanho da alocação inicial, em bytes, para o fluxo de arquivos. Um valor diferente de zero não tem efeito, a menos que o arquivo esteja sendo criado, substituído ou substituído.

[in] FileAttributes

Especifica um ou mais sinalizadores FILE_ATTRIBUTE_XXX , que representam os atributos de arquivo a serem definidos se você estiver criando, substituindo ou substituindo um arquivo. Consulte o parâmetro FileAttributes de IoCreateFileEx para obter mais detalhes e para obter a lista de sinalizadores.

[in] ShareAccess

Especifica o tipo de acesso de compartilhamento ao arquivo que o chamador requer, como zero ou um, ou uma combinação dos sinalizadores. Consulte o parâmetro ShareAccess de IoCreateFileEx para obter mais detalhes e para obter a lista de sinalizadores.

[in] CreateDisposition

Especifica um valor que determina a ação a ser tomada, dependendo se o arquivo já existe. Consulte o parâmetro Disposition de IoCreateFileEx para obter a lista de valores possíveis.

[in] CreateOptions

Especifica as opções a serem aplicadas ao criar ou abrir o arquivo. Esse parâmetro é uma combinação compatível dos sinalizadores listados e descritos no parâmetro CreateOptions de IoCreateFileEx.

[in, optional] EaBuffer

Um ponteiro para um buffer de FILE_FULL_EA_INFORMATION fornecido pelo chamador que contém informações de atributo estendido (EA) a serem aplicadas ao arquivo.

[in] EaLength

Comprimento, em bytes, de EaBuffer.

[in] Flags

Especifica as opções a serem usadas durante a criação da solicitação de criação. Consulte o parâmetro Options de IoCreateFileEx para obter a lista de opções possíveis.

[in, optional] DriverContext

Ponteiro opcional para uma estrutura de IO_DRIVER_CREATE_CONTEXT já inicializada por IoInitializeDriverCreateContext.

Retornar valor

FltCreateFileEx2 retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado. Consulte a seção Valor retornado de IoCreateFileEx para obter uma lista de possíveis códigos de retorno.

Observação

FltCreateFileEx2 pode retornar STATUS_FILE_LOCK_CONFLICT como o valor retornado ou no membro Status da estrutura IO_STATUS_BLOCK que é apontado pelo parâmetro IoStatusBlock. Isso ocorrerá somente se o arquivo de log NTFS estiver cheio e ocorrer um erro enquanto FltCreateFileEx2 tentar lidar com essa situação.

Comentários

FltCreateFileEx2 é semelhante a FltCreateFile e FltCreateFileEx, exceto que ele dá suporte ao parâmetro de entrada DriverContext .

Para especificar um ECP como parte de uma operação de criação, inicialize o membro ExtraCreateParameter da estrutura IO_DRIVER_CREATE_CONTEXT com a rotina FltAllocateExtraCreateParameterList . Se os ECPs forem usados, eles deverão ser criados, manipulados e liberados usando as rotinas apropriadas.

Os drivers de filtro abaixo do chamador de FltCreateFileEx2 não devem adicionar ou excluir ECPs no chamador. Consequentemente, ao retornar da chamada para FltCreateFileEx2, a lista ECP deve ser inalterada e pode ser passada para chamadas adicionais de FltCreateFileEx2 para outras operações de criação. Observe que o sistema operacional não desaloca automaticamente a estrutura de lista ECP – o chamador de FltCreateFileEx2 deve desalocar essa estrutura chamando a rotina FltFreeExtraCreateParameterList .

Para criar/abrir um arquivo no contexto de uma transação, defina o membro TxnParameters da estrutura IO_DRIVER_CREATE_CONTEXT para o valor retornado pela rotina IoGetTransactionParameterBlock .

FltCreateFileEx2 envia a solicitação de criação somente para as instâncias anexadas abaixo da instância do driver de minifiltro especificada e para o sistema de arquivos. A instância especificada e as instâncias anexadas acima dela não recebem a solicitação de criação. Se nenhuma instância for especificada, a solicitação irá para a parte superior da pilha e será recebida por todas as instâncias e pelo sistema de arquivos.

Há duas maneiras alternativas de especificar o nome do arquivo a ser criado ou aberto com FltCreateFileEx2:

Como um nome de caminho totalmente qualificado, fornecido no membro ObjectName da entrada ObjectAttributes.
Como um nome de caminho relativo ao arquivo de diretório representado pelo identificador no membro RootDirectory do ObjectAttributes de entrada.

Qualquer FileHandle obtido de FltCreateFileEx2 deve eventualmente ser liberado chamando FltClose. Além disso, qualquer ponteiro FileObject retornado deve ser desreferenciado quando não for mais necessário chamando ObDereferenceObject.

Rotinas de driver que não são executadas no contexto do processo do sistema devem definir o atributo OBJ_KERNEL_HANDLE para o parâmetro ObjectAttributes de FltCreateFileEx2. Definir esse atributo restringe o uso do identificador retornado por FltCreateFileEx2 para processos em execução no modo kernel. Caso contrário, o identificador pode ser acessado pelo processo em cujo contexto o driver está em execução.

Observação

Não chame essa rotina com um valor IRP de nível superior não NULL, pois isso pode causar um deadlock do sistema.

Determinados sinalizadores DesiredAccess e combinações de sinalizadores têm os seguintes efeitos:

Para que um chamador sincronize uma conclusão de E/S aguardando que o FileHandle retornado seja definido como o estado Sinalizado, o sinalizador SYNCHRONIZE deve ser definido.
Se apenas os sinalizadores FILE_APPEND_DATA e SYNCHRONIZE estiverem definidos, o chamador poderá gravar somente no final do arquivo e quaisquer informações de deslocamento sobre solicitações de gravação no arquivo serão ignoradas. No entanto, o arquivo é automaticamente estendido conforme necessário para esse tipo de operação de gravação.
Definir o sinalizador FILE_WRITE_DATA para um arquivo também permite que ocorram solicitações de gravação além do final do arquivo. O arquivo também é estendido automaticamente para esse tipo de solicitação de gravação.
Se apenas os sinalizadores FILE_EXECUTE e SYNCHRONIZE estiverem definidos, o chamador não poderá usar o identificador retornado no parâmetro FileHandle para ler ou gravar diretamente dados de ou para o arquivo. Ou seja, todas as operações no arquivo devem usar a E/S de paginação do sistema para ler ou gravar dados de arquivo.

O parâmetro ShareAccess determina se threads separados podem acessar o mesmo arquivo, possivelmente simultaneamente. Se ambos os abridores de arquivos tiverem o privilégio de acessar um arquivo da maneira especificada, o arquivo poderá ser aberto e compartilhado com êxito. Se o chamador original de FltCreateFileEx2 não especificar FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, nenhuma outra operação aberta poderá ser executada no arquivo porque o chamador original recebe acesso exclusivo ao arquivo.

Para que um arquivo compartilhado seja aberto com êxito, o DesiredAccess solicitado ao arquivo deve ser compatível com as especificações DesiredAccess e ShareAccess de todas as solicitações abertas anteriores que ainda não foram lançadas com o FltClose. Ou seja, o parâmetro DesiredAccess especificado para FltCreateFileEx2 para um determinado arquivo não deve entrar em conflito com os acessos que outros abridores do arquivo não permitiram.

Observação

Se IO_IGNORE_SHARE_ACCESS_CHECK for especificado no parâmetro Flags , o gerenciador de E/S ignorará o parâmetro ShareAccess . No entanto, o sistema de arquivos ainda pode executar verificações de acesso. Portanto, é importante especificar o modo de compartilhamento que você deseja para o parâmetro ShareAccess, mesmo ao usar o sinalizador IO_IGNORE_SHARE_ACCESS_CHECK. Além disso, observe que quando IO_IGNORE_SHARE_ACCESS_CHECK é especificado, o sistema de arquivos não controla o acesso desejado ou o acesso compartilhado do open atual. Por isso, chamadas abertas subsequentes no mesmo arquivo podem ter êxito.

O valor CreateDisposition FILE_SUPERSEDE requer que o chamador tenha acesso DELETE a um objeto de arquivo existente. Nesse caso, uma chamada bem-sucedida para FltCreateFileEx2 com FILE_SUPERSEDE em um arquivo existente exclui efetivamente esse arquivo e o recria. Isso implica que, se o arquivo já tiver sido aberto por outro thread, ele abriu o arquivo especificando um parâmetro ShareAccesscom o sinalizador FILE_SHARE_DELETE definido. Observe que esse tipo de disposição é consistente com o estilo POSIX de substituir arquivos.

Os valores CreateDisposition FILE_OVERWRITE_IF e FILE_SUPERSEDE são semelhantes. Se FltCreateFileEx2 for chamado com um arquivo existente e qualquer um desses valores CreateDisposition , o arquivo será substituído.

Substituir um arquivo é semanticamente equivalente a uma operação de substituição, exceto pelo seguinte:

O chamador deve ter acesso de gravação ao arquivo, em vez de excluir o acesso. Isso implica que, se o arquivo já tiver sido aberto por outro thread, ele abriu o arquivo com o sinalizador FILE_SHARE_WRITE definido no parâmetro ShareAccess de entrada.
Os atributos de arquivo especificados são combinados com os atributos que já são aplicados ao arquivo usando uma operação OR bit a bit. Isso implica que, se o arquivo já tiver sido aberto por outro thread, um chamador subsequente de FltCreateFileEx2 não poderá desabilitar sinalizadores FileAttributes existentes , mas poderá habilitar sinalizadores adicionais para o mesmo arquivo. Observe que esse estilo de substituição de arquivos é consistente com MS-DOS, Windows 3.1 e SO/2.

O valor FILE_DIRECTORY_FILE CreateOptions especifica que o arquivo a ser criado ou aberto é um arquivo de diretório. Quando um arquivo de diretório é criado, o sistema de arquivos cria uma estrutura apropriada no disco para representar um diretório vazio para a estrutura no disco desse sistema de arquivos específico. Se essa opção tiver sido especificada e o arquivo a ser aberto não for um arquivo de diretório ou se o chamador tiver especificado um valor inconsistente de CreateOptions ou CreateDisposition , a chamada para FltCreateFileEx2 falhará.

O sinalizador FILE_NO_INTERMEDIATE_BUFFERING CreateOptions impede que o sistema de arquivos execute qualquer buffer intermediário em nome do chamador. Especificar esse valor coloca determinadas restrições nos parâmetros do chamador para outro Flt.. Rotinas de arquivo ou Zw.. Rotinas de arquivo, incluindo o seguinte:

Qualquer valor de deslocamento de byte passado para o parâmetro ByteOffset de FltReadFile, ZwReadFile, FltWriteFile ou ZwWriteFile deve ser um múltiplo do tamanho do setor.
O parâmetro Length passado para FltReadFile, ZwReadFile, FltWriteFile ou ZwWriteFile deve ser um múltiplo do tamanho do setor. Observe que especificar uma operação de leitura para um buffer cujo tamanho é exatamente o tamanho do setor pode resultar em menos bytes significativos sendo transferidos para esse buffer se o final do arquivo foi atingido durante a transferência.
Os buffers devem ser alinhados de acordo com o requisito de alinhamento do dispositivo de armazenamento subjacente. Essas informações podem ser obtidas chamando FltCreateFileEx2 para obter um identificador para o objeto de arquivo que representa o dispositivo físico e, em seguida, chamando ZwQueryInformationFile com esse identificador, especificando FileAlignmentInformation como o valor para o parâmetro FileInformationClass . Para obter mais informações sobre os valores FILE_XXX_ALIGNMENT do sistema, que são definidos em Ntifs.h, consulte DEVICE_OBJECT e Inicializando um objeto device.
Chamadas para FltSetInformationFile ou ZwSetInformationFile com o parâmetro FileInformationClass definido como FilePositionInformation devem especificar um deslocamento que seja um múltiplo do tamanho do setor.

Os sinalizadores FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT CreateOptions , que são mutuamente exclusivos como seus nomes sugerem, especificam que o arquivo está sendo aberto para E/S síncrona. Isso significa que todas as operações de E/S no arquivo devem ser síncronas, desde que ocorram por meio do objeto de arquivo ao qual o FileHandle retornado se refere. Toda E/S em um arquivo desse tipo é serializada em todos os threads usando o identificador retornado. Com qualquer um desses sinalizadores CreateOptions definido, o Gerenciador de E/S mantém o deslocamento de posição do arquivo atual no campo CurrentByteOffset do objeto de arquivo. Esse deslocamento pode ser usado em chamadas para ZwReadFile e ZwWriteFile. Ele também pode ser consultado ou definido chamando ZwQueryInformationFile ou ZwSetInformationFile.

Se o sinalizador FILE_OPEN_REPARSE_POINT CreateOptionsnão for especificado e FltCreateFileEx2 tentar abrir um arquivo com um ponto de nova análise, o processamento normal de ponto de nova análise ocorrerá para o arquivo. Se, por outro lado, o sinalizador FILE_OPEN_REPARSE_POINT for especificado, o processamento normal de nova análise não ocorrerá e FltCreateFileEx2 tentará abrir diretamente o arquivo de ponto de nova análise. Em ambos os casos, se a operação aberta tiver sido bem-sucedida, FltCreateFileEx2 retornará STATUS_SUCCESS; caso contrário, a rotina retornará um código de erro NTSTATUS. FltCreateFileEx2 nunca retorna STATUS_REPARSE.

O sinalizador FILE_OPEN_REQUIRING_OPLOCK CreateOptions elimina o tempo entre quando você abre o arquivo e solicita um oplock que pode potencialmente permitir que terceiros abram o arquivo e obtenham uma violação de compartilhamento. Um aplicativo pode usar o sinalizador FILE_OPEN_REQUIRING_OPLOCK em FltCreateFileEx2 e solicitar qualquer oplock. Isso garante que um proprietário do oplock seja notificado de qualquer solicitação aberta posterior que cause uma violação de compartilhamento.

No Windows 7, se outros identificadores existirem no arquivo quando um aplicativo usar o sinalizador FILE_OPEN_REQUIRING_OPLOCK, a operação de criação falhará com STATUS_OPLOCK_NOT_GRANTED. Essa restrição não existe mais começando com Windows 8.

Se essa operação de criação interromper um oplock que já existe no arquivo, definir o sinalizador FILE_OPEN_REQUIRING_OPLOCK fará com que a operação de criação falhe com STATUS_CANNOT_BREAK_OPLOCK. O oplock existente não será interrompido por esta operação de criação.

Um aplicativo que usa esse sinalizador deve solicitar um oplock depois que essa chamada for bem-sucedida ou todas as tentativas posteriores de abrir o arquivo serão bloqueadas sem o benefício do processamento de oplock típico. Da mesma forma, se essa chamada for bem-sucedida, mas a solicitação oplock posterior falhar, um aplicativo que usa esse sinalizador deverá fechar seu identificador depois de detectar que a solicitação oplock falhou.

Observação

O sinalizador FILE_OPEN_REQUIRING_OPLOCK está disponível nos sistemas operacionais Windows 7, Windows Server 2008 R2 e posteriores. Os sistemas de arquivos da Microsoft que implementam esse sinalizador no Windows 7 são NTFS, FAT e exFAT.

O sinalizador CreateOptions FILE_RESERVE_OPFILTER permite que um aplicativo solicite um oplock de nível 1, lote ou filtro para impedir que outros aplicativos receberem violações de compartilhamento. No entanto, FILE_RESERVE_OPFILTER só é praticamente útil para filtro oplocks. Para usá-lo, você deve concluir as seguintes etapas:

Emita uma solicitação de criação com CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess de exatamente FILE_READ_ATTRIBUTES e ShareAccess de exatamente FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- Se já houver identificadores abertos, a solicitação de criação falhará com STATUS_OPLOCK_NOT_GRANTED e o próximo oplock solicitado também falhará.
- Se você abrir com mais acesso ou menos compartilhamento, também causará uma falha de STATUS_OPLOCK_NOT_GRANTED.
Se a solicitação de criação for bem-sucedida, solicite um oplock.
Abra outro identificador para o arquivo fazer E/S.

A etapa três torna isso prático apenas para oplocks de filtro. O identificador aberto na etapa 3 pode ter um DesiredAccess que contém um máximo de FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL e ainda não quebrar um oplock de filtro. No entanto, qualquer DesiredAccess maior que FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE interromperá um oplock de nível 1 ou lote e tornará o sinalizador FILE_RESERVE_OPFILTER inútil para esses tipos de oplock.

O NTFS é o único sistema de arquivos da Microsoft que implementa FILE_RESERVE_OPFILTER.

Os drivers de minifiltro devem usar FltSetInformationFile, não ZwSetInformationFile, para renomear um arquivo.

Observação

Se você tentar abrir um volume, mas especificar apenas uma combinação dos sinalizadores a seguir para o parâmetro DesiredAccess , FltCreateFileEx2 abrirá um identificador, independentemente do sistema de arquivos, que tem acesso direto ao dispositivo de armazenamento para o volume.

FILE_READ_ATTRIBUTES
READ_CONTROL
WRITE_DAC
WRITE_OWNER
SYNCHRONIZE

Você não deve usar FltCreateFileEx2 para abrir um identificador com acesso direto ao dispositivo de armazenamento para o volume ou você vai vazar recursos do sistema. Se você quiser abrir um identificador com acesso direto a um dispositivo de armazenamento, chame a função IoCreateFileEx, IoCreateFileSpecifyDeviceObjectHint ou ZwCreateFile .

Quando um chamador de FltCreateFileEx2 deseja habilitar a nova análise para um destino de volume, um FLT_CREATEFILE_TARGET_ECP_CONTEXT pode ser incluído como um ECP para a lista ECP no parâmetro DriverContext . Se esse ECP estiver presente, FltCreateFileEx2 ajustará o dispositivo de destino para a operação de criação e tentará localizar uma instância filtrada de um volume apropriado para as informações de arquivo fornecidas. O uso desse ECP está disponível a partir do Windows 8.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows Vista.
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua FltKernel.h)
Biblioteca	Fltmgr.lib
IRQL	PASSIVE_LEVEL