Fonction ZwQueryInformationFile (wdm.h)

Article
02/29/2024

La routine ZwQueryInformationFile retourne différents types d’informations sur un objet de fichier.

Syntaxe

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [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 à ZwCreateFile ou ZwOpenFile.

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

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.
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 .
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.
FileKnownFolderInformation (76)	Structure FILE_KNOWN_FOLDER_INFORMATION . Disponible à partir de Windows Server 2022.

Valeur retournée

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

Remarques

ZwQueryInformationFile 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 à ZwCreateFile, ZwQueryInformationFile retourne ce chemin complet.
Si le handle ObjectAttributes-RootDirectory> a été ouvert par nom dans un appel à ZwCreateFile et que le fichier a ensuite été ouvert par ZwCreateFile par rapport à ce handle de répertoire racine, ZwQueryInformationFile 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 à ZwCreateFile, puis que le fichier a été ouvert par ZwCreateFile par rapport à ce handle de répertoire racine, ZwQueryInformationFile retourne le chemin relatif.
Toutefois, si l’utilisateur a SeChangeNotifyPrivilege, ZwQueryInformationFile 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 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 ZwQueryInformationFile é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 qu’il convient dans 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 ZwQueryInformationFile doivent s’exécuter 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 « 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
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)