Fonction NtQueryInformationFile (ntifs.h)

Article
02/07/2025

La routine NtQueryInformationFile retourne différents types d’informations sur un objet de fichier. Consultez également NtQueryInformationByName, qui peut être plus efficace pour quelques classes d’informations de fichier.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Paramètres

[in] FileHandle

Gérer un objet de fichier. Le handle est créé par un appel réussi à NtCreateFile ou NtOpenFile, ou à une routine de création ou d’ouverture de fichier équivalente.

[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. Le membre Information reçoit le nombre d’octets que cette routine écrit réellement dans la mémoire tampon FileInformation.

[out] FileInformation

Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la routine écrit les informations demandées sur l’objet fichier. Le paramètre FileInformationClass spécifie le type d’informations que l’appelant demande.

[in] Length

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

[in] FileInformationClass

Spécifie le type d’informations à renvoyer sur le fichier, dans la mémoire tampon vers laquelle FileInformation pointe. Les pilotes de périphérique et intermédiaire peuvent spécifier l’une des valeurs de FILE_INFORMATION_CLASS suivantes (répertoriées entre la valeur d’énumération la plus basse et la plus élevée) :

valeur FILE_INFORMATION_CLASS	Type d’informations retournées
FileBasicInformation (4)	Structure FILE_BASIC_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_ATTRIBUTES spécifié dans le paramètre DesiredAccess.
FileStandardInformation (5)	Structure FILE_STANDARD_INFORMATION. L’appelant peut interroger ces informations tant que le fichier est ouvert, sans exigences particulières pour DesiredAccess.
FileInternalInformation (6)	Structure FILE_INTERNAL_INFORMATION. Cette structure spécifie un ID de fichier 64 bits qui identifie de façon unique un fichier dans NTFS. Sur d’autres systèmes de fichiers, cet ID de fichier n’est pas garanti comme unique.
FileEaInformation (7)	Structure FILE_EA_INFORMATION. Cette structure spécifie la taille du bloc d’attributs étendus associé au fichier.
FileAccessInformation (8)	Structure FILE_ACCESS_INFORMATION. Cette structure contient un masque d’accès. Pour plus d’informations sur les masques d’accès, consultez ACCESS_MASK.
FileNameInformation (9)	Structure FILE_NAME_INFORMATION. La structure peut contenir le chemin d’accès complet du fichier ou uniquement une partie de celui-ci. L’appelant peut interroger ces informations tant que le fichier est ouvert, sans exigences particulières pour DesiredAccess. Pour plus d’informations sur la syntaxe de nom de fichier, consultez la section Remarques plus loin dans cette rubrique.
FilePositionInformation (14)	Structure FILE_POSITION_INFORMATION. L’appelant doit avoir ouvert le fichier avec le FILE_READ_DATA DesiredAccess ou l’indicateur de FILE_WRITE_DATA spécifié dans le paramètre DesiredAccess, et avec l’indicateur FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT spécifié dans le paramètre CreateOptions .
FileModeInformation (16)	Structure FILE_MODE_INFORMATION. Cette structure contient un ensemble d’indicateurs qui spécifient le mode dans lequel le fichier est accessible. Ces indicateurs sont un sous-ensemble des options qui peuvent être spécifiées dans le paramètre CreateOptions de la routine IoCreateFile.
FileAlignmentInformation (17)	Structure FILE_ALIGNMENT_INFORMATION. L’appelant peut interroger ces informations tant que le fichier est ouvert, sans exigences particulières pour DesiredAccess. Ces informations sont utiles si le fichier a été ouvert avec l’indicateur de FILE_NO_INTERMEDIATE_BUFFERING spécifié dans le paramètre CreateOptions.
FileAllInformation (18)	Structure FILE_ALL_INFORMATION. En combinant plusieurs structures d’informations de fichier en une seule structure, FILE_ALL_INFORMATION réduit le nombre de requêtes requises pour obtenir des informations sur un fichier.
FileAlternateNameInformation (21)	Structure FILE_ALL_INFORMATION dans laquelle retourner les informations de nom de remplacement d’un fichier (son nom de format 8.3).
FileStreamInformation (22)	Mémoire tampon de FILE_STREAM_INFORMATION structures dans lesquelles énumérer les flux de données d’un fichier ou d’un répertoire.
FileCompressionInformation (28)	Structure FILE_COMPRESSION_INFORMATION dans laquelle retourner des informations de compression pour un fichier.
FileNetworkOpenInformation (34)	Structure FILE_NETWORK_OPEN_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_ATTRIBUTES spécifié dans le paramètre DesiredAccess.
FileAttributeTagInformation (35)	Structure FILE_ATTRIBUTE_TAG_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_ATTRIBUTES spécifié dans le paramètre DesiredAccess.
FileIoPriorityHintInformation (43)	Structure FILE_IO_PRIORITY_HINT_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_DATA spécifié dans le paramètre DesiredAccess.
FileSfioReserveInformation (44)	Structure FILE_SFIO_RESERVE_INFORMATION.
FileHardLinkInformation (46)	Structure FILE_LINKS_INFORMATION.
FileNormalizedNameInformation (48)	Structure FILE_NAME_INFORMATION dans laquelle retourner le nom normalisé d’un fichier.
FileIsRemoteDeviceInformation (51)	Structure FILE_IS_REMOTE_DEVICE_INFORMATION. L’appelant peut interroger ces informations tant que le fichier est ouvert, sans exigences particulières pour DesiredAccess.
FileStandardLinkInformation (54)	Structure FILE_STANDARD_LINK_INFORMATION.
FileIdInformation (59)	Structure FILE_ID_INFORMATION.
FileDesiredStorageClassInformation (67)	Structure FILE_DESIRED_STORAGE_CLASS_INFORMATION.
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Structure FILE_CASE_SENSITIVE_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_ATTRIBUTES spécifié dans le paramètre DesiredAccess. Cette valeur est disponible à partir de Windows 10 version 1803.
FileStorageReserveIdInformation (74)	Structure FILE_STORAGE_RESERVE_ID_INFORMATION.
FileCaseSensitiveInformationForceAccessCheck (75)	Structure FILE_CASE_SENSITIVE_INFORMATION. L’appelant doit avoir ouvert le fichier avec l’indicateur FILE_READ_ATTRIBUTES spécifié dans le paramètre DesiredAccess. Il s’agit d’une version spéciale de l’opération FileCaseSensitiveInformation utilisée pour forcer 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 reconnue uniquement par ioManager et un système de fichiers ne doit jamais le 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 de retour

NtQueryInformationFile retourne STATUS_SUCCESS ou un code d’erreur NTSTATUS approprié.

Remarques

NtQueryInformationFile retourne des informations sur l’objet de fichier spécifié. Notez qu’elle retourne zéro dans n’importe quel membre d’une structure_INFORMATION XXX FILE_qui n’est pas prise en charge par un appareil ou un système de fichiers particulier.

Lorsque FileInformationClass = FileNameInformation, le nom de fichier est retourné dans la structure FILE_NAME_INFORMATION. La syntaxe précise du nom de fichier dépend d’un certain nombre de facteurs :

Si vous avez ouvert le fichier en envoyant un chemin d’accès complet à NtCreateFile, NtQueryInformationFile retourne ce chemin d’accès complet.
Si le handle ObjectAttributes->RootDirectory a été ouvert par nom dans un appel à NtCreateFile, puis que le fichier a été ouvert par NtCreateFile par rapport à ce handle de répertoire racine, NtQueryInformationFile retourne le chemin d’accès complet.
Si le handle ObjectAttributes->RootDirectory a été ouvert par ID de fichier (à l’aide de l’indicateur FILE_OPEN_BY_FILE_ID) dans un appel à NtCreateFile, puis que le fichier a été ouvert par NtCreateFile par rapport à ce handle de répertoire racine, NtQueryInformationFile retourne le chemin relatif.
Toutefois, si l’utilisateur a SeChangeNotifyPrivilege (décrit dans la documentation du Kit de développement logiciel (SDK) Microsoft Windows), NtQueryInformationFile retourne le chemin complet dans tous les cas.
Si seul le chemin relatif est retourné, la chaîne de nom de fichier ne commence pas par une barre oblique inverse.
Si le chemin d’accès complet et le nom de fichier sont retournés, la chaîne commence par une barre oblique inverse unique, quel que soit son emplacement. Ainsi, le fichier C :\dir1\dir2\filename.ext apparaîtra sous la forme \dir1\dir2\filename.ext, tandis que le fichier \server\share\dir1\dir2\filename.ext apparaîtra sous la forme \server\share\dir1\dir2\filename.ext.

Si NtQueryInformationFile échoue en raison d’un dépassement de mémoire tampon, les pilotes qui implémentent FileNameInformation doivent retourner autant de caractères WCHAR du nom de fichier que cela correspond à la mémoire tampon et spécifier la longueur complète requise dans le paramètre FileNameLength de la structure FILE_NAME_INFORMATION. Vous devez réémettre la requête à l’aide de la longueur du nom de fichier afin de pouvoir récupérer le nom de fichier complet. Les pilotes qui ne suivent pas ce modèle peuvent nécessiter une augmentation progressive de la longueur jusqu’à ce qu’ils récupèrent le nom complet du fichier. Pour plus d’informations sur l’utilisation de fichiers, consultez Using Files in a Driver.

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

Note

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

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
client minimum pris en charge	Windows 2000.
plateforme cible	Universel
d’en-tête	ntifs.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, PowerIrpDDis