GetFinalPathNameByHandleA-Funktion (fileapi.h)
Ruft den endgültigen Pfad für die angegebene Datei ab.
Weitere Informationen zu Datei- und Pfadnamen finden Sie unter Benennen einer Datei.
Syntax
DWORD GetFinalPathNameByHandleA(
[in] HANDLE hFile,
[out] LPSTR lpszFilePath,
[in] DWORD cchFilePath,
[in] DWORD dwFlags
);
Parameter
[in] hFile
Ein Handle für eine Datei oder ein Verzeichnis.
[out] lpszFilePath
Ein Zeiger auf einen Puffer, der den Pfad von hFile empfängt.
[in] cchFilePath
Die Größe von lpszFilePath in TCHARs. Dieser Wert muss ein NULL-Terminierungszeichen enthalten.
[in] dwFlags
Der Typ des zurückzugebenden Ergebnisses. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Gibt den normalisierten Laufwerksnamen zurück. Dies ist die Standardoption. |
|
Gibt den geöffneten Dateinamen zurück (nicht normalisiert). |
Dieser Parameter kann auch einen der folgenden Werte enthalten.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge der von lpszFilePath empfangenen Zeichenfolge in TCHARs. Dieser Wert enthält nicht die Größe des abschließenden NULL-Zeichens.
Windows Server 2008 und Windows Vista: Für die ANSI-Version dieser Funktion GetFinalPathNameByHandleA enthält der Rückgabewert die Größe des abschließenden NULL-Zeichens.
Wenn die Funktion fehlschlägt, weil lpszFilePath zu klein ist, um die Zeichenfolge plus das abschließende NULL-Zeichen zu enthalten, ist der Rückgabewert die erforderliche Puffergröße in TCHARs. Dieser Wert enthält die Größe des abschließenden NULL-Zeichens.
Wenn die Funktion aus einem anderen Grund fehlschlägt, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
| Rückgabecode | Beschreibung |
|---|---|
|
Kann zurückgegeben werden, wenn Sie nach einem Laufwerkbuchstaben suchen und kein Laufwerksbuchstabe vorhanden ist. Beispielsweise wurde das Handle auf einem Laufwerk geöffnet, das derzeit nicht eingebunden ist, oder wenn Sie ein Volume erstellen und ihm keinen Laufwerkbuchstaben zuweisen. Wenn ein Volume keinen Laufwerkbuchstaben aufweist, können Sie den Volume-GUID-Pfad verwenden, um es zu identifizieren.
Dieser Rückgabewert kann auch zurückgegeben werden, wenn Sie nach einem Volume-GUID-Pfad für eine Netzwerkfreigabe suchen. Volume-GUID-Pfade werden nicht für Netzwerkfreigaben erstellt. |
|
Unzureichender Arbeitsspeicher, um den Vorgang abzuschließen. |
|
Für dwFlags wurden ungültige Flags angegeben. |
Hinweise
Das SMB-Protokoll (Server Message Block) unterstützt keine Abfragen für normalisierte Pfade. Wenn Sie diese Funktion aufrufen, indem Sie das Handle einer datei übergeben, die mit SMB geöffnet wurde, und mit dem flag FILE_NAME_NORMALIZED, teilt die Funktion den Pfad in ihre Komponenten auf und versucht, den normalisierten Namen jeder dieser Komponenten abzufragen. Wenn dem Benutzer die Zugriffsberechtigung für eine dieser Komponenten fehlt, schlägt der Funktionsaufruf mit ERROR_ACCESS_DENIED fehl.
Ein letzter Pfad ist der Pfad, der zurückgegeben wird, wenn ein Pfad vollständig aufgelöst wird. Für einen symbolischen Link namens "C:\tmp\mydir", der auf "D:\yourdir" verweist, lautet der endgültige Pfad beispielsweise "D:\yourdir".
Die von dieser Funktion zurückgegebene Zeichenfolge verwendet die Syntax "\\?\". Weitere Informationen finden Sie unter CreateFile.
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
Im folgenden Beispiel wird die Verwendung der GetFinalPathNameByHandle-Funktion veranschaulicht.
#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#define BUFSIZE MAX_PATH
void __cdecl _tmain(int argc, TCHAR *argv[])
{
TCHAR Path[BUFSIZE];
HANDLE hFile;
DWORD dwRet;
printf("\n");
if( argc != 2 )
{
printf("ERROR:\tIncorrect number of arguments\n\n");
printf("%s <file_name>\n", argv[0]);
return;
}
hFile = CreateFile(argv[1], // file to open
GENERIC_READ, // open for reading
FILE_SHARE_READ, // share for reading
NULL, // default security
OPEN_EXISTING, // existing file only
FILE_ATTRIBUTE_NORMAL, // normal file
NULL); // no attr. template
if( hFile == INVALID_HANDLE_VALUE)
{
printf("Could not open file (error %d\n)", GetLastError());
return;
}
dwRet = GetFinalPathNameByHandle( hFile, Path, BUFSIZE, VOLUME_NAME_NT );
if(dwRet < BUFSIZE)
{
_tprintf(TEXT("\nThe final path is: %s\n"), Path);
}
else printf("\nThe required buffer size is %d.\n", dwRet);
CloseHandle(hFile);
}
Hinweis
Der Fileapi.h-Header definiert GetFinalPathNameByHandle 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 Vista [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | fileapi.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für