GetShortPathNameW-Funktion (fileapi.h)

Artikel
03/01/2024

Ruft die Kurzpfadform des angegebenen Pfads ab.

Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Syntax

DWORD GetShortPathNameW(
  [in]  LPCWSTR lpszLongPath,
  [out] LPWSTR  lpszShortPath,
  [in]  DWORD   cchBuffer
);

Parameter

[in] lpszLongPath

Die Pfadzeichenfolge.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

[out] lpszShortPath

Ein Zeiger auf einen Puffer, der die null-endende Kurzform des Pfads empfangen soll, den lpszLongPath angibt.

Das Übergeben von NULL für diesen Parameter und null für cchBuffer gibt immer die erforderliche Puffergröße für einen angegebenen lpszLongPath zurück.

[in] cchBuffer

Die Größe des Puffers, auf den lpszShortPath in TCHARs zeigt.

Legen Sie diesen Parameter auf null fest, wenn lpszShortPath auf NULL festgelegt ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, entspricht der Rückgabewert der Länge in TCHARs der Zeichenfolge, die in lpszShortPath kopiert wird, ohne das abschließende NULL-Zeichen.

Wenn der lpszShortPath-Puffer zu klein ist, um den Pfad zu enthalten, entspricht der Rückgabewert der Größe des Puffers in TCHARs, die zum Speichern des Pfads und des abschließenden NULL-Zeichens erforderlich ist.

Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Der Pfad, den der lpszLongPath-Parameter angibt, muss kein vollständiger oder langer Pfad sein. Die Kurzform kann länger als der angegebene Pfad sein.

Wenn der Rückgabewert größer als der im cchBuffer-Parameter angegebene Wert ist, können Sie die Funktion erneut mit einem Puffer aufrufen, der groß genug ist, um den Pfad zu speichern. Ein Beispiel für diesen Fall neben der Verwendung eines Puffers der Länge Null für die dynamische Zuordnung finden Sie im Abschnitt Beispielcode.

Hinweis Obwohl der Rückgabewert in diesem Fall eine Länge ist, die das abschließende NULL-Zeichen enthält, enthält der Rückgabewert bei Erfolg nicht das abschließende NULL-Zeichen in der Anzahl.

Wenn der angegebene Pfad bereits in seiner Kurzform vorliegt und keine Konvertierung erforderlich ist, kopiert die Funktion einfach den angegebenen Pfad in den durch den lpszShortPath-Parameter angegebenen Puffer.

Sie können den lpszShortPath-Parameter auf den gleichen Wert wie den lpszLongPath-Parameter festlegen. Anders ausgedrückt: Sie können den Ausgabepuffer für den kurzen Pfad zur Adresse der Eingabepfadzeichenfolge festlegen. Stellen Sie immer sicher, dass der cchBuffer-Parameter die Gesamtgröße dieses Puffers in TCHARs genau darstellt.

Sie können den langen Namen einer Datei aus dem Kurznamen abrufen, indem Sie die GetLongPathName-Funktion aufrufen. Alternativ können Sie FindFirstFile für jede Komponente des Pfads aufrufen, wenn GetLongPathName nicht verfügbar ist, um den entsprechenden langen Namen abzurufen.

Es ist möglich, Zugriff auf eine Datei oder ein Verzeichnis zu haben, aber keinen Zugriff auf einige der übergeordneten Verzeichnisse dieser Datei oder dieses Verzeichnisses. Daher schlägt GetShortPathName möglicherweise fehl, wenn es das übergeordnete Verzeichnis einer Pfadkomponente nicht abfragen kann, um den Kurznamen für diese Komponente zu ermitteln. Diese Überprüfung kann für Verzeichniskomponenten übersprungen werden, die bereits die Anforderungen eines Kurznamens erfüllen. Weitere Informationen finden Sie im Abschnitt Kurze und lange Namen unter Benennen von Dateien, Pfaden und Namespaces.

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)	Ja
SMB 3.0 Transparent Failover (TFO)	No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	No
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	No
Robustes Dateisystem (Resilient File System, ReFS)	Ja

SMB 3.0 unterstützt keine Kurznamen auf Freigaben mit Continuous Availability-Funktion.

Resilient File System (ReFS) unterstützt keine Kurznamen. Wenn Sie GetShortPathName für einen Pfad aufrufen, der keine Kurznamen auf dem Datenträger enthält, wird der Aufruf erfolgreich ausgeführt, aber stattdessen wird der Pfad mit langen Namen zurückgegeben. Dieses Ergebnis ist auch bei NTFS-Volumes möglich, da es keine Garantie dafür gibt, dass für einen bestimmten langen Namen ein Kurzname vorhanden ist.

Beispiele

Ein Beispiel, das GetShortPathName verwendet, finden Sie im Abschnitt Beispielcode für GetFullPathName.

Im folgenden C++-Beispiel wird die Verwendung eines dynamisch zugeordneten Ausgabepuffers veranschaulicht.

//...
    long     length = 0;
    TCHAR*   buffer = NULL;

// First obtain the size needed by passing NULL and 0.

    length = GetShortPathName(lpszPath, NULL, 0);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

// Dynamically allocate the correct size 
// (terminating null char was included in length)

    buffer = new TCHAR[length];

// Now simply call again using same long path.

    length = GetShortPathName(lpszPath, buffer, length);
    if (length == 0) ErrorExit(TEXT("GetShortPathName"));

    _tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
    
    delete [] buffer;
///...

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