Função IoCreateFileEx (ntddk.h)

Artigo
03/08/2023

A rotina IoCreateFileEx faz com que um novo arquivo ou diretório seja criado ou abre um arquivo, dispositivo, diretório ou volume existente e dá ao chamador um identificador para o objeto de arquivo. Os drivers de filtro do sistema de arquivos (drivers de filtro herdados) chamam essa rotina.

Sintaxe

NTSTATUS IoCreateFileEx(
  [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] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

Parâmetros

[out] FileHandle

Um ponteiro para uma variável que receberá o identificador de arquivo se a chamada for bem-sucedida. O driver deve fechar o identificador com ZwClose assim que o identificador não estiver mais sendo usado.

[in] DesiredAccess

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

Sinalizador DesiredAccess	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 abaixo, podem ser lidos.
FILE_READ_EA	Os EAs (atributos estendidos) associados ao arquivo podem ser lidos.
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 associados ao arquivo podem ser gravados.
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.
SYNCHRONIZE	O chamador pode sincronizar a conclusão de uma operação de E/S aguardando que o FileHandle retornado seja 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.

Como alternativa, para qualquer objeto de arquivo que não represente um diretório, você pode especificar um ou mais dos seguintes sinalizadores genéricos de ACCESS_MASK. Os sinalizadores STANDARD_RIGHTS_XXX são valores predefinidos do sistema que são usados para impor a segurança em objetos do sistema. Você também pode combinar esses sinalizadores genéricos com sinalizadores adicionais da tabela anterior.

Acesso desejado a valores de arquivo	Mapeia para sinalizadores DesiredAccess
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

Para diretórios (o sinalizador FILE_DIRECTORY_FILE CreateOptions está definido), você pode especificar um ou mais dos sinalizadores de ACCESS_MASK a seguir, que você também pode combinar com quaisquer sinalizadores compatíveis descritos anteriormente.

Acesso desejado aos 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, ele 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

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

Membro	Valor
Comprimento do ULONG	O número de bytes dos dados ObjectAttributes fornecidos . Esse valor deve ser pelo menos `sizeof(OBJECT_ATTRIBUTES)`.
PUNICODE_STRING ObjectName	Ponteiro para uma cadeia de caracteres Unicode em buffer que contém o nome do 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 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 de unidade de disco disquete e o sistema de arquivos de sobreposição já estejam carregados. (Observação: "??" substitui "\DosDevices" como o nome do namespace do objeto Win32. "\DosDevices" ainda funciona, mas "??" é traduzido mais rapidamente pelo gerenciador de objetos.)
HANDLE RootDirectory	Identificador opcional para um diretório que foi obtido por uma chamada anterior para IoCreateFileEx. 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.
PSECURITY_DESCRIPTOR SecurityDescriptor	Descritor de segurança opcional 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 dessa ACL do arquivo de diretório pai combinado com a ACL padrão do chamador.
Atributos ULONG	Um conjunto de sinalizadores que controla os atributos de 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 OBJ_KERNEL_HANDLE . Opcionalmente, o chamador também pode definir 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

Ponteiro para uma variável do tipo IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. No retorno de IoCreateFileEx, o membro Information da variável 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 (por meio de uma operação OR bit a bit) de sinalizadores compatíveis. Os possíveis sinalizadores FileAttributes incluem o seguinte.

Sinalizadores FileAttributes	Significado
FILE_ATTRIBUTE_NORMAL	Um arquivo que tenha 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 IO_IGNORE_SHARE_ACCESS_CHECK for especificado no parâmetro Options , 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 esse parâmetro, mesmo quando você usa o sinalizador IO_IGNORE_SHARE_ACCESS_CHECK. Para ajudá-lo a 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 chamadas de criação de arquivo de outros threads.
FILE_SHARE_WRITE	O arquivo pode ser aberto para acesso de gravação por chamadas de criação de arquivo de outros threads.
FILE_SHARE_DELETE	O arquivo pode ser aberto para excluir o acesso por chamadas de criação de arquivo de outros threads.

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

[in] Disposition

Valor que determina como o arquivo deve ser tratado quando o arquivo já existe. A disposição pode ser uma das seguintes.

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

[in] CreateOptions

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

Sinalizador CreateOptions	Significado
FILE_DIRECTORY_FILE (0x00000001)	O arquivo que está sendo criado ou aberto é um arquivo de diretório. Com esse sinalizador, o parâmetro Disposition deve ser definido como um dos FILE_CREATE, FILE_OPEN ou FILE_OPEN_IF. Os sinalizadores CreateOptions compatíveis com esse sinalizador são os seguintes: FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT e FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH (0x00000002)	Os serviços do sistema, os sistemas 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)	Todos os acessos ao arquivo serão sequenciais.
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	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 (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 contexto de posição do arquivo. Se esse sinalizador for definido, o sinalizador DesiredAccess SYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização.
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	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 for definido, o sinalizador DesiredAccess SYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização.
FILE_NON_DIRECTORY_FILE (0x00000040)	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_CREATE_TREE_CONNECTION (0x00000080)	Crie uma conexão de árvore para esse arquivo para abri-lo pela rede.
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	Conclua essa operação imediatamente com um código de êxito alternativo 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 pela rede.
FILE_NO_EA_KNOWLEDGE (0x00000200)	Se os atributos estendidos em um arquivo existente que está sendo aberto indicarem que o chamador deve entender os atributos estendidos para interpretar corretamente o arquivo, falhe essa solicitação porque o chamador não entende como lidar com atributos estendidos.
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	Reservado para uso do sistema; não use.
FILE_RANDOM_ACCESS (0x00000800)	Os acessos ao arquivo podem ser aleatórios, portanto, nenhuma operação sequencial de leitura antecipada deve ser executada no arquivo por sistemas de arquivos ou pelo sistema operacional.
FILE_DELETE_ON_CLOSE (0x00001000)	Exclua o arquivo quando o último identificador para ele for passado para FltClose.
FILE_OPEN_BY_FILE_ID (0x00002000)	O arquivo está sendo aberto pela ID. O nome do arquivo contém o nome de um dispositivo e uma ID de 64 bits a ser usada para abrir o arquivo.
FILE_OPEN_FOR_BACKUP_INTENT (0x000004000)	O arquivo está sendo aberto para intenção de backup; Portanto, o sistema deve marcar para 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_NO_COMPRESSION (0x00008000)	Suprima 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 a operação de criação falhará com um código de retorno de STATUS_CANNOT_BREAK_OPLOCK se a operação de criação interromper um oplock existente. Esse sinalizador está disponível nos sistemas operacionais Windows 7, Windows Server 2008 R2 e posteriores do Windows.
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, não o abrirá com STATUS_ACCESS_DENIED. Esse era o comportamento padrão antes do Windows 7.
FILE_SESSION_AWARE (0x00040000)	O arquivo ou dispositivo está sendo aberto com reconhecimento de sessão. Se esse sinalizador não for especificado, os dispositivos por sessão (como um dispositivo que usa o Redirecionamento USB RemoteFX) não poderão ser abertos por processos em execução na sessão 0. Esse sinalizador não tem efeito para os chamadores que não estão na sessão 0. Esse sinalizador tem suporte apenas em edições de servidor do Windows. Não há suporte para esse sinalizador antes de Windows Server 2012.
FILE_RESERVE_OPFILTER (0x00100000)	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 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 a não recuperar 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 computar o espaço livre disponível para o chamador. Isso se aplica aos seguintes valores FsInformationClass: FileFsSizeInformation, FileFsFullSizeInformation e FileFsFullSizeInformationEx.

[in, optional] EaBuffer

Um ponteiro para uma variável fornecida pelo chamador do tipo FILE_FULL_EA_INFORMATION que contém informações de atributo estendido (EA) a serem aplicadas ao arquivo. Para drivers intermediários e de dispositivo, esse parâmetro deve ser NULL.

[in] EaLength

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

[in] CreateFileType

Os drivers devem definir esse parâmetro como CreateFileTypeNone.

[in, optional] InternalParameters

Os drivers devem definir esse parâmetro como NULL.

[in] Options

Especifica as opções a serem usadas durante a geração da solicitação de criação. Zero ou mais dos valores de sinalizador de bit a seguir podem ser usados.

Sinalizador de opções	Significado
IO_FORCE_ACCESS_CHECK	O gerente de E/S deve marcar a solicitação de criação no descritor de segurança do arquivo. Para obter mais informações, consulte Comentários.
IO_IGNORE_SHARE_ACCESS_CHECK	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.
IO_STOP_ON_SYMLINK	Se um ponto de junção, um link simbólico ou um ponto de nova análise global for encontrado ao abrir ou criar o arquivo, o gerente de E/S retornará STATUS_STOPPED_ON_SYMLINK. Além disso, uma estrutura REPARSE_DATA_BUFFER será retornada em IoStatusBlock-Information>. O chamador é responsável por liberar a estrutura REPARSE_DATA_BUFFER .
IO_OPEN_TARGET_DIRECTORY	Abra o diretório pai do arquivo.

[in, optional] DriverContext

Um ponteiro opcional para uma estrutura IO_DRIVER_CREATE_CONTEXT que foi inicializada anteriormente pela rotina IoInitializeDriverCreateContext . A estrutura IO_DRIVER_CREATE_CONTEXT pode ser usada para passar parâmetros adicionais para as rotinas IoCreateFileEx e FltCreateFileEx2 . Consulte a seção Comentários a seguir para obter mais informações.

Retornar valor

IoCreateFileEx retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes.

Código de retorno	Descrição
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	IoCreateFileEx retornará esse valor status se o parâmetro DriverContext não for NULL e se o objeto de dispositivo especificado não estiver anexado à pilha de driver do sistema de arquivos para o volume especificado no nome do arquivo ou diretório. Esse objeto de dispositivo é especificado pelo membro DeviceObjectHint da estrutura IO_DRIVER_CREATE_CONTEXT. Para obter mais informações, consulte IO_DRIVER_CREATE_CONTEXT.
STATUS_MOUNT_POINT_NOT_RESOLVED	IoCreateFileEx retornará esse valor status se o parâmetro DriverContext não for NULL e se o nome do arquivo ou diretório contiver um ponto de montagem que seja resolvido para um volume diferente daquele ao qual o objeto de dispositivo especificado está anexado. Esse objeto de dispositivo é especificado pelo membro DeviceObjectHint da estrutura IO_DRIVER_CREATE_CONTEXT. Para obter mais informações, consulte IO_DRIVER_CREATE_CONTEXT.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx retornará esse valor status se o parâmetro ObjectAttributes não contiver um membro RootDirectory, mas o membro ObjectName na estrutura OBJECT_ATTRIBUTES era uma cadeia de caracteres vazia ou não continha um caractere OBJECT_NAME_PATH_SEPARATOR. Isso indica a sintaxe incorreta para o caminho do objeto.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx retornará esse valor status se o sinalizador de parâmetro OptionsIO_STOP_ON_SYMLINK estiver definido e um link simbólico for encontrado ao abrir ou criar o arquivo.

Se a rotina IoCreateFileEx retornar um erro status, o chamador poderá encontrar informações adicionais sobre a causa da falha verificando o parâmetro IoStatusBlock.

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

Comentários

A rotina IoCreateFileEx é semelhante à rotina IoCreateFile e à rotina IoCreateFileSpecifyDeviceObjectHint, mas oferece funcionalidade adicional, incluindo acesso a ECPs (parâmetros de criação extra), dicas de objetos de dispositivo e informações de transação por meio do parâmetro DriverContext da rotina IoCreateFileEx. Para obter mais informações sobre esses parâmetros baseados em estrutura, consulte IO_DRIVER_CREATE_CONTEXT.

Os drivers de filtro do sistema de arquivos chamam IoCreateFileEx 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 do driver não recebem a solicitação de criação. No entanto, se o membro DeviceObjectHint da estrutura IO_DRIVER_CREATE_CONTEXT (passado pelo parâmetro DriverContext ) for NULL, a solicitação irá para a parte superior da pilha e será recebida por todos os filtros e pelo sistema de arquivos.

Se a solicitação de E/S não for para a parte superior da pilha de driver, ou seja, se o parâmetro DriverContext não for NULL e um objeto de dispositivo válido for especificado pelo membro DeviceObjectHint da estrutura IO_DRIVER_CREATE_CONTEXT, a seguinte restrição se aplicará:

Se o caminho do nome do arquivo que é passado para a rotina IoCreateFileEx contiver um ponto de montagem, o ponto de montagem deverá resolve para o mesmo volume em que o arquivo ou diretório reside.

O identificador obtido por IoCreateFileEx pode ser usado por chamadas subsequentes para manipular dados dentro do arquivo ou no estado ou atributos do objeto de arquivo. Qualquer identificador obtido de IoCreateFileEx deverá eventualmente ser liberado chamando ZwClose.

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

Como um nome de caminho totalmente qualificado, fornecido no membro ObjectName do parâmetro ObjectAttributes de entrada.
Como um nome de caminho relativo ao identificador no membro RootDirectory do parâmetro ObjectAttributes de entrada. (Esse identificador pode representar um arquivo de diretório.)

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 IoCreateFileEx. Isso restringe o uso do identificador retornado por IoCreateFileEx 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. Os drivers podem chamar InitializeObjectAttributes para definir o atributo OBJ_KERNEL_HANDLE.

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. 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 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 será 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 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 instruções e acessos a dados. Os drivers intermediários e de dispositivo não devem definir o sinalizador FILE_EXECUTE em DesiredAccess.

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 IoCreateFileEx 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 valor desiredAccess solicitado para o 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 ZwClose. Ou seja, o valor DesiredAccess especificado para IoCreateFileEx 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 Options , 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 valor disposição FILE_SUPERSEDE requer que o chamador tenha acesso DELETE a um objeto de arquivo existente. Nesse caso, uma chamada bem-sucedida para IoCreateFileEx 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, o thread 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 substituição de arquivos.

Os valores disposição FILE_OVERWRITE_IF e FILE_SUPERSEDE são semelhantes. Se IoCreateFileEx for chamado com um arquivo existente e qualquer um desses valores de Disposição , 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 IoCreateFileEx 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 com 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 fornecido a ser aberto não for um arquivo de diretório ou se o chamador tiver especificado um valor de CreateOptions ou Disposition inconsistente, a chamada para IoCreateFileEx 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 o Zw.. Rotinas de arquivo, incluindo o seguinte:

Qualquer ByteOffset opcional passado para ZwReadFile ou ZwWriteFile deve ser integral (inteiro múltiplo) do tamanho do setor.
O Length passado para ZwReadFile ou ZwWriteFile deve ser um integral 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 tiver sido 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 IoCreateFileEx 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 dos valores FILE_XXX_ALIGNMENT do sistema, confira DEVICE_OBJECT.
Chamadas para ZwSetInformationFile com o parâmetro FileInformationClass definido como FilePositionInformation devem especificar um deslocamento que seja um integral do tamanho do setor.

Os sinalizadores CreateOptions, FILE_SYNCHRONOUS_IO_ALERT e FILE_SYNCHRONOUS_IO_NONALERT mutuamente exclusivos especificam que todas as operações de E/S no arquivo devem ser síncronas, desde que ocorram por meio do objeto de arquivo referenciado pelo FileHandle retornado. Toda E/S em um arquivo desse tipo é serializada em todos os threads usando o identificador retornado. Com qualquer um desses valores 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 valores 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 ZwQueryInformationFile ou definida chamando ZwSetInformationFile.

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

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 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 seguir estas 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.

Para solicitações de criação originadas no modo de usuário, se o driver definir IO_FORCE_ACCESS_CHECK no parâmetro Options de IoCreateFileEx , ele também deverá definir OBJ_FORCE_ACCESS_CHECK no parâmetro ObjectAttributes . Para obter informações sobre esse sinalizador, consulte o membro Atributos do OBJECT_ATTRIBUTES.

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

IoCreateFileEx pode ser usado para obter um identificador para um volume.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	ntddk.h (inclua Ntddk.h, Ntifs.h, FltKernel.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL