GetVolumePathNameA-Funktion (winbase.h)
Ruft den Volumebereitstellungspunkt ab, an dem der angegebene Pfad eingebunden wird.
Syntax
BOOL GetVolumePathNameA(
[in] LPCSTR lpszFileName,
[out] LPSTR lpszVolumePathName,
[in] DWORD cchBufferLength
);
Parameter
[in] lpszFileName
Ein Zeiger auf die Eingabepfadzeichenfolge. Sowohl absolute als auch relative Datei- und Verzeichnisnamen, z. B. "..", sind in diesem Pfad zulässig.
Wenn Sie einen relativen Verzeichnis- oder Dateinamen ohne Volumequalifizierer angeben, gibt GetVolumePathName den Laufwerkbuchstaben des Startvolumes zurück.
Wenn es sich bei diesem Parameter um eine leere Zeichenfolge "" handelt, schlägt die Funktion fehl, aber der letzte Fehler ist auf ERROR_SUCCESS festgelegt.
[out] lpszVolumePathName
Ein Zeiger auf eine Zeichenfolge, die den Volumebereitstellungspunkt für den Eingabepfad empfängt.
[in] cchBufferLength
Die Länge des Ausgabepuffers in TCHARs.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Hinweise
Wenn ein angegebener Pfad übergeben wird, gibt GetVolumePathName den Pfad zum Volumebereitstellungspunkt zurück. Dies bedeutet, dass der Stamm des Volumes zurückgegeben wird, auf dem sich der Endpunkt des angegebenen Pfads befindet.
Angenommen, Sie haben Volume D unter C:\Mnt\Ddrive und Volume E unter "C:\Mnt\Ddrive\Mnt\Edrive" eingebunden. Angenommen, Sie verfügen über eine Datei mit dem Pfad "E:\Dir\Subdir\MyFile". Wenn Sie "C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile" an GetVolumePathName übergeben, wird der Pfad "C:\Mnt\Ddrive\Mnt\Edrive" zurückgegeben.
Wenn entweder ein relatives Verzeichnis oder eine Datei ohne Volumequalifizierer übergeben wird, gibt die Funktion den Laufwerkbuchstaben des Startvolumes zurück. Der Laufwerkbuchstabe des Startvolumes wird auch zurückgegeben, wenn ein ungültiger Datei- oder Verzeichnisname ohne gültigen Volumequalifizierer angegeben wird. Wenn ein gültiger Volumespezifizierer angegeben wird und das Volume vorhanden ist, aber ein ungültiger Datei- oder Verzeichnisname angegeben ist, wird die Funktion erfolgreich ausgeführt, und dieser Volumename wird zurückgegeben. Beispiele finden Sie im Abschnitt Beispiele dieses Themas.
Sie müssen einen gültigen Win32-Namespacepfad angeben. Wenn Sie einen NT-Namespacepfad angeben, z. B. "\DosDevices\H:" oder "\Device\HardDiskVolume6", gibt die Funktion den Laufwerkbuchstaben des Startvolumes und nicht den Laufwerkbuchstaben dieses NT-Namespacepfads zurück.
Weitere Informationen zu Pfadnamen und Namespaces finden Sie unter Benennen von Dateien, Pfaden und Namespaces.
Sie können sowohl lokale als auch Remotepfade angeben. Wenn Sie einen lokalen Pfad angeben, gibt GetVolumePathName einen vollständigen Pfad zurück, dessen Präfix das längste Präfix ist, das ein Volume darstellt.
Wenn eine Netzwerkfreigabe angegeben wird, gibt GetVolumePathName den kürzesten Pfad zurück, für den GetDriveTypeDRIVE_REMOTE zurückgibt. Dies bedeutet, dass der Pfad als vorhandenes Remotelaufwerk überprüft wird, auf das der aktuelle Benutzer zugreifen kann.
Es gibt bestimmte Sonderfälle, die keinen nachgestellten umgekehrten Schrägstrich zurückgeben. Diese treten auf, wenn die Länge des Ausgabepuffers um ein Zeichen zu kurz ist. Wenn beispielsweise lpszFileName C: und lpszVolumePathName 4 Zeichen lang ist, lautet der zurückgegebene Wert "C:"; Wenn lpszVolumePathName jedoch 3 Zeichen lang ist, lautet der zurückgegebene Wert "C:". Eine sicherere, aber langsamere Möglichkeit zum Festlegen der Größe des Rückgabepuffers besteht darin, die GetFullPathName-Funktion aufzurufen und dann sicherzustellen, dass die Puffergröße mindestens die gleiche Größe wie der vollständige Pfad aufweist, den GetFullPathName zurückgibt. Wenn der Ausgabepuffer mehr als ein Zeichen zu kurz ist, schlägt die Funktion fehl und gibt einen Fehler zurück.
Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | No |
| SMB 3.0 Transparent Failover (TFO) | No |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | No |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
SMB unterstützt keine Volumeverwaltungsfunktionen.
Nachgestellte Pfadelemente
Nachgestellte Pfadelemente, die ungültig sind, werden ignoriert. Bei Remotepfaden wird der gesamte Pfad (nicht nur nachfolgende Elemente) als ungültig betrachtet, wenn eine der folgenden Bedingungen zutrifft:- Der Pfad ist nicht richtig formatiert.
- Der Pfad ist nicht vorhanden.
- Der aktuelle Benutzer hat keinen Zugriff auf den Pfad.
Verbindungspunkte und eingebundene Ordner
Wenn der angegebene Pfad einen Knotenpunkt durchläuft, gibt GetVolumePathName das Volume zurück, auf das der Knotenpunkt verweist. Wenn z. B. ein Knotenpunkt ist,W:\Adir der auf C:\Adirzeigt, gibt GetVolumePathName aufgerufen bei W:\Adir\Afile "C:\" zurück.
Wenn der angegebene Pfad mehrere Knotenpunkte durchläuft, wird der gesamten Kette gefolgt, und GetVolumePathName gibt das Volume zurück, auf das sich der letzte Knotenpunkt in der Kette bezieht.
Wenn ein Remotepfad zu einem eingebundenen Ordner oder Knotenpunkt angegeben wird, wird der Pfad als Remotepfad analysiert, und der bereitgestellte Ordner oder Verbindungspunkt wird ignoriert. Wenn z. BC:\Dir_C. mit verknüpft D:\Dir_D ist und C: auf einem Remotecomputer zugeordnet X: ist, gibt der Aufruf von GetVolumePathName und die Angabe X:\Dir_C auf dem Remotecomputer X:</code> zurück.
Beispiele
Für die folgenden Beispiele wird U: dem Remotecomputer \\IhrComputer\C$ zugeordnet, und Q ist ein lokales Laufwerk.
Angegebener Pfad
Die Funktion gibt zurück
\\IhrComputer\C$\Windows
\\IhrComputer\C$\
\\?\UNC\IhrComputer\C$\Windows
\\?\UNC\IhrComputer\C$\
Q:\Windows
Q:\
\\?\Q:\Windows
\\?\Q:\
\\.\Q:\Windows
\\.\Q:\
\\?\UNC\W:\Windows
FALSE mit Fehler 123, weil ein angegebener Remotepfad ungültig war; Die W$-Freigabe ist nicht vorhanden, oder es wird kein Benutzerzugriff gewährt.
C:\COM2 (vorhanden)
\\.\COM2\
C:\COM3 (nicht vorhanden)
FALSE mit Fehler 123, weil ein nicht vorhandenes COM-Gerät angegeben wurde.
Für die folgenden Beispiele enthalten die Pfade ungültige nachgestellte Pfadelemente.
Angegebener Pfad
Die Funktion gibt zurück
G:\invalid (ungültiger Pfad)
G:\
\\.\I:\aaa\invalid (ungültiger Pfad)
\\.\Ich:\
\\IhrComputer\C$\invalid (ungültiges nachgestelltes Pfadelement)
\\IhrComputer\C$\
Anforderungen
Anforderung
Wert
Unterstützte Mindestversion (Client)
Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows Server 2003 [nur Desktop-Apps]
Zielplattform
Windows
Kopfzeile
winbase.h (einschließlich Windows.h)
Bibliothek
Kernel32.lib
DLL
Kernel32.dll
Siehe auch