Função NtSetInformationFile (ntifs.h)

A rotina NtSetInformationFile altera vários tipos de informações sobre um objeto de arquivo.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parâmetros

[in] FileHandle

Manipule para o objeto de arquivo. Esse identificador é criado por uma chamada bem-sucedida para NtCreateFile ou NtOpenFile.

[out] IoStatusBlock

Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. O membro Information recebe o número de bytes definidos no arquivo.

[in] FileInformation

Ponteiro para um buffer que contém as informações a serem definidas para o arquivo. A estrutura específica nesse buffer é determinada pelo parâmetro FileInformationClass . Por exemplo, se o parâmetro FileInformationClass for definido como a constante FileDispositionInformationEx , esse parâmetro deverá ser um ponteiro para uma estrutura FILE_DISPOSITION_INFORMATION_EX .

[in] Length

O tamanho, em bytes, do buffer FileInformation .

[in] FileInformationClass

O tipo de informação, fornecida no buffer apontado por FileInformation, para definir para o arquivo. Os drivers intermediários e de dispositivo podem especificar qualquer um dos seguintes valores de FILE_INFORMATION_CLASS .

FILE_INFORMATION_CLASS valor Tipo de informação retornada
FileBasicInformation (4) Altere as informações fornecidas em uma estrutura FILE_BASIC_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess .
FileRenameInformation (10) Altere o nome do arquivo atual, que é fornecido em uma estrutura FILE_RENAME_INFORMATION . O chamador deve ter acesso DELETE ao arquivo.
FileDispositionInformation (13) Solicite a exclusão do arquivo quando ele for fechado ou cancelar uma exclusão solicitada anteriormente. A opção de excluir ou cancelar é fornecida em uma estrutura FILE_DISPOSITION_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador DELETE definido no parâmetro DesiredAccess .
FilePositionInformation (14) Altere as informações de arquivo atuais, que são armazenadas em uma estrutura FILE_POSITION_INFORMATION .
FileEndOfFileInformation (20) Altere as informações atuais de fim de arquivo, fornecidas em uma estrutura FILE_END_OF_FILE_INFORMATION . A operação pode truncar ou estender o arquivo. O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_DATA definido no parâmetro DesiredAccess .
FileValidDataLengthInformation (39) Altere o comprimento de dados válido atual para o arquivo, que é fornecido em uma estrutura FILE_VALID_DATA_LENGTH_INFORMATION . O arquivo deve estar em um volume NTFS e o chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_DATA definido no parâmetro DesiredAccess . Não administradores e usuários remotos devem ter o privilégio SeManageVolumePrivilege .
FileShortNameInformation (40) Altere o nome do arquivo curto atual, que é fornecido em uma estrutura FILE_NAME_INFORMATION . O arquivo deve estar em um volume NTFS e o chamador deve ter aberto o arquivo com o sinalizador DesiredAccess DELETE definido no parâmetro DesiredAccess .
FileIoPriorityHintInformation (43) Altere a dica de prioridade irp padrão atual para o identificador de arquivo. O novo valor é fornecido em uma estrutura FILE_IO_PRIORITY_HINT_INFORMATION . Essa estrutura deve estar alinhada a 8 bytes.
FileReplaceCompletionInformation (61) Altere ou remova a porta de conclusão de E/S para o identificador de arquivo especificado. O chamador fornece um ponteiro para uma estrutura FILE_COMPLETION_INFORMATION que especifica um identificador de porta e uma chave de conclusão. Se o identificador de porta não for NULL, esse identificador especificará uma nova porta de conclusão de E/S a ser associada ao identificador de arquivo. Para remover a porta de conclusão de E/S associada ao identificador de arquivo, defina o identificador de porta na estrutura como NULL. Para obter um identificador de porta, um chamador do modo de usuário pode chamar a função CreateIoCompletionPort .
FileDispositionInformationEx (64) Solicite a exclusão do arquivo ou cancele uma exclusão solicitada anteriormente. A opção de excluir ou cancelar, bem como as configurações de quando e como a exclusão deve ser executada, são fornecidas em uma estrutura FILE_DISPOSITION_INFORMATION_EX . O chamador deve ter aberto o arquivo com o sinalizador DELETE definido no parâmetro DesiredAccess .
FileCaseSensitiveInformation (71) Altere as informações fornecidas em uma estrutura FILE_CASE_SENSITIVE_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess . Esse valor está disponível a partir do Windows 10, versão 1803.
FileLinkInformation (72) Crie um link rígido para um arquivo existente, que é especificado em uma estrutura FILE_LINK_INFORMATION . Nem todos os sistemas de arquivos dão suporte a links rígidos; por exemplo, o NTFS faz enquanto FAT não.
FileCaseSensitiveInformationForceAccessCheck (75) Altere as informações fornecidas em uma estrutura FILE_CASE_SENSITIVE_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess . Esta é uma versão especial da operação FileCaseSensitiveInformation que é usada para forçar o IOManager a executar verificações de acesso para o driver do modo kernel, semelhante às verificações que se aplicam a um chamador do modo de usuário. Essa operação só é reconhecida pelo IOManager e um sistema de arquivos nunca deve recebê-la. Esse valor está disponível a partir do Windows 10, versão 1803.
FileKnownFolderInformation (76) Uma estrutura FILE_KNOWN_FOLDER_INFORMATION . Disponível a partir do Windows Server 2022.

Valor retornado

NtSetInformationFile retorna STATUS_SUCCESS ou um status de erro apropriado.

Comentários

NtSetInformationFile altera as informações sobre um arquivo. Ele ignora qualquer membro de uma estrutura FILE_XXX_INFORMATION que não tem suporte de um dispositivo ou sistema de arquivos específico.

Se você definir FileInformationClass como FileDispositionInformation, poderá passar FileHandle posteriormente para NtClose, mas não para qualquer outra rotina dearquivoZwXxx. Como FileDispositionInformation faz com que o arquivo seja marcado para exclusão, é um erro de programação tentar qualquer operação subsequente no identificador que não seja fechá-lo.

Se você definir FileInformationClass como FilePositionInformation e a chamada anterior para NtCreateFile incluir o sinalizador FILE_NO_INTERMEDIATE_BUFFERING no parâmetro CreateOptions , determinadas restrições no membro CurrentByteOffset da estrutura FILE_POSITION_INFORMATION serão impostas. Para obter mais informações, consulte NtCreateFile.

Se você definir FileInformationClass como FileEndOfFileInformation e o membro EndOfFile do FILE_END_OF_FILE_INFORMATION especificar um deslocamento além da marca de fim de arquivo atual, NtSetInformationFile estenderá o arquivo e preencherá a extensão com zeros.

Para obter mais informações sobre como trabalhar com arquivos, consulte Como usar arquivos em um driver.

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

Observação

Se a chamada para essa função ocorrer no modo de usuário, use o nome "NtSetInformationFile" em vez de "ZwSetInformationFile".

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

Requisitos

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

Confira também

Createiocompletionport

FILE_BASIC_INFORMATION

FILE_COMPLETION_INFORMATION

FILE_DISPOSITION_INFORMATION

FILE_END_OF_FILE_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_LINK_INFORMATION

FILE_NAME_INFORMATION

FILE_POSITION_INFORMATION

FILE_RENAME_INFORMATION

FILE_VALID_DATA_LENGTH_INFORMATION

ZwClose

ZwCreateFile

ZwOpenFile

ZwQueryInformationFile