Fonction FltGetVolumeGuidName (fltkernel.h)

Article
08/07/2023

FltGetVolumeGuidName obtient le nom du volume d’un volume donné, au format GUID (Volume 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. Il doit s’agir d’un volume de système de fichiers local. Ce paramètre est obligatoire et ne peut pas avoir la valeur NULL.

[in/out, optional] VolumeGuidName

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

Si VolumeGuidName a la valeur NULL et que BufferSizeNeeded n’a pas la valeur 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. Consultez la section Notes.

[out, optional] BufferSizeNeeded

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

Valeur retournée

FltGetVolumeGuidName retourne STATUS_SUCCESS ou une valeur NTSTATUS appropriée, par exemple :

Code de retour	Description
STATUS_BUFFER_TOO_SMALL	La mémoire tampon pointée par VolumeGuidName est NULL ou trop petite pour contenir le GUID de volume. Si l’appelant fournit une valeur non NULL pour 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 de volume n’a pas été récupéré.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName a 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 GUID de 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 demandes du gestionnaire de montage dans un pilote de classe de stockage.

Si BufferSizeNeeded est inconnu, appelez FltGetVolumeGuidName deux fois :

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

FltGetVolumeGuidName ne peut pas être appelé en toute sécurité à partir d’un rappel pré-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, ce qui provoque un blocage avec le gestionnaire de montage dans certains cas.

Sur Windows Vista et versions ultérieures, un pilote de minifiltre peut appeler en toute sécurité FltGetVolumeGuidName à partir de sa routine InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK), car le rappel est appelé lors de la première opération d’E/S pour un nouveau volume une fois que tout le traitement de 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 en tenant un verrou, ce qui peut provoquer un blocage.

Il est important de noter que le GUID de 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 est à peu près équivalent à la fonction Win32 GetVolumeNameForVolumeMountPoint . (GetVolumeNameForVolumeMountPoint est documenté dans le Microsoft Windows SDK.)