Fonction NtSetInformationFile (ntifs.h)

Article
07/11/2023

La routine NtSetInformationFile modifie différents types d’informations sur un objet file.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [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 file. Ce handle est créé par un appel réussi à NtCreateFile ou NtOpenFile.

[out] IoStatusBlock

Pointeur vers une structure de IO_STATUS_BLOCK qui reçoit le status d’achèvement final 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 par FileInformation, à définir pour le fichier. Les pilotes de périphérique et intermédiaires peuvent spécifier l’une des valeurs de FILE_INFORMATION_CLASS suivantes.

FILE_INFORMATION_CLASS valeur	Type d’informations retournées
FileBasicInformation (4)	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 .
FileRenameInformation (10)	Modifiez le nom de fichier actuel, qui est fourni dans une structure de FILE_RENAME_INFORMATION . L’appelant doit avoir un accès DELETE au fichier.
FileDispositionInformation (13)	Demande de supprimer le fichier lorsqu’il est fermé ou d’annuler une suppression précédemment demandée. Le choix de supprimer ou d’annuler 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 .
FilePositionInformation (14)	Modifiez les informations du fichier actuel, qui sont stockées dans une structure de FILE_POSITION_INFORMATION .
FileEndOfFileInformation (20)	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 .
FileValidDataLengthInformation (39)	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 .
FileShortNameInformation (40)	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 DesiredAccess DELETE défini dans le paramètre DesiredAccess .
FileIoPriorityHintInformation (43)	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.
FileReplaceCompletionInformation (61)	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 de 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 .
FileDispositionInformationEx (64)	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 .
FileCaseSensitiveInformation (71)	Modifiez les informations fournies dans une structure de FILE_CASE_SENSITIVE_INFORMATION . L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_WRITE_ATTRIBUTES défini dans le paramètre DesiredAccess . Cette valeur est disponible à partir de Windows 10, version 1803.
FileLinkInformation (72)	Créez un lien physique 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 physiques ; par exemple NTFS le fait alors que FAT ne le fait pas.
FileCaseSensitiveInformationForceAccessCheck (75)	Modifiez les informations fournies dans une structure de FILE_CASE_SENSITIVE_INFORMATION . L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_WRITE_ATTRIBUTES défini dans le paramètre DesiredAccess . Il s’agit d’une version spéciale de l’opération FileCaseSensitiveInformation qui est utilisée pour forcer l’IOManager à effectuer des vérifications d’accès pour le pilote en mode noyau, comme les vérifications qui s’appliquent à un appelant en mode utilisateur. Cette opération est uniquement reconnue par l’IOManager et un système de fichiers ne doit jamais la recevoir. Cette valeur est disponible à partir de Windows 10, version 1803.
FileKnownFolderInformation (76)	Structure FILE_KNOWN_FOLDER_INFORMATION . Disponible à partir de Windows Server 2022.

Valeur retournée

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

Remarques

NtSetInformationFile modifie les informations relatives à un fichier. Il 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 FileDispositionInformation, vous pouvez ensuite passer FileHandle à NtClose , mais pas à toute 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 sa fermeture.

Si vous définissez FileInformationClass sur FilePositionInformation et que l’appel précédent à NtCreateFile 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 NtCreateFile.

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, NtSetInformationFile é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 NtSetInformationFile doivent s’exécuter sur IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Notes

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

Pour les appels provenant 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
Client minimal pris en charge	Windows 2000.
Plateforme cible	Universal
En-tête	ntifs.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, PowerIrpDDis