Função NtCreateFile (winternl.h)

Cria um novo arquivo ou diretório ou abre um arquivo, dispositivo, diretório ou volume existente.

 

Essa função é o modo de usuário equivalente à função ZwCreateFile documentada no WDK (Windows Driver Kit).

Sintaxe

__kernel_entry 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]           PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

Parâmetros

[out] FileHandle

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

[in] DesiredAccess

O valor ACCESS_MASK que expressa o tipo de acesso que o chamador requer para o arquivo ou diretório. O conjunto de sinalizadores DesiredAccess definidos pelo sistema determina os direitos de acesso específicos a seguir para objetos de arquivo.

Valor	Significado
DELETE	O arquivo pode ser excluído.
FILE_READ_DATA	Os dados podem ser lidos no arquivo.
FILE_READ_ATTRIBUTES	Os sinalizadores FileAttributes, descritos posteriormente, podem ser lidos.
FILE_READ_EA	Atributos estendidos associados ao arquivo podem ser lidos. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
READ_CONTROL	A ACL (lista de controle de acesso) e as informações de propriedade associadas ao arquivo podem ser lidas.
FILE_WRITE_DATA	Os dados podem ser gravados no arquivo.
FILE_WRITE_ATTRIBUTES	Os sinalizadores FileAttributes podem ser gravados .
FILE_WRITE_EA	Os EAs (atributos estendidos) associados ao arquivo podem ser gravados. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
FILE_APPEND_DATA	Os dados podem ser acrescentados ao arquivo.
WRITE_DAC	A DACL (lista de controle de acesso discricionário) associada ao arquivo pode ser gravada.
WRITE_OWNER	As informações de propriedade associadas ao arquivo podem ser gravadas.
SINCRONIZAR	O FileHandle retornado pode ser aguardado para sincronizar com a conclusão de uma operação de E/S. Se FileHandle não tiver sido aberto para E/S síncrona, esse valor será ignorado.
FILE_EXECUTE	Os dados podem ser lidos na memória do arquivo usando e/S de paginação do sistema. Esse sinalizador é irrelevante para drivers de dispositivo e intermediários.

 

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

Os chamadores de NtCreateFile podem especificar uma ou uma combinação do seguinte, possivelmente usando um or bit a bit com sinalizadores compatíveis adicionais da lista de sinalizadores DesiredAccess anterior, para qualquer objeto de arquivo que não represente um arquivo de diretório.

Valor	Significado
FILE_GENERIC_READ	STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
FILE_GENERIC_WRITE	STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
FILE_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE

 

O valor FILE_GENERIC_EXECUTE é irrelevante para drivers intermediários e de dispositivo.

O STANDARD_RIGHTS_XXX são valores predefinidos do sistema usados para impor a segurança em objetos do sistema.

Para abrir ou criar um arquivo de diretório, conforme também indicado com o parâmetro CreateOptions , os chamadores de NtCreateFile podem especificar uma ou uma combinação do seguinte, possivelmente usando um bit a bit OR com um ou mais sinalizadores compatíveis da lista de sinalizadores DesiredAccess anterior.

Valor	Significado
FILE_LIST_DIRECTORY	Os arquivos no diretório podem ser listados.
FILE_TRAVERSE	O diretório pode ser percorrido: ou seja, ele pode fazer parte do nome do caminho de um arquivo.

[in] ObjectAttributes

Um ponteiro para uma estrutura já inicializada com InitializeObjectAttributes. Os membros dessa estrutura para um objeto de arquivo incluem o seguinte.

Valor	Significado
Comprimento do ULONG	Especifica o número de bytes de dados ObjectAttributes fornecidos . Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES).
HANDLE RootDirectory	Opcionalmente, especifica um identificador para um diretório obtido por uma chamada anterior para NtCreateFile. Se esse valor for NULL, o membro ObjectName deverá ser uma especificação de arquivo totalmente qualificada que inclua o caminho completo para o arquivo de destino. Se esse valor não for NULL, o membro ObjectName especificará um nome de arquivo relativo a esse diretório.
PUNICODE_STRING ObjectName	Aponta para uma cadeia de caracteres Unicode em buffer que nomeia o arquivo a ser criado ou aberto. Esse valor deve ser uma especificação de arquivo totalmente qualificada ou o nome de um objeto de dispositivo, a menos que seja o nome de um arquivo relativo ao diretório especificado por RootDirectory. Por exemplo, \Device\Floppy1\myfile.dat ou \?? \B:\myfile.dat pode ser a especificação de arquivo totalmente qualificada, desde que o driver disquete e o sistema de arquivos em excesso já estejam carregados. Para obter mais informações, consulte Nomes de arquivo, caminhos e namespaces.
Atributos ULONG	É um conjunto de sinalizadores que controla os atributos do objeto de arquivo. Esse valor pode ser zero ou OBJ_CASE_INSENSITIVE, o que indica que o código de pesquisa de nome deve ignorar o caso do membro ObjectName em vez de executar uma pesquisa de correspondência exata. O valor OBJ_INHERIT é irrelevante para drivers intermediários e de dispositivo.
PSECURITY_DESCRIPTOR SecurityDescriptor	Opcionalmente, especifica um descritor de segurança a ser aplicado a um arquivo. AS ACLs especificadas por esse descritor de segurança são aplicadas ao arquivo somente quando ele é criado. Se o valor for NULL quando um arquivo for criado, a ACL colocada no arquivo dependerá do sistema de arquivos; a maioria dos sistemas de arquivos propaga alguma parte dessa ACL do arquivo de diretório pai combinado com a ACL padrão do chamador. Drivers intermediários e de dispositivo podem definir esse membro como NULL.
PSECURITY_QUALITY_OF_SERVICE SecurityQualityOfService	Especifica os direitos de acesso que um servidor deve receber ao contexto de segurança do cliente. Esse valor não é NULL somente quando uma conexão com um servidor protegido é estabelecida, permitindo que o chamador controle quais partes do contexto de segurança do chamador são disponibilizadas para o servidor e se o servidor tem permissão para representar o chamador.

[out] IoStatusBlock

Um ponteiro para uma variável que recebe o status de conclusão final e informações sobre a operação solicitada. No retorno de NtCreateFile, o membro Information contém um dos seguintes valores:

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

[in, optional] AllocationSize

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

[in] FileAttributes

Os atributos de arquivo. Atributos especificados explicitamente são aplicados somente quando o arquivo é criado, substituído ou, em alguns casos, substituído. Por padrão, esse valor é um FILE_ATTRIBUTE_NORMAL, que pode ser substituído por uma combinação ORed de um ou mais sinalizadores FILE_ATTRIBUTE_xxxx , que são definidos em Wdm.h e NtDdk.h. Para obter uma lista de sinalizadores que podem ser usados com NtCreateFile, consulte CreateFile.

[in] ShareAccess

O tipo de acesso de compartilhamento que o chamador gostaria de usar no arquivo, como zero, ou como um ou uma combinação dos valores a seguir.

Valor	Significado
FILE_SHARE_READ	O arquivo pode ser aberto para acesso de leitura por chamadas de outros threads para NtCreateFile.
FILE_SHARE_WRITE	O arquivo pode ser aberto para acesso de gravação por chamadas de outros threads para NtCreateFile.
FILE_SHARE_DELETE	O arquivo pode ser aberto para excluir o acesso por chamadas de outros threads para NtCreateFile.

 

Para obter mais informações, confira o SDK do Windows.

[in] CreateDisposition

Especifica o que fazer, dependendo se o arquivo já existe, como um dos valores a seguir.

Valor	Significado
FILE_SUPERSEDE	Se o arquivo já existir, substitua-o pelo arquivo fornecido. Caso contrário, crie o arquivo especificado.
FILE_CREATE	Se o arquivo já existir, falhe na solicitação e não crie ou abra o arquivo fornecido. Caso contrário, crie o arquivo especificado.
FILE_OPEN	Se o arquivo já existir, abra-o em vez de criar um novo arquivo. Caso contrário, falhe na solicitação e não crie um novo arquivo.
FILE_OPEN_IF	Se o arquivo já existir, abra-o. Caso contrário, crie o arquivo especificado.
FILE_OVERWRITE	Se o arquivo já existir, abra-o e substitua-o. Se isso não acontecer, falhe na solicitação.
FILE_OVERWRITE_IF	Se o arquivo já existir, abra-o e substitua-o. Caso contrário, crie o arquivo especificado.

[in] CreateOptions

As opções a serem aplicadas ao criar ou abrir o arquivo, como uma combinação compatível dos sinalizadores a seguir.

Valor	Significado
FILE_DIRECTORY_FILE	O arquivo que está sendo criado ou aberto é um arquivo de diretório. Com esse sinalizador, o parâmetro CreateDisposition deve ser definido como FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF. Com esse sinalizador, outros sinalizadores CreateOptions compatíveis incluem apenas o seguinte: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO _NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID.
FILE_NON_DIRECTORY_FILE	O arquivo que está sendo aberto não deve ser um arquivo de diretório ou essa chamada falha. O objeto de arquivo que está sendo aberto pode representar um arquivo de dados, um dispositivo lógico, virtual ou físico ou um volume.
FILE_WRITE_THROUGH	Os aplicativos 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. Esse sinalizador será definido automaticamente se o sinalizador CreateOptionsFILE_NO_INTERMEDIATE _BUFFERING estiver definido.
FILE_SEQUENTIAL_ONLY	Todos os acessos ao arquivo são sequenciais.
FILE_RANDOM_ACCESS	Os acessos ao arquivo podem ser aleatórios, portanto, nenhuma operação sequencial de leitura antecipada deve ser executada no arquivo por FSDs ou pelo sistema.
FILE_NO_INTERMEDIATE_BUFFERING	O arquivo não pode ser armazenado em cache ou armazenado em buffer nos buffers internos de um driver. Esse sinalizador é incompatível com o sinalizador de FILE_APPEND_DATADesiredAccess.
FILE_SYNCHRONOUS_IO_ALERT	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 contexto de posição do arquivo. Se esse sinalizador estiver definido, o sinalizador DesiredAccessSYNCHRONIZE também deverá ser definido.
FILE_SYNCHRONOUS_IO_NONALERT	Todas as operações no arquivo são executadas de forma síncrona. As esperas no sistema para sincronizar a fila de E/S e a conclusão 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 DesiredAccessSYNCHRONIZE também deverá ser definido.
FILE_CREATE_TREE_CONNECTION	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_NO_EA_KNOWLEDGE	Se os atributos estendidos em um arquivo existente que está sendo aberto indicarem que o chamador deve entender os EAs para interpretar corretamente o arquivo, falhe essa solicitação porque o chamador não entende como lidar com EAs. Esse sinalizador é irrelevante para drivers intermediários e de dispositivo.
FILE_OPEN_REPARSE_POINT	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.
FILE_DELETE_ON_CLOSE	Exclua o arquivo quando o último identificador para ele for passado para NtClose. Se esse sinalizador for definido, o sinalizador DELETE deverá ser definido no parâmetro DesiredAccess .
FILE_OPEN_BY_FILE_ID	O nome do arquivo especificado pelo parâmetro ObjectAttributes inclui o número de referência do arquivo de 8 bytes para o arquivo. Esse número é atribuído por e específico ao sistema de arquivos específico. Se o arquivo for um ponto de nova análise, o nome do arquivo também incluirá o nome de um dispositivo. Observe que o sistema de arquivos FAT não dá suporte a esse sinalizador. Esse sinalizador não é usado por drivers intermediários e de dispositivo.
FILE_OPEN_FOR_BACKUP_INTENT	O arquivo está sendo aberto para intenção de backup. Portanto, o sistema deve marcar para 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_RESERVE_OPFILTER	Esse sinalizador permite que um aplicativo solicite um bloqueio oportunista de filtro (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.
FILE_OPEN_REQUIRING_OPLOCK	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. Para obter mais informações, consulte a seção Comentários. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse sinalizador. Esse sinalizador tem suporte nos seguintes sistemas de arquivos: NTFS, FAT e exFAT.
FILE_COMPLETE_IF_OPLOCKED	Conclua essa operação imediatamente com um código de êxito 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.

[in] EaBuffer

Ponteiro para um buffer de EA usado para passar atributos estendidos.

Nota Alguns sistemas de arquivos podem não dar suporte a buffers EA.

 

[in] EaLength

Comprimento do buffer do EA.

Retornar valor

NtCreateFile retorna STATUS_SUCCESS ou um erro apropriado status. Se ele retornar um erro status, o chamador poderá encontrar mais informações sobre a causa da falha verificando o IoStatusBlock. Para simplificar esse marcar, um aplicativo pode usar as macros NT_SUCCESS, NT_ERROR e NT_WARNING.

Comentários

O identificador, fornecido por NtCreateFile, pode ser usado por chamadas subsequentes para manipular dados dentro do arquivo ou do estado ou atributos do objeto de arquivo.

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 da entrada ObjectAttributes
• Como um nome de caminho relativo ao arquivo de diretório representado pelo identificador no membro RootDirectory do ObjectAttributes de entrada

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 o FileHandle retornado, o sinalizador SYNCHRONIZE deve ser definido.
• Passar um zero para DesiredFlags não é válido.
• Se apenas os sinalizadores FILE_APPEND_DATA e SYNCHRONIZE estiverem definidos, o chamador poderá gravar somente no final do arquivo e todas as informações de deslocamento sobre gravações 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 as gravações além do final do arquivo ocorram. O arquivo também é estendido automaticamente para esse tipo de gravação.
• Se apenas os sinalizadores FILE_EXECUTE e SYNCHRONIZE estiverem definidos, o chamador não poderá ler nem gravar dados diretamente no arquivo usando o FileHandle retornado, ou seja, todas as operações no arquivo ocorrerão por meio do pager do sistema em resposta à instrução e aos acessos a dados.

O parâmetro ShareAccess determina se threads separados podem acessar o mesmo arquivo, possivelmente simultaneamente. Desde que ambos os abridores de arquivos tenham o privilégio de acessar um arquivo da maneira especificada, 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, nenhuma outra operação aberta poderá ser executada no arquivo; ou seja, o chamador original recebe acesso exclusivo ao arquivo.

Para que um arquivo compartilhado seja aberto com êxito, o parâmetro DesiredAccess solicitado para o arquivo deve ser compatível com as especificações DesiredAccess e ShareAccess de todas as aberturas anteriores que ainda não foram lançadas com NtClose. Ou seja, o parâmetro 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 CreateDispositionFILE_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 novamente. Isso implica que, se o arquivo já tiver sido aberto por outro thread, ele abriu o arquivo especificando um parâmetro ShareAccess com o sinalizador FILE_SHARE_DELETE definido. Observe que esse tipo de disposição é consistente com o estilo POSIX de substituir arquivos. Os valores CreateDispositionFILE_OVERWRITE_IF e FILE_SUPERSEDE são semelhantes. Se ZwCreateFile for chamado com um arquivo existente e 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 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 sistemas operacionais MS-DOS, Windows 3.1 e OS/2.

O valor FILE_DIRECTORY_FILECreateOptions 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 NtCreateFile falhará.

O sinalizador CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 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 outras rotinas de Arquivo NtXXX, incluindo o seguinte:

• Qualquer ByteOffset opcional passado para a função NtReadFile ou NtWriteFile deve ser uma parte integrante do tamanho do setor.
• O Length 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 ajustados de acordo com o requisito de alinhamento do dispositivo subjacente. Essas informações podem ser obtidas chamando NtCreateFile para obter um identificador para o objeto de arquivo que representa o dispositivo físico e, em seguida, chamando NtQueryInformationFile com esse identificador. Para obter uma lista dos valores FILE_XXX_ALIGNMENT do sistema, consulte a documentação do SDK do Windows.
• As chamadas para NtSetInformationFile com o parâmetro FileInformationClass definido como FilePositionInformation devem especificar um deslocamento que seja uma parte integrante do tamanho do setor.

Os sinalizadores createOptionsFILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT , que são mutuamente exclusivos como seus nomes sugerem, especificam que todas as operações de E/S no arquivo devem ser síncronas, desde que ocorram por meio do objeto de arquivo referido pelo FileHandle retornado. Toda a E/S em um arquivo desse tipo é serializada em todos os threads usando o identificador retornado. Com qualquer uma dessas CreateOptions, o sinalizador DesiredAccessSYNCHRONIZE deve ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização. Com qualquer um desses Conjuntos de CreateOptions , o Gerenciador de E/S mantém o "contexto de posição do arquivo" para o objeto de arquivo, um deslocamento de posição de arquivo interno e atual. Esse deslocamento pode ser usado em chamadas para NtReadFile e NtWriteFile. Sua posição também pode ser consultada ou definida com NtQueryInformationFile e NtSetInformationFile.

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

O sinalizador FILE_OPEN_REQUIRING_OPLOCK do parâmetro CreateOptions elimina o tempo entre quando você abre o arquivo e solicita um oplock que poderia potencialmente permitir que um terceiro abrisse o arquivo, o que causaria uma violação de compartilhamento. Um aplicativo pode usar o sinalizador FILE_OPEN_REQUIRING_OPLOCK com NtCreateFile e solicitar qualquer oplock. Isso garante que um proprietário do oplock seja notificado de qualquer solicitação aberta subsequente que cause uma violação de compartilhamento.

No Windows 7, se outros identificadores existirem no arquivo quando um aplicativo usar esse sinalizador, 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á quebrado por essa 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 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.

Nota O sinalizador FILE_OPEN_REQUIRING_OPLOCK está disponível nos sistemas operacionais Windows 7, Windows Server 2008 R2 e posterior para os seguintes sistemas de arquivos: NTFS, FAT e exFAT.

 

O sinalizador de FILE_RESERVE_OPFILTER do parâmetro CreateOptions permite que um aplicativo solicite um oplock de Nível 1, Lote ou Filtro para impedir que outros aplicativos sejam violações de compartilhamento. No entanto, em termos práticos, o FILE_RESERVE_OPFILTER é útil apenas para oplocks de filtro. Para usá-lo, você deve concluir as seguintes etapas:

1. 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). As possíveis falhas são as seguintes:
   • 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 do que FILE_READ_ATTRIBUTES ou menos compartilhamento do que (FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE), a solicitação falhará com 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 três torna isso prático apenas para oplocks de filtro. O identificador aberto na etapa três 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 quebra 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 obter mais informações sobre oplocks, consulte Semântica oplock.

Observe que o arquivo de cabeçalho do WDK NtDef.h é necessário para muitas definições constantes, bem como para a macro InitializeObjectAttributes . Você também pode usar as funções LoadLibrary e GetProcAddress para vincular dinamicamente a NtDll.dll.

Requisitos

Requisito	Valor
Plataforma de Destino	Windows
Cabeçalho	winternl.h
Biblioteca	ntdll.lib
DLL	ntdll.dll