GetFullPathNameA-Funktion (fileapi.h)
Ruft den vollständigen Pfad und Dateinamen der angegebenen Datei ab.
Verwenden Sie die GetFullPathNameTransacted-Funktion , um diesen Vorgang als transaktionierten Vorgang auszuführen.
Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Dateinamen, Pfade und Namespaces.
Syntax
DWORD GetFullPathNameA(
[in] LPCSTR lpFileName,
[in] DWORD nBufferLength,
[out] LPSTR lpBuffer,
[out] LPSTR *lpFilePart
);
Parameter
[in] lpFileName
Der Name der Datei.
Bei diesem Parameter kann es sich um einen kurzen (8.3)-Dateinamen oder einen langen Dateinamen handeln. Diese Zeichenfolge kann auch ein Freigabe- oder Volumename sein.
[in] nBufferLength
Die Größe des Puffers, der die NULL-endende Zeichenfolge für das Laufwerk und den Pfad in TCHARs empfangen soll.
[out] lpBuffer
Ein Zeiger auf einen Puffer, der die NULL-endende Zeichenfolge für das Laufwerk und den Pfad empfängt.
[out] lpFilePart
Ein Zeiger auf einen Puffer, der die Adresse (innerhalb von lpBuffer) der endgültigen Dateinamenkomponente im Pfad empfängt.
Dieser Parameter kann NULL sein.
Wenn lpBuffer auf ein Verzeichnis und nicht auf eine Datei verweist, erhält lpFilePart null.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge der in lpBuffer kopierten Zeichenfolge in TCHARs, ohne das abschließende NULL-Zeichen.
Wenn der lpBuffer-Puffer zu klein ist, um den Pfad zu enthalten, entspricht der Rückgabewert in TCHARs der Größe des Puffers, der 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
GetFullPathName führt den Namen des aktuellen Laufwerks und Verzeichnisses mit einem angegebenen Dateinamen zusammen, um den vollständigen Pfad und Dateinamen einer angegebenen Datei zu ermitteln. Außerdem wird die Adresse des Dateinamenteils des vollständigen Pfads und des Dateinamens berechnet.
Diese Funktion überprüft nicht, ob der resultierende Pfad und Dateiname gültig sind oder ob eine vorhandene Datei auf dem zugeordneten Volume angezeigt wird.
Beachten Sie, dass der lpFilePart-Parameter keinen Zeichenfolgenpufferspeicherplatz benötigt, sondern nur ausreichend für eine einzelne Adresse. Dies liegt daran, dass einfach eine Adresse innerhalb des Puffers zurückgegeben wird, die bereits für lpBuffer vorhanden ist.
Freigabe- und Volumenamen sind gültige Eingaben für lpFileName. In der folgenden Liste werden beispielsweise der zurückgegebene Pfad und die Dateinamen angegeben, wenn test-2 ein Remotecomputer ist, und U: ein im Netzwerk zugeordnetes Laufwerk, dessen aktuelles Verzeichnis der Stamm des Volumes ist:
- Wenn Sie "\\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\test-2\q$\lh"
- Wenn Sie "\\?\UNC\test-2\q$\lh" angeben, lautet der zurückgegebene Pfad "\\?\UNC\test-2\q$\lh"
- Wenn Sie "U:" angeben, ist der zurückgegebene Pfad das aktuelle Verzeichnis auf dem Laufwerk "U:\"
Wenn der Rückgabewert größer oder gleich dem in nBufferLength angegebenen 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.
Relative Pfade, die an die GetFullPathName-Funktion übergeben werden, werden relativ zum aktuellen Verzeichnis des Prozesses interpretiert. Der aktuelle Verzeichniszustand, der von der SetCurrentDirectory-Funktion geschrieben wird, ist global für den Prozess und kann jederzeit von jedem Thread geändert werden. Anwendungen sollten beachten, dass aufeinander folgende Aufrufe der GetFullPathName-Funktion mit einem relativen Pfad zu unterschiedlichen Ergebnissen führen können, wenn sich das aktuelle Verzeichnis zwischen den beiden Aufrufen ändert.
Um Probleme zu vermeiden, die durch inkonsistente Ergebnisse verursacht werden, sollten Multithreadanwendungen und freigegebener Bibliothekscode die Verwendung relativer Pfade vermeiden. Wenn ein relativer Pfad empfangen wird, sollte er genau einmal verwendet werden, entweder durch direkte Übergabe des relativen Pfads an eine Funktion wie CreateFile oder durch Konvertieren in einen absoluten Pfad und Verwenden des absoluten Pfads von diesem Punkt nach vorne.
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) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Beispiele
Das folgende C++-Beispiel zeigt eine einfache Verwendung von GetFullPathName, GetLongPathName und GetShortPathName. Ein weiteres Beispiel für die verwendung der dynamischen Zuordnung finden Sie unter GetShortPathName.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE 4096
#define LONG_DIR_NAME TEXT("c:\\longdirectoryname")
void _tmain(int argc, TCHAR *argv[])
{
DWORD retval=0;
BOOL success;
TCHAR buffer[BUFSIZE]=TEXT("");
TCHAR buf[BUFSIZE]=TEXT("");
TCHAR** lppPart={NULL};
if( argc != 2 )
{
_tprintf(TEXT("Usage: %s [file]\n"), argv[0]);
return;
}
// Retrieve the full path name for a file.
// The file does not need to exist.
retval = GetFullPathName(argv[1],
BUFSIZE,
buffer,
lppPart);
if (retval == 0)
{
// Handle an error condition.
printf ("GetFullPathName failed (%d)\n", GetLastError());
return;
}
else
{
_tprintf(TEXT("The full path name is: %s\n"), buffer);
if (lppPart != NULL && *lppPart != 0)
{
_tprintf(TEXT("The final component in the path name is: %s\n"), *lppPart);
}
}
// Create a long directory name for use with the next two examples.
success = CreateDirectory(LONG_DIR_NAME,
NULL);
if (!success)
{
// Handle an error condition.
printf ("CreateDirectory failed (%d)\n", GetLastError());
return;
}
// Retrieve the short path name.
retval = GetShortPathName(LONG_DIR_NAME,
buf,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetShortPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The short name for %s is %s\n"),
LONG_DIR_NAME, buf);
// Retrieve the long path name.
retval = GetLongPathName(buf,
buffer,
BUFSIZE);
if (retval == 0)
{
// Handle an error condition.
printf ("GetLongPathName failed (%d)\n", GetLastError());
return;
}
else _tprintf(TEXT("The long name for %s is %s\n"), buf, buffer);
// Clean up the directory.
success = RemoveDirectory(LONG_DIR_NAME);
if (!success)
{
// Handle an error condition.
printf ("RemoveDirectory failed (%d)\n", GetLastError());
return;
}
}
Hinweis
Der Fileapi.h-Header definiert GetFullPathName als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |