GetVolumePathNameA, fonction (winbase.h)

  • Article

Récupère le point de montage du volume où le chemin spécifié est monté.

Syntaxe

BOOL GetVolumePathNameA(
  [in]  LPCSTR lpszFileName,
  [out] LPSTR  lpszVolumePathName,
  [in]  DWORD  cchBufferLength
);

Paramètres

[in] lpszFileName

Pointeur vers la chaîne de chemin d’entrée. Les noms de fichiers et de répertoires absolus et relatifs, par exemple « ». sont acceptables dans ce chemin d’accès.

Si vous spécifiez un répertoire ou un nom de fichier relatif sans qualificateur de volume, GetVolumePathName renvoie la lettre de lecteur du volume de démarrage.

Si ce paramètre est une chaîne vide, « », la fonction échoue, mais la dernière erreur est définie sur ERROR_SUCCESS.

[out] lpszVolumePathName

Pointeur vers une chaîne qui reçoit le point de montage du volume pour le chemin d’entrée.

[in] cchBufferLength

Longueur de la mémoire tampon de sortie, en TCHAR.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Si un chemin d’accès spécifié est passé, GetVolumePathName retourne le chemin d’accès au point de montage du volume, ce qui signifie qu’il retourne la racine du volume où se trouve le point de terminaison du chemin spécifié.

Par exemple, supposons que vous ayez le volume D monté sur C :\Mnt\Ddrive et le volume E monté sur « C :\Mnt\Ddrive\Mnt\Edrive ». Supposons également que vous disposez d’un fichier avec le chemin « E :\Dir\Subdir\MyFile ». Si vous passez « C :\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile » à GetVolumePathName, le chemin « C :\Mnt\Ddrive\Mnt\Mnt\Edrive » est renvoyé.

Si un répertoire relatif ou un fichier est passé sans qualificateur de volume, la fonction retourne la lettre de lecteur du volume de démarrage. La lettre de lecteur du volume de démarrage est également retournée si un nom de fichier ou de répertoire non valide est spécifié sans qualificateur de volume valide. Si un spécificateur de volume valide est fourni et que le volume existe, mais qu’un nom de fichier ou de répertoire non valide est spécifié, la fonction réussit et ce nom de volume est retourné. Pour obtenir des exemples, consultez la section Exemples de cette rubrique.

Vous devez spécifier un chemin d’espace de noms Win32 valide. Si vous spécifiez un chemin d’espace de noms NT, par exemple, « \DosDevices\H : » ou « \Device\HardDiskVolume6 », la fonction retourne la lettre de lecteur du volume de démarrage, et non la lettre de lecteur de ce chemin d’espace de noms NT.

Pour plus d’informations sur les noms de chemin d’accès et les espaces de noms, consultez Naming Files, Paths, and Namespaces.

Vous pouvez spécifier des chemins d’accès locaux et distants. Si vous spécifiez un chemin local, GetVolumePathName retourne un chemin d’accès complet dont le préfixe est le préfixe le plus long qui représente un volume.

Si un partage réseau est spécifié, GetVolumePathName renvoie le chemin d’accès le plus court pour lequel GetDriveType retourne DRIVE_REMOTE, ce qui signifie que le chemin d’accès est validé en tant que lecteur distant existant, auquel l’utilisateur actuel peut accéder.

Certains cas spéciaux ne renvoient pas de barre oblique inverse de fin. Elles se produisent lorsque la longueur de la mémoire tampon de sortie est d’un caractère trop court. Par exemple, si lpszFileName a la valeur C : et que lpszVolumePathName contient 4 caractères, la valeur retournée est « C : » ; Toutefois, si lpszVolumePathName contient 3 caractères, la valeur retournée est « C : ». Un moyen plus sûr mais plus lent de définir la taille de la mémoire tampon de retour consiste à appeler la fonction GetFullPathName , puis à vérifier que la taille de la mémoire tampon est au moins identique à celle du chemin d’accès complet retourné par GetFullPathName . Si la mémoire tampon de sortie contient plusieurs caractères trop courts, la fonction échoue et retourne une erreur.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 No
Basculement transparent SMB 3.0 (TFO) No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) No
Système de fichiers du volume partagé de cluster (CsvFS) Oui
Système de fichiers résilient (ReFS) Oui
 

SMB ne prend pas en charge les fonctions de gestion des volumes.

Éléments de chemin de fin

Les éléments de chemin de fin non valides sont ignorés. Pour les chemins distants, le chemin d’accès entier (pas seulement les éléments de fin) est considéré comme non valide si l’une des conditions suivantes est remplie :
  • Le chemin d’accès n’est pas formé correctement.
  • Le chemin d’accès n’existe pas.
  • L’utilisateur actuel n’a pas accès au chemin d’accès.

Points de jonction et dossiers montés

Si le chemin spécifié traverse un point de jonction, GetVolumePathName retourne le volume auquel le point de jonction fait référence. Par exemple, si W:\Adir est un point de jonction qui pointe vers C:\Adir, getVolumePathName appelé sur W:\Adir\Afile retourne «C:\ ». Si le chemin spécifié traverse plusieurs points de jonction, la chaîne entière est suivie et GetVolumePathName retourne le volume auquel le dernier point de jonction de la chaîne fait référence.

Si un chemin d’accès distant vers un dossier monté ou un point de jonction est spécifié, le chemin d’accès est analysé en tant que chemin distant et le dossier monté ou le point de jonction est ignoré. Par exemple, si C:\Dir_C est lié à D:\Dir_D et C: est mappé à X: sur un ordinateur distant, l’appel de GetVolumePathName et la spécification X:\Dir_C sur l’ordinateur distant retourne X :</code>.

Exemples

Pour l’ensemble d’exemples suivant, U : est mappé à l’ordinateur distant \\YourComputer\C$, et Q est un lecteur local.

Chemin d'accès spécifié La fonction retourne
\\YourComputer\C$\Windows \\YourComputer\C$\
\\ ?\UNC\YourComputer\C$\Windows \\ ?\UNC\YourComputer\C$\
Q :\Windows Q:\
\\ ?\Q :\Windows \\?\Q:\
\\.\Q :\Windows \\.\Q:\
\\ ?\UNC\W :\Windows FALSE avec l’erreur 123, car un chemin d’accès distant spécifié n’était pas valide ; Le partage W$ n’existe pas ou aucun accès utilisateur n’est accordé.
C :\COM2 (qui existe) \\.\COM2\
C :\COM3 (inexistant) FALSE avec l’erreur 123, car un appareil COM inexistant a été spécifié.
 
Pour l’ensemble d’exemples suivant, les chemins d’accès contiennent des éléments de chemin de fin non valides.
Chemin d'accès spécifié La fonction retourne
G :\invalid (chemin non valide) G:\
\\.\I :\aaa\invalid (chemin non valide) \\.\Je:\
\\YourComputer\C$\invalid (élément chemin de fin non valide) \\YourComputer\C$\
 

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête winbase.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

DeleteVolumeMountPoint

GetFullPathName

GetVolumeNameForVolumeMountPoint

SetVolumeMountPoint

Fonctions de gestion des volumes

Points de montage de volume