Função NtCreateFile (ntifs.h)

A rotina NtCreateFile cria um novo arquivo ou abre um arquivo existente.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [out]          PHANDLE            FileHandle,
  [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
);

Parâmetros

[out] FileHandle

Um ponteiro para uma variável HANDLE que recebe um identificador para o arquivo.

[in] DesiredAccess

Especifica um valor ACCESS_MASK que determina o acesso solicitado ao objeto.

Além dos direitos de acesso padrão definidos para todos os tipos de objetos, o chamador pode especificar qualquer um dos seguintes direitos de acesso específicos ; ou seja, direitos específicos aos arquivos.

sinalizador ACCESS_MASK Permite que o chamador faça isso
FILE_READ_DATA Ler dados do arquivo.
FILE_READ_ATTRIBUTES Leia os atributos do arquivo. Para obter mais informações, consulte a descrição do parâmetro FileAttributes .
FILE_READ_EA Leia os EAs (atributos estendidos) do arquivo. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
FILE_WRITE_DATA Escreva dados no arquivo.
FILE_WRITE_ATTRIBUTES Escreva os atributos do arquivo. Para obter mais informações, consulte a descrição do parâmetro FileAttributes .
FILE_WRITE_EA Altere os atributos estendidos (EAs) do arquivo. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
FILE_APPEND_DATA Acrescente dados ao arquivo.
FILE_EXECUTE Use a E/S de paginação do sistema para ler dados do arquivo na memória. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.

Observação

Não especifique FILE_READ_DATA, FILE_WRITE_DATA, FILE_APPEND_DATA ou FILE_EXECUTE ao criar ou abrir um diretório.

O chamador também pode especificar os seguintes direitos de acesso genérico (direitos que se aplicam a todos os tipos de objeto, em que o significado de cada direito de acesso genérico é específico do tipo de objeto). Os direitos de acesso genéricos para objetos de arquivo correspondem a direitos de acesso específicos, conforme mostrado na tabela a seguir. (Observe que "corresponder" significa "mapas para" e não significa que o valor do direito genérico seja "igual a" o valor do OR bit a bit de seu mapeamento de direitos específico). O gerente de E/S define o mapeamento real.

Direito de acesso genérico Mapeia para esses direitos de acesso específicos
GENERIC_READ STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA e SYNCHRONIZE
GENERIC_WRITE STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA e SYNCHRONIZE
GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE, FILE_EXECUTE, FILE_READ_ATTRIBUTES e SYNCHRONIZE. Esse valor é irrelevante para drivers intermediários e de dispositivo.
GENERIC_ALL FILE_ALL_ACCESS

Observação

Os direitos de acesso genéricos só podem ser especificados para um arquivo; eles não podem ser especificados para um diretório.

Alguns sinalizadores CreateOptions exigem que determinados sinalizadores de acesso sejam definidos em DesiredAccess quando NtCreateFile for chamado. Consulte o parâmetro CreateOptions para obter esses detalhes.

Por exemplo, se você especificar GENERIC_READ para um objeto de arquivo, a rotina mapeia esse valor para a FILE_GENERIC_READ máscara de bits de direitos de acesso específicos. Na tabela anterior, os direitos de acesso específicos listados para GENERIC_READ correspondem (mas não são iguais a) os sinalizadores de acesso contidos na máscara de bits FILE_GENERIC_READ.

Se o arquivo for realmente um diretório, o chamador também poderá especificar os direitos de acesso genéricos a seguir.

Sinalizador DesiredAccess Permite que o chamador faça isso
FILE_LIST_DIRECTORY Liste os arquivos no diretório.
FILE_TRAVERSE Percorra o diretório, em outras palavras, inclua o diretório no caminho de um arquivo.

Para obter mais informações sobre direitos de acesso, consulte ACCESS_MASK e Direitos de Acesso.

[in] ObjectAttributes

Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica o nome do objeto e outros atributos. Use InitializeObjectAttributes para inicializar essa estrutura. Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE quando chamar InitializeObjectAttributes.

[out] IoStatusBlock

Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e outras informações sobre a operação solicitada. Em particular, o membro information recebe um dos seguintes valores:

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Um ponteiro para um LARGE_INTEGER que contém o tamanho da alocação inicial, em bytes, para um arquivo criado ou substituído. Se AllocationSize for NULL, nenhum tamanho de alocação será especificado. Se nenhum arquivo for criado ou substituído, AllocationSize será ignorado.

[in] FileAttributes

Especifica um ou mais sinalizadores FILE_ATTRIBUTE_XXX , que representam os atributos de arquivo a serem definidos se você criar ou substituir um arquivo. O chamador geralmente especifica FILE_ATTRIBUTE_NORMAL, que define os atributos padrão. Para obter uma lista de sinalizadores FILE_ATTRIBUTE_XXX válidos, consulte a rotina CreateFile na documentação SDK do Microsoft Windows. Se nenhum arquivo for criado ou substituído, FileAttributes será ignorado.

[in] ShareAccess

Tipo de acesso de compartilhamento, que é especificado como zero ou qualquer combinação dos sinalizadores a seguir.

Sinalizador shareAccess Permite que outros threads façam isso
FILE_SHARE_READ Ler o arquivo
FILE_SHARE_WRITE Gravar o arquivo
FILE_SHARE_DELETE Excluir o arquivo

Os drivers intermediários e de dispositivo geralmente definem o ShareAccess como zero, o que fornece ao chamador acesso exclusivo ao arquivo aberto.

[in] CreateDisposition

Especifica a ação a ser executada se o arquivo existir ou não. CreateDisposition pode ser um dos valores na tabela a seguir.

Valor CreateDisposition Ação se o arquivo existir Ação se o arquivo não existir
FILE_SUPERSEDE Substitua o arquivo. Crie o arquivo.
FILE_CREATE Retornar um erro. Crie o arquivo.
FILE_OPEN Abra o arquivo. Retornar um erro.
FILE_OPEN_IF Abra o arquivo. Crie o arquivo.
FILE_OVERWRITE Abra o arquivo e substitua-o. Retornar um erro.
FILE_OVERWRITE_IF Abra o arquivo e substitua-o. Crie o arquivo.

[in] CreateOptions

Especifica as opções a serem aplicadas quando o driver cria ou abre o arquivo. Use um ou mais sinalizadores na tabela a seguir.

Sinalizador CreateOptions Significado
FILE_DIRECTORY_FILE (0x00000001) O arquivo é um diretório. Os sinalizadores CreateOptions compatíveis são FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID. O parâmetro CreateDisposition deve ser definido como FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF.
FILE_WRITE_THROUGH (0x00000002) Os serviços do sistema, os drivers do sistema de arquivos e os drivers que gravam dados no arquivo devem realmente transferir os dados para o arquivo antes que qualquer operação de gravação solicitada seja considerada concluída.
FILE_SEQUENTIAL_ONLY (0x00000004) Todo o acesso ao arquivo será sequencial.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) O arquivo não pode ser armazenado em cache ou armazenado em buffers internos de um driver. Esse sinalizador é incompatível com o sinalizador FILE_APPEND_DATA do parâmetro DesiredAccess .
FILE_SYNCHRONOUS_IO_ALERT (0x00000010) Todas as operações no arquivo são executadas de forma síncrona. Qualquer espera em nome do chamador está sujeita ao encerramento prematuro de alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o ponteiro de posição do arquivo. Se esse sinalizador estiver definido, o sinalizador SYNCHRONIZE deverá ser definido no parâmetro DesiredAccess .
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) Todas as operações no arquivo são executadas de forma síncrona. As esperas no sistema que sincronizam a enfileiramento e a conclusão de E/S não estão sujeitas a alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do arquivo. Se esse sinalizador estiver definido, o sinalizador SYNCHRONIZE deverá ser definido no parâmetro DesiredAccess .
FILE_NON_DIRECTORY_FILE (0x00000040) O arquivo não é um diretório. O objeto de arquivo a ser aberto pode representar um arquivo de dados; um dispositivo lógico, virtual ou físico; ou um volume.
FILE_CREATE_TREE_CONNECTION (0x00000080) Crie uma conexão de árvore para esse arquivo para abri-lo pela rede. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
FILE_COMPLETE_IF_OPLOCKED (0x00000100) Conclua essa operação imediatamente com um código de sucesso alternativo de STATUS_OPLOCK_BREAK_IN_PROGRESS se o arquivo de destino estiver bloqueado, em vez de bloquear o thread do chamador. Se o arquivo estiver oplocked, outro chamador já terá acesso ao arquivo. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
FILE_NO_EA_KNOWLEDGE (0x00000200) Se os atributos estendidos (EAs) de um arquivo existente que está sendo aberto indicarem que o chamador deve entender eAs para interpretar corretamente o arquivo, NtCreateFile deve retornar um erro. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
FILE_OPEN_REMOTE_INSTANCE (0x00000400) Reservado para uso do sistema; não use.
FILE_RANDOM_ACCESS (0x00000800) O acesso ao arquivo pode ser aleatório, portanto, nenhuma operação sequencial de leitura antecipada deve ser executada por drivers do sistema de arquivos ou pelo sistema.
FILE_DELETE_ON_CLOSE (0x00001000) O sistema exclui o arquivo quando o último identificador para o arquivo é passado para o NtClose. Se esse sinalizador for definido, o sinalizador DELETE deverá ser definido no parâmetro DesiredAccess .
FILE_OPEN_BY_FILE_ID (0x00002000) O nome do arquivo especificado pelo parâmetro ObjectAttributes inclui um número de referência de arquivo binário de 8 bytes ou 16 bytes ou uma ID de objeto para o arquivo, dependendo do sistema de arquivos. Opcionalmente, um nome de dispositivo seguido por um caractere de barra invertida pode continuar esses valores binários. Consulte Comentários para obter detalhes adicionais e um exemplo.
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000) O arquivo está sendo aberto para intenção de backup. Portanto, o sistema deve verificar determinados direitos de acesso e conceder ao chamador o acesso apropriado ao arquivo antes de verificar o parâmetro DesiredAccess no descritor de segurança do arquivo. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
FILE_NO_COMPRESSION (0x00008000) Suprime a herança de FILE_ATTRIBUTE_COMPRESSED do diretório pai. Isso permite a criação de um arquivo não compactado em um diretório marcado como compactado.
FILE_OPEN_REQUIRING_OPLOCK (0x00010000) O arquivo está sendo aberto e um bloqueio oportunista (oplock) no arquivo está sendo solicitado como uma única operação atômica. O sistema de arquivos verifica se há oplocks antes de executar a operação de criação e falhará na criação com um código de retorno de STATUS_CANNOT_BREAK_OPLOCK se o resultado for interromper um oplock existente. Esse sinalizador está disponível a partir do Windows 7 e do Windows Server 2008 R2.
FILE_DISALLOW_EXCLUSIVE (0x00020000) Ao abrir um arquivo existente, se FILE_SHARE_READ não for especificado e as verificações de acesso do sistema de arquivos não concederem ao chamador acesso de gravação ao arquivo, falhará com STATUS_ACCESS_DENIED. Esse era o comportamento padrão antes do Windows 7. Esse sinalizador está disponível a partir do Windows 7 e do Windows Server 2008 R2.
FILE_SESSION_AWARE (0x00040000) O cliente que abre o arquivo ou o dispositivo está ciente da sessão e o acesso por sessão é validado, se necessário. Esse sinalizador está disponível a partir de Windows 8.
FILE_RESERVE_OPFILTER (0x00100000) Esse sinalizador permite que um aplicativo solicite um filtro de bloqueio oportunista (oplock) para impedir que outros aplicativos sejam violações de compartilhamento. Se já houver identificadores abertos, a solicitação de criação falhará com STATUS_OPLOCK_NOT_GRANTED. Para obter mais informações, consulte a seção Comentários a seguir.
FILE_OPEN_REPARSE_POINT (0x00200000) Abra um arquivo com um ponto de nova análise e ignore o processamento normal de ponto de nova análise para o arquivo. Para obter mais informações, consulte a seção Comentários a seguir.
FILE_OPEN_NO_RECALL (0x00400000) Instrui todos os filtros que executam armazenamento offline ou virtualização para não lembrar o conteúdo do arquivo como resultado dessa abertura.
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) Esse sinalizador instrui o sistema de arquivos a capturar o usuário associado ao thread de chamada. Todas as chamadas subsequentes para FltQueryVolumeInformation ou ZwQueryVolumeInformationFile usando o identificador retornado assumirão que o usuário capturado, em vez do usuário de chamada no momento, para fins de calcular o espaço livre disponível para o chamador. Isso se aplica aos seguintes valores FsInformationClass: FileFsSizeInformation, FileFsFullSizeInformation e FileFsFullSizeInformationEx.
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000) Interprete o parâmetro EaBuffer como uma instância de EXTENDED_CREATE_INFORMATION. Esse sinalizador está disponível a partir de Windows 11, versão 22H2.

[in, optional] EaBuffer

Para drivers intermediários e de dispositivo, esse parâmetro deve ser um ponteiro NULL .

[in] EaLength

Para drivers intermediários e de dispositivo, esse parâmetro deve ser zero.

Retornar valor

NtCreateFile retorna STATUS_SUCCESS com êxito ou um código de erro NTSTATUS apropriado sobre falha. No último caso, o chamador pode determinar a causa da falha verificando o parâmetro IoStatusBlock .

Observação

NtCreateFile 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 NtCreateFile tentar lidar com essa situação.

Comentários

O NtCreateFile fornece um identificador que o chamador pode usar para manipular os dados de um arquivo ou o estado e os atributos do objeto de arquivo. Para obter mais informações, consulte Como usar arquivos em um driver.

Depois que o identificador apontado pelo FileHandle não estiver mais em uso, o driver deverá chamar NtClose para fechá-lo.

Se o chamador não estiver em execução em um contexto de thread do sistema, ele deverá garantir que todos os identificadores que ele cria sejam identificadores privados. Caso contrário, o identificador poderá ser acessado pelo processo em cujo contexto o driver está em execução. Para obter mais informações, consulte Identificadores de Objeto.

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

  • Como um nome de caminho totalmente qualificado, fornecido no membro ObjectName do ObjectAttributes de entrada.
  • Como nome de caminho em relação ao arquivo de diretório representado pelo identificador no membro RootDirectory do ObjectAttributes de entrada.

Definir determinados sinalizadores no parâmetro DesiredAccess resulta nos seguintes efeitos:

  • Para que um chamador sincronize uma conclusão de E/S aguardando o FileHandle retornado, o sinalizador SYNCHRONIZE deve ser definido. Caso contrário, um chamador que seja um dispositivo ou driver intermediário deve sincronizar uma conclusão de E/S usando um objeto de evento.
  • Se o chamador definir apenas os sinalizadores FILE_APPEND_DATA e SYNCHRONIZE, ele poderá gravar somente no final do arquivo e qualquer informação de deslocamento sobre operações de gravação no arquivo será ignorada. O arquivo será automaticamente estendido conforme necessário para esse tipo de operação.
  • Definir o sinalizador FILE_WRITE_DATA para um arquivo também permite que o chamador escreva além do final do arquivo. Novamente, o arquivo é automaticamente estendido conforme necessário.
  • Se o chamador definir apenas os sinalizadores FILE_EXECUTE e SYNCHRONIZE, ele não poderá ler ou gravar dados diretamente no arquivo usando o FileHandle retornado. Ou seja, todas as operações no arquivo ocorrem por meio do pager do sistema em resposta a operações de instrução e acesso a dados. Os drivers intermediários e de dispositivo não devem definir o sinalizador de FILE_EXECUTE.

O parâmetro ShareAccess determina se threads separados podem acessar o mesmo arquivo, possivelmente simultaneamente. Desde que ambos os chamadores tenham os privilégios de acesso apropriados, o arquivo pode ser aberto e compartilhado com êxito. Se o chamador original de NtCreateFile não especificar FILE_SHARE_READ, FILE_SHARE_WRITE ou FILE_SHARE_DELETE, nenhum outro chamador poderá abrir o arquivo, ou seja, o chamador original terá acesso exclusivo.

Para abrir um arquivo compartilhado com êxito, os sinalizadores DesiredAccess devem ser compatíveis com os sinalizadores DesiredAccess e ShareAccess de todas as operações abertas anteriores que ainda não foram lançadas. Ou seja, o DesiredAccess especificado para NtCreateFile para um determinado arquivo não deve entrar em conflito com os acessos que outros abridores do arquivo não permitiram.

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 NtCreateFile 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 ShareAccess com o conjunto de sinalizadores FILE_SHARE_DELETE. 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 NtCreateFile 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 ShareAccess de entrada.
  • Os atributos de arquivo especificados são logicamente ORed com aqueles que já estão no arquivo. Isso implica que, se o arquivo já tiver sido aberto por outro thread, um chamador subsequente de NtCreateFile 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, Microsoft Windows 3.1 e SO/2.

