GetShortPathNameA-Funktion (winbase.h)

Artikel
06/02/2023

Ruft die Kurzpfadform des angegebenen Pfads ab.

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

Syntax

DWORD GetShortPathNameA(
  [in]  LPCSTR lpszLongPath,
  [out] LPSTR  lpszShortPath,
  [in]  DWORD  cchBuffer
);

Parameter

[in] lpszLongPath

Die Pfadzeichenfolge.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um dieses Limit auf 32.767 breite Zeichen zu erweitern, müssen Sie dem Pfad "\\?\" voranstellen. 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 entfernen, ohne "\\?\" vorauszustellen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbegrenzung" unter Benennung von Dateien, Pfaden und Namespaces .

[out] lpszShortPath

Ein Zeiger auf einen Puffer, um die null-beendete Kurzform des Pfads zu empfangen, 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 verweist.

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

Rückgabewert

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

Wenn der puffer lpszShortPath zu klein ist, um den Pfad zu enthalten, ist der Rückgabewert die Größe des Puffers in TCHARs, die erforderlich ist, um den Pfad und das beendende NULL-Zeichen zu enthalten.

Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert 0. 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 finden Sie neben der Verwendung eines Puffers der Länge null für die dynamische Zuordnung im Abschnitt Beispielcode.

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

Wenn der angegebene Pfad bereits kurz ist und keine Konvertierung erforderlich ist, kopiert die Funktion einfach den angegebenen Pfad in den puffer, der durch den lpszShortPath-Parameter angegeben wird.

Sie können den lpszShortPath-Parameter auf denselben Wert wie den lpszLongPath-Parameter festlegen. Anders ausgedrückt: Sie können den Ausgabepuffer für den kurzen Pfad auf die 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 kurzen Namen abrufen, indem Sie die GetLongPathName-Funktion aufrufen. Wenn GetLongPathName nicht verfügbar ist, können Sie alternativ FindFirstFile für jede Komponente des Pfads aufrufen, um den entsprechenden langen Namen zu erhalten.

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 nicht in der Lage ist, das übergeordnete Verzeichnis einer Pfadkomponente abzufragen, um den kurzen Namen für diese Komponente zu bestimmen. Diese Überprüfung kann für Verzeichniskomponenten übersprungen werden, die bereits die Anforderungen eines kurzen Namens erfüllen. Weitere Informationen finden Sie im Abschnitt Kurze und lange Namen unter Benennungsdateien, Pfade 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 kontinuierlicher Verfügbarkeitsfunktion.

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

Beispiele

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

Das folgende C++-Beispiel zeigt die Verwendung eines dynamisch zugeordneten Ausgabepuffers.

//...
    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	winbase.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll