ZwSetInformationFile, fonction (wdm.h)

Article
11/07/2024

La routine ZwSetInformationFile modifie différents types d’informations sur un objet de fichier.

Syntaxe

NTSYSAPI NTSTATUS ZwSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Paramètres

[in] FileHandle

Gérez l’objet de fichier. Ce handle est créé par un appel réussi à ZwCreateFile ou ZwOpenFile.

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et les informations relatives à l’opération demandée. L'Informations membre reçoit le nombre d’octets définis sur le fichier.

[in] FileInformation

Pointeur vers une mémoire tampon qui contient les informations à définir pour le fichier. La structure particulière de cette mémoire tampon est déterminée par le paramètre FileInformationClass. Par exemple, si le paramètre FileInformationClass est défini sur la constante FileDispositionInformationEx, ce paramètre doit être un pointeur vers une structure FILE_DISPOSITION_INFORMATION_EX.

[in] Length

Taille, en octets, de la mémoire tampon FileInformation.

[in] FileInformationClass

Type d’informations, fourni dans la mémoire tampon pointée par FileInformation, à définir pour le fichier. Les pilotes de périphérique et intermédiaire peuvent spécifier l’une des valeurs de FILE_INFORMATION_CLASS suivantes.

valeur FileInformationClass	Signification
FileBasicInformation	Modifiez les informations fournies dans une structure de FILE_BASIC_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur de FILE_WRITE_ATTRIBUTES défini dans le paramètre DesiredAccess.
FileDispositionInformation	Demande de suppression du fichier lorsqu’il est fermé ou annule une suppression précédemment demandée. Le choix entre la suppression ou l’annulation est fourni dans une structure FILE_DISPOSITION_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur DELETE défini dans le paramètre DesiredAccess.
FileDispositionInformationEx	Demande de suppression du fichier ou d’annulation d’une suppression précédemment demandée. Le choix entre la suppression ou l’annulation, ainsi que les paramètres de la façon dont la suppression doit être effectuée, sont fournis dans une structure FILE_DISPOSITION_INFORMATION_EX. L’appelant doit avoir ouvert le fichier avec l’indicateur DELETE** défini dans le paramètre DesiredAccess.
FileEndOfFileInformation	Modifiez les informations de fin de fichier actuelles, fournies dans une structure FILE_END_OF_FILE_INFORMATION. L’opération peut tronquer ou étendre le fichier. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_WRITE_DATA défini dans le paramètre DesiredAccess.
FileIoPriorityHintInformation	Modifiez l’indicateur de priorité IRP par défaut actuel pour le handle de fichier. La nouvelle valeur est fournie dans une structure FILE_IO_PRIORITY_HINT_INFORMATION. Cette structure doit être alignée sur 8 octets.
FileLinkInformation	Créez un lien dur vers un fichier existant, qui est spécifié dans une structure FILE_LINK_INFORMATION. Tous les systèmes de fichiers ne prennent pas en charge les liens durs ; par exemple, NTFS ne le fait pas, tandis que FAT ne le fait pas.
FilePositionInformation	Modifiez les informations actuelles du fichier, qui sont stockées dans une structure de FILE_POSITION_INFORMATION.
FileRenameInformation	Modifiez le nom de fichier actuel, fourni dans une structure FILE_RENAME_INFORMATION. L’appelant doit disposer d’un accès DELETE au fichier.
FileShortNameInformation	Modifiez le nom de fichier court actuel, fourni dans une structure FILE_NAME_INFORMATION. Le fichier doit se trouver sur un volume NTFS et l’appelant doit avoir ouvert le fichier avec l’indicateur DesiredAccess DELETE défini dans le paramètre DesiredAccess.
FileIoCompletionNotificationInformation	Modifiez les indicateurs de notification d’achèvement des E/S de fichier. Prend en charge les mêmes indicateurs que SetFileCompletionNotificationModes.
FileValidDataLengthInformation	Modifiez la longueur des données valides actuelle pour le fichier, qui est fournie dans une structure FILE_VALID_DATA_LENGTH_INFORMATION. Le fichier doit se trouver sur un volume NTFS et l’appelant doit avoir ouvert le fichier avec l’indicateur de FILE_WRITE_DATA défini dans le paramètre DesiredAccess. Les utilisateurs non administrateurs et distants doivent disposer du privilège SeManageVolumePrivilege.
FileReplaceCompletionInformation	Modifiez ou supprimez le port d’achèvement des E/S pour le handle de fichier spécifié. L’appelant fournit un pointeur vers une structure FILE_COMPLETION_INFORMATION qui spécifie un handle de port et une clé d’achèvement. Si le handle de port n’est pas NULL, ce handle spécifie un nouveau port d’achèvement d’E/S à associer au handle de fichier. Pour supprimer le port d’achèvement d’E/S associé au handle de fichier, définissez le handle de port dans la structure sur NULL. Pour obtenir un handle de port, un appelant en mode utilisateur peut appeler la fonction CreateIoCompletionPort.

Valeur de retour

ZwSetInformationFile retourne STATUS_SUCCESS ou un état d’erreur approprié.

Remarques

ZwSetInformationFile modifie les informations relatives à un fichier. Il ignore tout membre d’une structure_INFORMATION XXX FILE_qui n’est pas prise en charge par un appareil ou un système de fichiers particulier.

Si vous définissez FileInformationClass sur fileDispositionInformation, vous pouvez ensuite passer fileHandle à zwClose, mais pas à une autre routine ZwXxxFile. Étant donné que FileDispositionInformation provoque la suppression du fichier, il s’agit d’une erreur de programmation pour tenter toute opération ultérieure sur le handle autre que de la fermer.

Si vous définissez FileInformationClass sur FilePositionInformation, et que l’appel précédent à ZwCreateFile incluait l’indicateur FILE_NO_INTERMEDIATE_BUFFERING dans le paramètre createOptions , certaines restrictions sur le membre CurrentByteOffset membre de la structure FILE_POSITION_INFORMATION sont appliquées. Pour plus d’informations, consultez ZwCreateFile.

Si vous définissez FileInformationClass sur FileEndOfFileInformation, et que le membre EndOfFile de FILE_END_OF_FILE_INFORMATION spécifie un décalage au-delà de la marque de fin de fichier actuelle, ZwSetInformationFile étend le fichier et le remplissage de l’extension avec zéros.

Pour plus d’informations sur l’utilisation de fichiers, consultez Using Files in a Driver.

Les appelants de ZwSetInformationFile doivent s’exécuter à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Si l’appel à cette fonction se produit en mode utilisateur, vous devez utiliser le nom «NtSetInformationFile» au lieu de «ZwSetInformationFile».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Exigences

Exigence	Valeur
plateforme cible	Universel
d’en-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)
règles de conformité DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)