Fonction NtQueryInformationFile (ntifs.h)

Article
02/29/2024

La routine NtQueryInformationFile retourne différents types d’informations sur un objet de fichier. Consultez également NtQueryInformationByName, qui peut être utilisé plus efficacement 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érez 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 de IO_STATUS_BLOCK qui reçoit le status d’achèvement final et des informations sur 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 à l’appelant dans laquelle la routine écrit les informations demandées sur l’objet de 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 à retourner sur le fichier, dans la mémoire tampon vers laquelle FileInformation pointe. Les pilotes d’appareil et intermédiaires peuvent spécifier l’une des valeurs FILE_INFORMATION_CLASS suivantes (répertoriées de la valeur d’énumération la plus basse à la valeur d’énumération la plus élevée) :

FILE_INFORMATION_CLASS valeur	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 aucune exigence particulière pour DesiredAccess.
FileInternalInformation (6)	Structure FILE_INTERNAL_INFORMATION . Cette structure spécifie un ID de fichier 64 bits qui identifie de manière unique un fichier dans NTFS. Sur d’autres systèmes de fichiers, il n’est pas garanti que cet ID de fichier soit 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 seulement une partie de celui-ci. L’appelant peut interroger ces informations tant que le fichier est ouvert, sans aucune exigence particulière 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 l’indicateur DesiredAccess FILE_READ_DATA ou 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 d’accès au fichier. 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 aucune exigence particulière pour DesiredAccess. Ces informations sont utiles si le fichier a été ouvert avec l’indicateur 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 nécessaires pour obtenir des informations sur un fichier.
FileAlternateNameInformation (21)	Une 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)	Une 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 aucune exigence particulière 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 qui est 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 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

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’il retourne zéro dans n’importe quel membre d’une structure FILE_XXX_INFORMATION qui n’est pas prise en charge par un appareil ou un système de fichiers particulier.

Quand 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 complet.
Si le handle ObjectAttributes-RootDirectory> a été ouvert par nom dans un appel à NtCreateFile et que le fichier a ensuite é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 l’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 dispose de SeChangeNotifyPrivilege (décrit dans la documentation Microsoft Windows SDK), NtQueryInformationFile retourne le chemin d’accès 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 seule barre oblique inverse, quel que soit son emplacement. Ainsi, le fichier C :\dir1\dir2\filename.ext s’affiche sous la forme \dir1\dir2\filename.ext, tandis que le fichier \server\share\dir1\dir2\filename.ext s’affiche 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 correspondra à 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 de fichier complet. Pour plus d’informations sur l’utilisation des fichiers, consultez Utilisation de fichiers dans un pilote.

Les appelants de NtQueryInformationFile doivent être en cours d’exécution à IRQL = PASSIVE_LEVEL et avec des API de noyau spéciales activées.

Notes

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 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