GetVolumePathNameW, fonction (fileapi.h)

  • Article

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

Syntaxe

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Paramètres

[in] lpszFileName

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

Si vous spécifiez un répertoire ou un nom de fichier relatif sans qualificateur de volume, GetVolumePathName retourne 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 transmis, 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 fin du chemin spécifié.

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

Si un répertoire relatif ou un fichier est transmis 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 qu’un qualificateur de volume valide soit spécifié. Si un spécificateur de volume valide est donné 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 Nommer des fichiers, des chemins et des espaces de noms.

Vous pouvez spécifier des chemins d’accès locaux et distants. Si vous spécifiez un chemin d’accès 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 retourne 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.

Il existe certains cas spéciaux qui ne retournent pas de barre oblique inverse de fin. Celles-ci se produisent lorsque la longueur de la mémoire tampon de sortie est d’un caractère trop court. Par exemple, si lpszFileName est C: et que lpszVolumePathName a une longueur de 4 caractères, la valeur retournée est C:\; toutefois, si lpszVolumePathName a une longueur de 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 de la même taille que le 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 (et 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 à 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 sont ignorés. 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 X:\Dir_C spécification sur l’ordinateur distant retourne X:\.

Exemples

Pour l’ensemble d’exemples suivant, U : est mappé à l’ordinateur \\_YourComputer_\C$distant 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 d’accès non valide) G:\
\\.\I:\aaa\invalid (chemin d’accès non valide) \\.\I:\
\\_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 fileapi.h (inclure Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi