GetVolumePathNameW-Funktion (fileapi.h)

  • Artikel

Ruft den Volumebereitstellungspunkt ab, an dem der angegebene Pfad eingebunden wird.

Syntax

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  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 akzeptabel.

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 wird 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, was bedeutet, dass der Stamm des Volumes zurückgegeben wird, auf dem sich der Endpunkt des angegebenen Pfads befindet.

Angenommen, Sie haben Volume D am C:\Mnt\Ddrive und Volume E an C:\Mnt\Ddrive\Mnt\Edriveeingebunden. Gehen Sie auch davon aus, dass Sie über eine Datei mit dem Pfad E:\Dir\Subdir\MyFileverfügen. Wenn Sie an GetVolumePathName übergebenC:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile, 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 Volumebezeichner angegeben wird und das Volume vorhanden ist, aber ein ungültiger Datei- oder Verzeichnisname angegeben ist, wird die Funktion erfolgreich ausgeführt, und der Volumename wird zurückgegeben. Beispiele finden Sie im Abschnitt Beispiele dieses Themas.

Sie müssen einen gültigen Win32-Namespacepfad angeben. Wenn Sie z. B. einen NT-Namespacepfad angeben, \DosDevices\H: gibt \Device\HardDiskVolume6die 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 nachfolgenden umgekehrten Schrägstrich zurückgeben. Diese treten auf, wenn die Ausgabepufferlänge um ein Zeichen zu kurz ist. Wenn beispielsweise lpszFileName und C:lpszVolumePathName 4 Zeichen lang ist, lautet C:\der zurückgegebene Wert. Wenn lpszVolumePathName jedoch 3 Zeichen lang ist, ist C:der zurückgegebene Wert . 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 gilt der gesamte Pfad (nicht nur nachfolgende Elemente) als ungültig, wenn eine der folgenden Bedingungen zutrifft:

  • Der Pfad ist nicht ordnungsgemäß gebildet.
  • Der Pfad ist nicht vorhanden.
  • Der aktuelle Benutzer hat keinen Zugriff auf den Pfad.

Verbindungspunkte und eingebundene Ordner

Wenn der angegebene Pfad einen Knotenpunkt durchquert, gibt GetVolumePathName das Volume zurück, auf das der Knotenpunkt verweist. Wenn W:\Adir es sich beispielsweise um einen Knotenpunkt handelt, der auf C:\Adirverweist, gibt GetVolumePathName aufgerufen für W:\Adir\Afile zurück C:\. Wenn der angegebene Pfad mehrere Knotenpunkte durchläuft, wird die gesamte Kette befolgt, 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 eingebundene Ordner oder Knotenpunkt wird ignoriert. Wenn C:\Dir_C beispielsweise mit einem Remotecomputer verknüpft D:\Dir_D ist und C: zugeordnet X: ist, wird X:\getVolumePathName aufgerufen und auf dem Remotecomputer angegebenX:\Dir_C.

Beispiele

Für die folgenden Beispiele ist U: dem Remotecomputer \\_YourComputer_\C$zugeordnet, und Q ist ein lokales Laufwerk.

Angegebener Pfad Funktion gibt zurück
\\_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 mit Fehler 123, da ein angegebener Remotepfad ungültig war; W$-Freigabe ist nicht vorhanden oder kein Benutzerzugriff gewährt.
C:\COM2 (vorhanden) \\.\COM2\
C:\COM3 (nicht vorhanden) FALSE mit Fehler 123, da ein nicht vorhandenes COM-Gerät angegeben wurde.

In den folgenden Beispielen enthalten die Pfade ungültige nachgestellte Pfadelemente.

Angegebener Pfad Funktion gibt zurück
G:\invalid (ungültiger Pfad) G:\
\\.\I:\aaa\invalid (ungültiger Pfad) \\.\I:\
\\_YourComputer_\C$\invalid (ungültiges nachgestelltes Pfadelement) \\_YourComputer_\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 fileapi.h (Einschließen von Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch