Função IoCreateFileSpecifyDeviceObjectHint (ntddk.h)

Artigo
02/07/2025

A rotina IoCreateFileSpecifyDeviceObjectHint é usada por drivers de filtro do sistema de arquivos para enviar uma solicitação de criação apenas para os filtros abaixo de um objeto de dispositivo especificado e para o sistema de arquivos.

Sintaxe

NTSTATUS IoCreateFileSpecifyDeviceObjectHint(
  [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              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options,
  [in, optional] PVOID              DeviceObject
);

Parâmetros

[out] FileHandle

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

[in] DesiredAccess

Uma máscara de bits de sinalizadores que especifica o tipo de acesso que o chamador requer para o arquivo ou diretório. O conjunto de sinalizadores de DesiredAccess definidos pelo sistema determina os direitos de acesso específicos a seguir para objetos de arquivo.

Sinalizadores DesiredAccess	Significado
EXCLUIR	O arquivo pode ser excluído.
FILE_READ_DATA	Os dados podem ser lidos do arquivo.
FILE_READ_ATTRIBUTES	fileAttributes sinalizadores, descritos posteriormente, podem ser lidos.
FILE_READ_EA	Atributos estendidos (EA) associados ao arquivo podem ser lidos.
READ_CONTROL	A lista de controle de acesso (ACL) 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	sinalizadores FileAttributes podem ser gravados.
FILE_WRITE_EA	Atributos estendidos associados ao arquivo podem ser gravados.
FILE_APPEND_DATA	Os dados podem ser acrescentados ao arquivo.
WRITE_DAC	A lista de controle de acesso discricionário (DACL) associada ao arquivo pode ser gravada.
WRITE_OWNER	As informações de propriedade associadas ao arquivo podem ser gravadas.
SINCRONIZAR	O chamador pode sincronizar a conclusão de uma operação de E/S aguardando o FileHandle retornado para ser definido como o estado Sinalizado. Esse sinalizador deverá ser definido se o sinalizador CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT estiver definido.
FILE_EXECUTE	Os dados podem ser lidos na memória do arquivo usando e/S de paginação do sistema.

Os chamadores de IoCreateFileSpecifyDeviceObjectHint podem especificar um ou uma combinação dos seguintes, possivelmente ORed com sinalizadores compatíveis adicionais da lista anterior de sinalizadoresDesiredAccess DesiredAccess, para qualquer objeto de arquivo que não represente um arquivo de diretório:

DesiredAccess para arquivar valores	Mapas para sinalizadores DesiredAccess
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, SYNCHRONIZE, FILE_READ_ATTRIBUTES e FILE_EXECUTE.

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

Se o sinalizador FILE_DIRECTORY_FILE CreateOptions for definido, os chamadores de IoCreateFileSpecifyDeviceObjectHint poderão especificar um ou uma combinação dos seguintes, possivelmente ORed com um ou mais sinalizadores compatíveis da lista anterior de sinalizadoresDesiredAccess.

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

Os sinalizadores FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE e FILE_APPEND_DATA DesiredAccess são incompatíveis com a criação ou abertura de um arquivo de diretório.

[in] ObjectAttributes

Um ponteiro para uma estrutura de OBJECT_ATTRIBUTES já inicializada pela rotina InitializeObjectAttributes. Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro (ObjectAttributes) poderá ser NULL. Caso contrário, o chamador deve definir o atributo OBJ_KERNEL_HANDLE na chamada para a rotina de InitializeObjectAttributes. Os membros da estrutura de OBJECT_ATTRIBUTES de um objeto de arquivo incluem o seguinte.

Membro	Valor
ULONGLength	Especifica o número de bytes de ObjectAttributes dados fornecidos. Esse valor deve ter pelo menos tamanhos de(OBJECT_ATTRIBUTES).
objectName PUNICODE_STRING	Um ponteiro para uma cadeia de caracteres Unicode em buffer nomeando o arquivo a ser criado ou aberto. Esse valor deve ser uma especificação de arquivo totalmente qualificada, a menos que seja o nome de um arquivo relativo ao diretório especificado pelo 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. (Observe que \?? substitui \DosDevices como o nome do namespace do objeto Win32. \DosDevices ainda funcionará, mas \?? é traduzido mais rapidamente pelo gerenciador de objetos.)
HANDLERootDirectory	Opcionalmente, especifica um identificador para um diretório obtido por uma chamada anterior para IoCreateFileSpecifyDeviceObjectHint. 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 forNULL, o membro ObjectName especifica um nome de arquivo relativo a esse diretório.
securityDescriptor PSECURITY_DESCRIPTOR	Opcionalmente, especifica um descritor de segurança a ser aplicado a um arquivo. As ACLs especificadas por esse descritor de segurança só são aplicadas ao arquivo 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 de tal ACL do arquivo de diretório pai combinado com a ACL padrão do chamador.
ULONGAttributes	Um conjunto de sinalizadores que controla os atributos do objeto de arquivo. Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro poderá ser zero. Caso contrário, o chamador deverá definir o sinalizador de OBJ_KERNEL_HANDLE. O chamador também pode definir opcionalmente o sinalizador OBJ_CASE_INSENSITIVE, que indica que o código de pesquisa de nome deve ignorar o caso de ObjectName em vez de executar uma pesquisa de correspondência exata.

[out] IoStatusBlock

Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. Ao retornar de IoCreateFileSpecifyDeviceObjectHint, o membro de Informações do contém um dos seguintes valores:

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

Opcionalmente, especifica 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

Atributos explicitamente especificados são aplicados somente quando o arquivo é criado, substituído ou, em alguns casos, substituído. Por padrão, esse valor é FILE_ATTRIBUTE_NORMAL, que pode ser substituído por qualquer outro sinalizador ou por uma combinação ORed de sinalizadores compatíveis. Possíveis sinalizadores FileAttributes incluem o seguinte.

Sinalizadores FileAttributes	Significado
FILE_ATTRIBUTE_NORMAL	Um arquivo com atributos padrão deve ser criado.
FILE_ATTRIBUTE_READONLY	Um arquivo somente leitura deve ser criado.
FILE_ATTRIBUTE_HIDDEN	Um arquivo oculto deve ser criado.
FILE_ATTRIBUTE_SYSTEM	Um arquivo do sistema deve ser criado.
FILE_ATTRIBUTE_ARCHIVE	O arquivo deve ser marcado para que ele seja arquivado.
FILE_ATTRIBUTE_TEMPORARY	Um arquivo temporário deve ser criado.

[in] ShareAccess

Especifica o tipo de acesso de compartilhamento ao arquivo que o chamador gostaria, como zero, ou um, ou uma combinação dos sinalizadores a seguir. Para solicitar acesso exclusivo, defina esse parâmetro como zero. Se o sinalizador de IO_IGNORE_SHARE_ACCESS_CHECK for especificado no parâmetro opções, o gerenciador de E/S ignorará esse parâmetro. No entanto, o sistema de arquivos ainda pode executar verificações de acesso. Portanto, é importante especificar o modo de compartilhamento que você deseja para esse parâmetro, mesmo ao usar o sinalizador IO_IGNORE_SHARE_ACCESS_CHECK. Para obter a maior chance de evitar erros de violação de compartilhamento, especifique todos os sinalizadores de acesso de compartilhamento a seguir.

Sinalizadores do ShareAccess	Significado
FILE_SHARE_READ	O arquivo pode ser aberto para acesso de leitura por outros threads.
FILE_SHARE_WRITE	O arquivo pode ser aberto para acesso de gravação por outros threads.
FILE_SHARE_DELETE	O arquivo pode ser aberto para excluir o acesso por outros threads.

[in] Disposition

Especifica um valor que determina a ação a ser tomada, dependendo se o arquivo já existe. O valor pode ser qualquer um dos descritos a seguir.

Valores de disposição	Significado
FILE_SUPERSEDE	Se o arquivo já existir, substitua-o pelo arquivo especificado. Se isso não acontecer, crie o arquivo especificado.
FILE_CREATE	Se o arquivo já existir, falhe na solicitação e não crie ou abra o arquivo especificado. Se isso não acontecer, 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. Se isso não acontecer, crie o arquivo especificado.
FILE_OVERWRITE	Se o arquivo já existir, abra-o e substitua-o. Se isso não acontecer, falhará na solicitação.
FILE_OVERWRITE_IF	Se o arquivo já existir, abra-o e substitua-o. Se isso não acontecer, crie o arquivo especificado.

[in] CreateOptions

Especifica as opções a serem aplicadas ao criar ou abrir o arquivo. Essas opções são especificadas como uma combinação compatível dos sinalizadores a seguir.

Sinalizadores CreateOptions	Significado
FILE_DIRECTORY_FILE	O arquivo que está sendo criado ou aberto é um arquivo de diretório. Se esse sinalizador estiver definido, o parâmetro disposição deverá ser definido como um dos FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF. Esse sinalizador é compatível com os seguintes sinalizadores CreateOptions: 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 falhará. O objeto de arquivo que está sendo aberto deve representar um arquivo de dados.
FILE_WRITE_THROUGH	Os serviços do sistema, FSDs e 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	Todos os acessos ao arquivo serã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_DATA DesiredAccess.
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 a 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 DesiredAccess SYNCHRONIZE também deverá ser definido.
FILE_SYNCHRONOUS_IO_NONALERT	Todas as operações no arquivo são executadas de forma síncrona. As esperas que existem no sistema para sincronizar 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 DesiredAccess SYNCHRONIZE também deverá ser definido.
FILE_CREATE_TREE_CONNECTION	Crie uma conexão de árvore para esse arquivo para abri-la pela rede.
FILE_COMPLETE_IF_OPLOCKED	Conclua essa operação imediatamente com um código de sucesso alternativo se o arquivo de destino estiver bloqueado, em vez de bloquear o thread do chamador. Se o arquivo estiver oplockizado, outro chamador já terá acesso ao arquivo pela rede.
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.
FILE_OPEN_REPARSE_POINT	Abra um arquivo com um ponto de nova análise e ignore o processamento normal do ponto de nova análise para o arquivo. Para obter mais informações, consulte a seção comentários abaixo.
FILE_DELETE_ON_CLOSE	Exclua o arquivo quando o último identificador para ele for passado para ZwClose.
FILE_OPEN_BY_FILE_ID	O nome do arquivo especificado no parâmetro ObjectAttributes inclui o número de referência de arquivo de 8 bytes para o arquivo. Esse número é atribuído pelo sistema de arquivos e é específico do sistema de arquivos. Se o arquivo for um ponto de nova análise, o nome do arquivo também incluirá o nome de um dispositivo. Observação: o sistema de arquivos FAT não dá suporte a FILE_OPEN_BY_FILE_ID.
FILE_OPEN_FOR_BACKUP_INTENT	O arquivo está sendo aberto para a intenção de backup, portanto, o sistema deve verificar determinados direitos de acesso e conceder ao chamador os acessos apropriados ao arquivo antes de verificar a entrada DesiredAccess no descritor de segurança do arquivo.
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 a operação de criação falha com um código de retorno de STATUS_CANNOT_BREAK_OPLOCK se a criação interromperia um oplock existente.
FILE_RESERVE_OPFILTER	Esse sinalizador permite que um aplicativo solicite um filtro de bloqueio oportunista (oplock) para impedir que outros aplicativos sejam atingidos por 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.

[in, optional] EaBuffer

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

[in] EaLength

O comprimento, em bytes, de EaBuffer.

[in] CreateFileType

Os drivers devem definir esse parâmetro como CreateFileTypeNone.

[in, optional] InternalParameters

Os drivers devem definir esse parâmetro para NULL.

[in] Options

Especifica as opções a serem usadas durante a criação da solicitação de criação. A tabela a seguir lista as opções disponíveis.

Sinalizadores de opções	Significado
IO_FORCE_ACCESS_CHECK	Indica que o gerente de E/S deve verificar a solicitação de criação no descritor de segurança do arquivo.
IO_IGNORE_SHARE_ACCESS_CHECK	Indica que o gerenciador de E/S não deve executar verificações de acesso de compartilhamento no objeto de arquivo depois que ele é criado. No entanto, o sistema de arquivos ainda pode executar essas verificações.

[in, optional] DeviceObject

Um ponteiro para o objeto do dispositivo para o qual a solicitação de criação deve ser enviada. O objeto do dispositivo deve ser um objeto de dispositivo do sistema de arquivos ou filtro na pilha de driver do sistema de arquivos para o volume no qual 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 ao objeto do dispositivo na parte superior da pilha de driver.

Valor de retorno

IoCreateFileSpecifyDeviceObjectHint retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	O DeviceObject especificado não está anexado à pilha de driver do sistema de arquivos para o volume especificado no nome do arquivo ou diretório. Esse erro também poderá ocorrer se o nome contiver um ponto de nova análise diferente de um ponto de montagem.
STATUS_MOUNT_POINT_NOT_RESOLVED	O nome do arquivo ou diretório contém um ponto de montagem que é resolvido para um volume diferente daquele ao qual o DeviceObject especificado está anexado.
STATUS_OBJECT_PATH_SYNTAX_BAD

IoCreateFileSpecifyDeviceObjectHint pode retornar STATUS_FILE_LOCK_CONFLICT como o valor retornado ou no Status membro 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 IoCreateFileSpecifyDeviceObjectHint tentar lidar com essa situação.

Observações

Essa rotina é usada por drivers de filtro do sistema de arquivos para enviar uma solicitação de criação apenas para os filtros abaixo de um objeto de dispositivo especificado e para o sistema de arquivos. Os filtros anexados acima do objeto de dispositivo especificado na pilha de driver não recebem a solicitação de criação.

A rotina de IoCreateFileEx do Windows Vista é semelhante à rotina de IoCreateFileSpecifyDeviceObjectHint do, mas fornece uma funcionalidade maior do que a rotina de IoCreateFileSpecifyDeviceObjectHint, incluindo acesso a parâmetros de criação extra (ECPs) e informações de transação.

Se você usar a rotina de IoCreateFileEx em vez da rotina de IoCreateFileSpecifyDeviceObjectHint, observe que o parâmetro DriverContext do IoCreateFileSpecifyDeviceObjectHint foi movido para o DeviceObjectHint da estrutura IO_DRIVER_CREATE_CONTEXT. A estrutura de IO_DRIVER_CREATE_CONTEXT é passada para a rotina de IoCreateFileEx por meio de seu parâmetro DriverContext.

Os drivers de filtro do sistema de arquivos chamam IoCreateFileSpecifyDeviceObjectHint para enviar uma solicitação de criação apenas para um objeto de dispositivo especificado, os filtros anexados abaixo dele e o sistema de arquivos. Os filtros anexados acima do objeto de dispositivo especificado na pilha de driver não recebem a solicitação de criação. O mesmo é verdadeiro para qualquer solicitação de limpeza ou fechamento no objeto de arquivo criado por IoCreateFileSpecifyDeviceObjectHint.

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

Como um nome de caminho totalmente qualificado, fornecido no ObjectName membro 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 identificador obtido de IoCreateFileSpecifyDeviceObjectHint deve ser liberado chamando ZwClose.

As rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o atributo OBJ_KERNEL_HANDLE para o parâmetro ObjectAttributes de IoCreateFileSpecifyDeviceObjectHint. Isso restringe o uso do identificador retornado por IoCreateFileSpecifyDeviceObjectHint aos 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.

Certas DesiredAccess sinalizadores 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 qualquer informação de deslocamento sobre gravações no arquivo será ignorada. No entanto, o arquivo será automaticamente estendido conforme necessário para esse tipo de operação de gravação.
Definir o sinalizador de 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 ocorrem por meio do pager do sistema em resposta a instruções e 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 do IoCreateFileSpecifyDeviceObjectHint 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 receberá acesso exclusivo ao arquivo.

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

Se IO_IGNORE_SHARE_ACCESS_CHECK for especificado no parâmetro opções, 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.

O FILE_SUPERSEDE de disposição de requer que o chamador tenha acesso DELETE a um objeto de arquivo existente. Nesse caso, uma chamada bem-sucedida para IoCreateFileSpecifyDeviceObjectHint com FILE_SUPERSEDE em um arquivo existente efetivamente exclui esse arquivo e recria-o. 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 de FILE_SHARE_DELETE definido. Observe que esse tipo de disposição é consistente com o estilo POSIX de substituição de arquivos.

Os valores disposição FILE_OVERWRITE_IF e FILE_SUPERSEDE são semelhantes. Se IoCreateFileSpecifyDeviceObjectHint for chamado com um arquivo existente e qualquer um desses Disposição valores, 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 na entrada ShareAccess.
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 do IoCreateFileSpecifyDeviceObjectHint não poderá desabilitar os sinalizadores de FileAttributes existentes, mas poderá habilitar sinalizadores adicionais para o mesmo arquivo.

O valor CreateOptions FILE_DIRECTORY_FILE 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 em disco do 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 CreateOptions ou Disposição valor, a chamada para IoCreateFileSpecifyDeviceObjectHint falhará.

O sinalizador CreateOptions FILE_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 Zw.. Rotinas de de arquivo, incluindo o seguinte:

Qualquer valor de de deslocamento de bytes passado para ZwReadFile ou ZwWriteFile deve ser um múltiplo do tamanho do setor do dispositivo subjacente.
O length que é passado para ZwReadFile ou ZwWriteFile deve ser um múltiplo 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. Essas informações podem ser obtidas chamando IoCreateFileSpecifyDeviceObjectHint para obter um identificador para o objeto de arquivo que representa o dispositivo físico e, em seguida, chamando ZwQueryInformationFile com esse identificador. Para obter uma lista do sistema FILE_valores de_ALIGNMENT XXX, consulte DEVICE_OBJECT.
As chamadas para ZwSetInformationFile com o parâmetro FileInformationClass definido como FilePositionInformation devem especificar um deslocamento que seja um múltiplo do tamanho do setor.

O mutuamente exclusivo CreateOptions, FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT, 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. Todas as E/Ss em um arquivo desse tipo são serializadas em todos os threads usando o identificador retornado. Com qualquer um desses CreateOptions, o sinalizador DesiredAccess SYNCHRONIZE 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 CreateOptions definido, 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 ZwReadFile e ZwWriteFile . Sua posição também pode ser consultada chamando ZwQueryInformationFileou definida chamando ZwSetInformationFile.

Se o sinalizador CreateOptions FILE_OPEN_REPARSE_POINT não for especificado e IoCreateFileSpecifyDeviceObjectHint 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 IoCreateFileSpecifyDeviceObjectHint tentar abrir diretamente o arquivo de ponto de nova análise. Em ambos os casos, se a operação aberta tiver sido bem-sucedida, IoCreateFileSpecifyDeviceObjectHint retornará STATUS_SUCCESS; caso contrário, a rotina retorna um código de erro NTSTATUS. IoCreateFileSpecifyDeviceObjectHint 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 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 IoCreateFileSpecifyDeviceObjectHint 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 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 a partir do 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 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 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.

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 sejam atingidos por violações de compartilhamento. No entanto, FILE_RESERVE_OPFILTER só é praticamente útil para oplocks de filtro. Para usá-lo, você deve concluir as seguintes etapas:

Emita uma solicitação create com CreateOptions de FILE_RESERVE_OPFILTER, DesiredAccess exatamente FILE_READ_ATTRIBUTES e do ShareAccess 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 no arquivo para 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 filtro oplock. 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.

IoCreateFileSpecifyDeviceObjectHint não pode ser usado para obter um identificador para um volume.

Se o caminho do nome do arquivo passado para IoCreateFileSpecifyDeviceObjectHint contiver um ponto de nova análise, o ponto de nova análise deverá ser resolvido para o mesmo volume em que o arquivo ou diretório reside. Caso contrário, o erro STATUS_INVALID_DEVICE_OBJECT_PARAMETER ou STATUS_MOUNT_POINT_NOT_RESOLVED será retornado.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
cabeçalho	ntddk.h (incluem Ntddk.h, Ntifs.h, FltKernel.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL