GetFinalPathNameByHandleA-Funktion (fileapi.h)

Artikel
08/23/2023

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
FILE_NAME_NORMALIZED 0x0	Gibt den normalisierten Laufwerksnamen zurück. Dies ist die Standardoption.
FILE_NAME_OPENED 0x8	Gibt den geöffneten Dateinamen zurück (nicht normalisiert).

Dieser Parameter kann auch einen der folgenden Werte enthalten.

Wert	Bedeutung
VOLUME_NAME_DOS 0x0	Gibt den Pfad mit dem Laufwerkbuchstaben zurück. Dies ist die Standardoption.
VOLUME_NAME_GUID 0x1	Gibt den Pfad mit einem Volume-GUID-Pfad anstelle des Laufwerknamens zurück.
VOLUME_NAME_NONE 0x4	Gibt den Pfad ohne Laufwerksinformationen zurück.
VOLUME_NAME_NT 0x2	Gibt den Pfad mit dem Volumegerätepfad zurück.

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
ERROR_PATH_NOT_FOUND	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.
ERROR_NOT_ENOUGH_MEMORY	Unzureichender Arbeitsspeicher, um den Vorgang abzuschließen.
ERROR_INVALID_PARAMETER	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

Dateiverwaltungsfunktionen

Freigeben über