Função ZwSetInformationFile (wdm.h)

Artigo
03/08/2023

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

Sintaxe

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [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 ZwCreateFile ou ZwOpenFile.

[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 .

FileInformationClass Valor	Significado
FileBasicInformation	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 .
FileDispositionInformation	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 .
FileDispositionInformationEx	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 .
FileEndOfFileInformation	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 .
FileIoPriorityHintInformation	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.
FileLinkInformation	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.
FilePositionInformation	Altere as informações de arquivo atuais, que são armazenadas em uma estrutura FILE_POSITION_INFORMATION .
FileRenameInformation	Altere o nome do arquivo atual, que é fornecido em uma estrutura FILE_RENAME_INFORMATION . O chamador deve ter acesso DELETE ao arquivo.
FileShortNameInformation	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 .
FileValidDataLengthInformation	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 .
FileReplaceCompletionInformation	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 .

Retornar valor

ZwSetInformationFile retorna STATUS_SUCCESS ou um erro apropriado status.

Comentários

ZwSetInformationFile 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 ZwClose, mas não para nenhuma outra rotina de Arquivo ZwXxx. 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 ZwCreateFile 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 ZwCreateFile.

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, ZwSetInformationFile 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 ZwSetInformationFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar 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
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include 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(storport), PowerIrpDDis(wdm)