FltGetVolumeGuidName, fonction (fltkernel.h)

Article
12/22/2024

FltGetVolumeGuidName obtient le nom du volume pour un volume donné, au format GUID (Global Unique Identifier).

Syntaxe

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

Paramètres

[in] Volume

Pointeur opaque pour le volume. Doit être un volume de système de fichiers local. Ce paramètre est obligatoire et ne peut pas être NULL.

[in/out, optional] VolumeGuidName

Pointeur vers une structure UNICODE_STRING allouée par l’appelant qui reçoit le nom GUID du volume lorsque STATUS_SUCCESS est retourné. N’oubliez pas que le pool pour VolumeGuidName -> tampon est également alloué à l’appelant.

Si VolumeGuidName est NULL et BufferSizeNeeded n’est pas NULL , FltGetVolumeGuidName stocke la taille de mémoire tampon nécessaire pour le GUID de volume demandé dans le paramètre BufferSizeNeededed et retourne STATUS_BUFFER_TOO_SMALL. Voir les remarques.

[out, optional] BufferSizeNeeded

Pointeur vers une variable allouée par l’appelant qui reçoit la taille, en octets, du nom du GUID de volume demandé. Ce paramètre est facultatif et peut être NULL ; Toutefois, elle ne doit pas êtreNULL si VolumeGuidName est NULL afin que FltGetVolumeGuidName puisse stocker la taille de mémoire tampon nécessaire pour le GUID de volume demandé.

Valeur de retour

FltGetVolumeGuidName retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, comme l’une des opérations suivantes :

Retourner le code	Description
STATUS_BUFFER_TOO_SMALL	La mémoire tampon pointée par VolumeGuidName est NULL ou trop petite pour contenir le GUID du volume. Si l’appelant fournit une valeur de NULL nonpour BufferSizeNeededed, FltGetVolumeGuidName stocke la taille de mémoire tampon requise dans BufferSizeNeeded. Il s’agit d’un code d’erreur, car le nom du GUID du volume n’a pas été récupéré.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName rencontré un échec d’allocation de pool. Il s’agit d’un code d’erreur.
STATUS_INVALID_DEVICE_REQUEST	Le paramètre volume est un handle pour un volume réseau. Il s’agit d’un code d’erreur.
STATUS_FLT_VOLUME_NOT_FOUND	Aucun volume correspondant n’a été trouvé. Il s’agit d’un code d’erreur.

Remarques

Le nom du GUID du volume retourné est exprimé au format suivant :

\ ?? \Volume{GUID}

où GUID est un identificateur global unique qui identifie le volume. Ce format, qui est le même que celui utilisé par le gestionnaire de montage, est décrit dans prise en charge des requêtes mount Manager dans un pilote de classe de stockage.

Si BufferSizeNeededed est inconnu, appelez FltGetVolumeGuidName deux fois :

Lors du premier appel, définissez VolumeGuidName sur NULL et BufferSizeNeeded non-NULL. FltGetVolumeGuidName stocke le nombre d’octets nécessaires pour le GUID du nom de volume dans BufferSizeNeeded et retourne STATUS_BUFFER_TOO_SMALL.
Lors du deuxième appel, définissez VolumeGuidName pour pointer vers une structure qui correspond à la taille de la valeur BufferSizeNeededed retournée dans le premier appel.

FltGetVolumeGuidName ne peut pas être appelé en toute sécurité à partir d’un rappel avant montage ou post-montage. Il ne peut pas être appelé en toute sécurité, car même lorsque le rappel post-montage est appelé, le traitement du montage n’a pas été effectué par le gestionnaire d’E/S et cela provoque un blocage avec le gestionnaire de montage dans certains cas.

Sur Windows Vista et versions ultérieures, un pilote minifilter peut appeler en toute sécurité FltGetVolumeGuidName à partir de sa routine InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK), car le rappel est appelé sur la première opération d’E/S pour un nouveau volume une fois que tout le traitement du montage est terminé.

Sur les systèmes d’exploitation Windows antérieurs à Windows Vista, FltGetVolumeGuidName ne peut pas être appelé en toute sécurité à partir d’une routine InstanceSetupCallback, car le gestionnaire de montage peut émettre une opération d’E/S de fichier lors de la conservation d’un verrou, ce qui peut entraîner un blocage.

Il est important de noter que le GUID du volume n’est pas identique à l’ID d’objet de volume. Le GUID de volume , ou nom de volume unique, est une valeur indépendante du système de fichiers ; il est affecté au volume de stockage sous-jacent par le gestionnaire de montage. L’ID d’objet de volume est affecté au volume du système de fichiers par le système de fichiers.

Pour obtenir l’ID d’objet de volume d’un volume, appelez ZwQueryVolumeInformationFile, en spécifiant FileFsObjectIdInformation pour le paramètre FsInformationClass .

FltGetVolumeGuidName équivaut approximativement à la fonction Win32 GetVolumeNameForVolumeMountPoint. (GetVolumeNameForVolumeMountPoint est documenté dans le Kit de développement logiciel (SDK) Microsoft Windows.)