O valor FILE_DIRECTORY_FILE CreateOptions especifica que o arquivo a ser criado ou aberto é um 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 fornecido 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 NtCreateFile 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 sinalizador coloca as seguintes restrições nos parâmetros do chamador para outras rotinas de arquivo ZwXxx.

  • Qualquer ByteOffset opcional passado para NtReadFile ou NtWriteFile deve ser um múltiplo do tamanho do setor.
  • O Comprimento passado para NtReadFile ou NtWriteFile deve ser uma parte integrante do tamanho do setor. Observe que especificar uma operação de leitura para um buffer cujo comprimento é exatamente o tamanho do setor pode resultar em um número menor de 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 subjacente. Para obter essas informações, chame NtCreateFile para obter um identificador para o objeto de arquivo que representa o dispositivo físico e passe esse identificador para NtQueryInformationFile. Para obter uma lista dos valores FILE_XXX_ALIGNMENT do sistema, consulte DEVICE_OBJECT.
  • As chamadas para NtSetInformationFile 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) especificam que todas as operações de E/S no arquivo serão síncronas, desde que as operações ocorram por meio do objeto de arquivo referenciado pelo FileHandle retornado. Todas as E/S em um arquivo desse tipo são serializadas em todos os threads usando o identificador retornado. Se qualquer um desses sinalizadores CreateOptions estiver definido, o sinalizador SYNCHRONIZE DesiredAccess também deverá ser definido para obrigar o gerenciador de E/S a usar o objeto de arquivo como um objeto de sincronização. Nesses casos, o gerente de E/S mantém o controle do deslocamento de posição do arquivo atual, que você pode passar para NtReadFile e NtWriteFile. Chame NtQueryInformationFile ou NtSetInformationFile para obter ou definir essa posição.

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

O sinalizador createoptions FILE_OPEN_REQUIRING_OPLOCK elimina o tempo entre quando você abre o arquivo e solicita um oplock que poderia potencialmente permitir que um terceiro abra o arquivo e obtenha uma violação de compartilhamento. Um aplicativo pode usar o sinalizador FILE_OPEN_REQUIRING_OPLOCK no NtCreateFile e solicitar qualquer oplock. Isso garante que um proprietário oplock seja notificado de qualquer solicitação aberta subsequente que cause uma violação de compartilhamento.

No Windows 7, se houver outros identificadores 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 quebrar um oplock que já existe no arquivo, a configuração do 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 essa operação de criação.

Um aplicativo que usa o sinalizador FILE_OPEN_REQUIRING_OPLOCK deve solicitar um oplock depois que essa chamada for bem-sucedida ou todas as tentativas subsequentes de abrir o arquivo serão bloqueadas sem o benefício do processamento de oplock normal. Da mesma forma, se essa chamada for bem-sucedida, mas a solicitação oplock subsequente 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 do Windows. 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:

  1. Emita uma solicitação de criação com CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess 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.
  2. Se a solicitação de criação for bem-sucedida, solicite um oplock.
  3. Abra outro identificador no arquivo para fazer E/S.

A etapa 3 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 | SINCRONIZAR | READ_CONTROL e ainda não quebrar um oplock de filtro. No entanto, qualquer DesiredAccess maior que FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | SYNCHRONIZE quebrará 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.

Para o sinalizador createoptions FILE_OPEN_BY_FILE_ID, um nome de dispositivo de exemplo terá o formato:

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

em que FileID é 8 bytes e ObjectID é 16 bytes:

  • No NTFS, isso pode ser um número de referência de 8 bytes ou 16 bytes ou ID de objeto. Um número de referência de 16 bytes é o mesmo que um número de 8 bytes acolchoados com zeros.
  • No ReFS, isso pode ser um número de referência de 8 bytes ou 16 bytes. Um número de 16 bytes não está relacionado a um número de 8 bytes. Não há suporte para IDs de objeto.
  • Os sistemas de arquivos FAT, ExFAT, UDFS e CDFS não dão suporte ao sinalizador FILE_OPEN_BY_FILE_ID.

Esse número é atribuído e específico ao sistema de arquivos específico. Como o campo nome de arquivo conterá parcialmente um blob binário, é incorreto supor que essa é uma cadeia de caracteres Unicode válida e, mais importante, pode não ser uma cadeia de caracteres terminada nula.

Os chamadores de NtCreateFile devem estar em execução no IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Observação

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtCreateFile" em vez de "ZwCreateFile".

Para chamadas de drivers do modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas de serviços nativos do sistema.

Requisitos

   
Cliente mínimo com suporte Windows 2000
Plataforma de Destino Universal
Cabeçalho ntifs.h (incluem Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade DDI HwStorPortProhibitedDIs, PowerIrpDDis

Confira também

ACCESS_MASK

DEVICE_OBJECT

IO_STATUS_BLOCK

InitializeObjectAttributes

Usando versões Nt e Zw das rotinas de serviços nativos do sistema

NtClose

NtOpenFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile

NtWriteFile