Função NtSetInformationFile (ntifs.h)

Artigo
07/11/2023

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 a 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, fornecido no buffer apontado por FileInformation, a ser definido 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 de fim de arquivo atuais, 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 de 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 de 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 escolha 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 no 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.

Retornar valor

NtSetInformationFile retorna STATUS_SUCCESS ou um erro apropriado status.

Comentários

NtSetInformationFile altera 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 nenhuma 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 diferente de 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 de 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 Usando arquivos em um driver.

Os chamadores de NtSetInformationFile devem estar em execução em 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 de 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 Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

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