Função ZwSetInformationFile (wdm.h)

Artigo
11/07/2024

A rotina de 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 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 de 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.

valor de FileInformationClass	Significado
FileBasicInformation	Altere as informações fornecidas em uma estrutura de 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 escolha de excluir ou cancelar é fornecida em uma estrutura de 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 de FILE_END_OF_FILE_INFORMATION. A operação pode truncar ou estender o arquivo. O chamador deve ter aberto o arquivo com o sinalizador de 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 de 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.
FileIoCompletionNotificationInformation	Altere os sinalizadores de notificação de conclusão de E/S do arquivo. Dá suporte aos mesmos sinalizadores que SetFileCompletionNotificationModes.
FileValidDataLengthInformation	Altere o comprimento de dados válido atual para o arquivo, que é fornecido em uma estrutura de 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 do identificador de arquivo especificado. O chamador fornece um ponteiro para uma estrutura de 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.

Valor de retorno

ZwSetInformationFile retorna STATUS_SUCCESS ou um status de erro apropriado.

Observações

ZwSetInformationFile altera informações sobre um arquivo. Ele ignora qualquer membro de uma estrutura de_INFORMATION XXX FILE_que não tem suporte por um dispositivo ou sistema de arquivos específico.

Se você definir FileInformationClass para FileDispositionInformation, você poderá passar FileHandle para ZwClose, mas não para nenhuma outra rotina de de Arquivo xxx. 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 para FilePositionInformation e a chamada anterior para ZwCreateFile incluíram 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 para 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 adicionará 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 no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows 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 do sistema nativo.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)