GetLongPathNameA-Funktion (fileapi.h)

Artikel
11/20/2024

Wandelt den angegebenen Pfad in sein langes Format um.

Um diesen Vorgang als transacted-Vorgang auszuführen, verwenden Sie die GetLongPathNameTransacted--Funktion.

Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Namensdateien, Pfade und Namespaces.

Syntax

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

Parameter

[in] lpszShortPath

Der zu konvertierende Pfad.

[out] lpszLongPath

Ein Zeiger auf den Puffer, um den langen Pfad zu empfangen.

Sie können den gleichen Puffer verwenden, den Sie für den parameter lpszShortPath verwendet haben.

[in] cchBuffer

Die Größe des Puffers lpszLongPath in TCHARs.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge in TCHARsder Zeichenfolge, die in lpszLongPath-kopiert wurde, nicht einschließlich des endenden Nullzeichens.

Wenn der lpBuffer- Puffer zu klein ist, um den Pfad zu enthalten, ist der Rückgabewert die Größe in TCHARsdes Puffers, der zum Speichern des Pfads und des endenden Nullzeichens erforderlich ist.

Wenn die Funktion aus einem anderen Grund fehlschlägt, z. B. wenn die Datei nicht vorhanden ist, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

In vielen Dateisystemen enthält ein kurzer Dateiname ein Tildezeichen (~). Allerdings folgen nicht alle Dateisysteme dieser Konvention. Gehen Sie daher nicht davon aus, dass Sie den Aufruf GetLongPathName- überspringen können, wenn der Pfad kein Tildezeichen (~) enthält.

Wenn die Datei oder das Verzeichnis vorhanden ist, aber kein langer Pfad gefunden wird, GetLongPathName erfolgreich ist, nachdem die Zeichenfolge kopiert wurde, die vom parameter lpszShortPath in den Puffer kopiert wurde, auf den der parameter lpszLongPath verweist.

Wenn der Rückgabewert größer als der in cchBufferangegebene 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 im Abschnitt "Beispielcode" für GetFullPathName-.

Hinweis Obwohl der Rückgabewert in diesem Fall eine Länge ist, die das beendende NULL-Zeichen enthält, enthält der Rückgabewert für Erfolg nicht das endende Nullzeichen in der Anzahl.

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 zu haben. Daher kann GetLongPathName- fehlschlagen, wenn das übergeordnete Verzeichnis einer Pfadkomponente nicht abfragen kann, um den langen Namen für diese Komponente zu ermitteln. Diese Überprüfung kann für Verzeichniskomponenten mit Dateierweiterungen mit mehr als 3 Zeichen oder gesamter Länge übersprungen werden, die länger als 12 Zeichen sind. Weitere Informationen finden Sie im Abschnitt Short vs. Long Names Abschnitt Benennungsdateien, Pfade und Namespaces.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Beispiele

Ein Beispiel, das GetLongPathName-verwendet, finden Sie im Abschnitt "Beispielcode" für GetFullPathName.

Anmerkung

Der Fileapi.h-Header definiert GetLongPathName als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll