GetVolumePathNameA, fonction (winbase.h)
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, siW:\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
GetVolumeNameForVolumeMountPoint