GetFullPathNameA-Funktion (fileapi.h)
Ruft den vollständigen Pfad und Dateinamen der angegebenen Datei ab.
Verwenden Sie die GetFullPathNameTransacted--Funktion, um diesen Vorgang als transacted-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.
Dieser Parameter kann ein kurzer (das 8.3-Formular) oder ein langer Dateiname sein. Diese Zeichenfolge kann auch ein Freigabe- oder Volumename sein.
[in] nBufferLength
Die Größe des Puffers, um die mit Null beendete Zeichenfolge für das Laufwerk und den Pfad zu empfangen, in TCHARs.
[out] lpBuffer
Ein Zeiger auf einen Puffer, der die mit Null beendete Zeichenfolge für das Laufwerk und den Pfad empfängt.
[out] lpFilePart
Ein Zeiger auf einen Puffer, der die Adresse (innerhalb lpBuffer) der endgültigen Dateinamenkomponente im Pfad empfängt.
Dieser Parameter kann NULL-sein.
Wenn lpBuffer- auf ein Verzeichnis und keine Datei verweist, erhält lpFilePart Null.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge in TCHARsder Zeichenfolge, die in lpBuffer-kopiert wurde, nicht einschließlich des endenden NULL-Zeichens.
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, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
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 dateinamens berechnet.
Diese Funktion überprüft nicht, ob der resultierende Pfad und der Dateiname gültig sind oder ob eine vorhandene Datei auf dem zugeordneten Volume angezeigt wird.
Beachten Sie, dass der lpFilePart- Parameter keinen Zeichenfolgenpufferspeicher erfordert, sondern nur für eine einzelne Adresse ausreichend. Dies liegt daran, dass sie einfach eine Adresse innerhalb des Puffers zurückgibt, die bereits für lpBuffer-vorhanden ist.
Freigabe- und Volumenamen sind gültige Eingaben für lpFileName. Die folgende Liste identitätiert beispielsweise den zurückgegebenen Pfad und dateinamen, wenn "test-2" ein Remotecomputer und "U" ist: ein zugeordnetes Netzlaufwerk, 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 nBufferLengthangegebenen 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 zusätzlich zur Verwendung des 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 Verzeichnisstatus, der vom 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 Multithread-Anwendungen und freigegebener Bibliothekscode die Verwendung relativer Pfade vermeiden. Wenn ein relativer Pfad empfangen wird, sollte er genau einmal verwendet werden, entweder durch direktes Übergeben 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.
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
Das folgende C++-Beispiel zeigt eine einfache Verwendung von GetFullPathName-, GetLongPathName-und GetShortPathName-. Ein weiteres Beispiel für die dynamische 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;
}
}
Anmerkung
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 |
|---|---|
| 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 |