Fonction ZwSetInformationFile (wdm.h)

Article
02/29/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’achèvement final status et des informations sur l’opération demandée. Le membre Information reçoit le nombre d’octets défini 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 vers FileInformation, à définir pour le fichier. Les pilotes d’appareil et intermédiaires peuvent spécifier l’une des valeurs FILE_INFORMATION_CLASS suivantes.

FileInformationClass Valeur	Signification
FileBasicInformation	Modifiez les informations fournies dans une structure de FILE_BASIC_INFORMATION . L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_WRITE_ATTRIBUTES défini dans le paramètre DesiredAccess .
FileDispositionInformation	Demande de suppression du fichier lors de sa fermeture ou d’annulation d’une suppression demandée précédemment. Le choix de supprimer ou d’annuler est fourni dans une structure de 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 de supprimer ou d’annuler, ainsi que les paramètres pour quand et comment 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 de 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 de FILE_LINK_INFORMATION . Tous les systèmes de fichiers ne prennent pas en charge les liens physiques ; par exemple NTFS fait alors que FAT ne le fait pas.
FilePositionInformation	Modifiez les informations de fichier actuelles, qui sont stockées dans une structure de FILE_POSITION_INFORMATION .
FileRenameInformation	Modifiez le nom de fichier actuel, qui est fourni dans une structure de FILE_RENAME_INFORMATION . L’appelant doit disposer d’un accès DELETE au fichier.
FileShortNameInformation	Modifiez le nom de fichier court actuel, qui est 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 DELETE DesiredAccess défini dans le paramètre DesiredAccess .
FileValidDataLengthInformation	Modifiez la longueur de données valide actuelle pour le fichier, qui est fournie dans une structure de 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 FILE_WRITE_DATA défini dans le paramètre DesiredAccess . Les non-administrateurs et les utilisateurs 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 des 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 retournée

ZwSetInformationFile retourne STATUS_SUCCESS ou une status d’erreur appropriée.

Remarques

ZwSetInformationFile modifie les informations relatives à un fichier. Elle ignore tout membre d’une structure FILE_XXX_INFORMATION qui n’est pas prise en charge par un appareil ou un système de fichiers particulier.

Si vous définissez FileInformationClass sur FileDispositionInformationInformation, vous pouvez ensuite passer FileHandle à ZwClose, mais pas à n’importe quelle autre routine de fichier ZwXxx. Étant donné que FileDispositionInformation entraîne la marque du fichier pour suppression, il s’agit d’une erreur de programmation qui consiste à tenter une opération ultérieure sur le handle autre que sa fermeture.

Si vous définissez FileInformationClass sur FilePositionInformationInformation 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 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 pads l’extension avec des zéros.

Pour plus d’informations sur l’utilisation des fichiers, consultez Utilisation de fichiers dans un pilote.

Les appelants de ZwSetInformationFile doivent être en cours d’exécution sur 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 dans 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (inclure 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)