GetFinalPathNameByHandleA-Funktion (fileapi.h)

Artikel
11/20/2024

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 zu einer Datei oder einem Verzeichnis.

[out] lpszFilePath

Ein Zeiger auf einen Puffer, der den Pfad hFile-empfängt.

[in] cchFilePath

Die Größe von lpszFilePathin TCHARs. Dieser Wert muss ein NULL-Zeichen Beendigungszeichen enthalten.

[in] dwFlags

Der Ergebnistyp, der zurückgegeben werden soll. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
FILE_NAME_NORMALIZED 0x0	Gibt den normalisierten Laufwerknamen zurück. Dies ist die Standardeinstellung.
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 Standardeinstellung.
VOLUME_NAME_GUID 0x1	Geben Sie 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	Geben Sie den Pfad mit dem Volumegerätepfad zurück.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Länge der Zeichenfolge, die von lpszFilePathin TCHARs empfangen wird. Dieser Wert enthält nicht die Größe des endenden NULL-Zeichens.

Windows Server 2008 und Windows Vista: Für die ANSI-Version dieser Funktion GetFinalPathNameByHandleAenthält der Rückgabewert die Größe des endenden Nullzeichens.

Wenn die Funktion fehlschlägt, da lpszFilePath- zu klein ist, um die Zeichenfolge plus das endende NULL-Zeichen zu halten, ist der Rückgabewert die erforderliche Puffergröße in TCHARs. Dieser Wert enthält die Größe des endenden NULL-Zeichens.

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

Rückgabecode	Beschreibung
ERROR_PATH_NOT_FOUND	Kann zurückgegeben werden, wenn Sie nach einem Laufwerkbuchstaben suchen und kein Laufwerk vorhanden ist. Beispielsweise wurde das Handle auf einem Laufwerk geöffnet, das derzeit nicht bereitgestellt wird, oder wenn Sie ein Volume erstellen und ihm keinen Laufwerkbuchstaben zuweisen. Wenn ein Volume keinen Laufwerkbuchstaben aufweist, können Sie das Volume GUID Pfad verwenden, um es zu identifizieren. Dieser Rückgabewert kann auch zurückgegeben werden, wenn Sie nach einem Volume GUID Pfad in einer Netzwerkfreigabe suchen. Volume GUID Pfade werden nicht für Netzwerkfreigaben erstellt.
ERROR_NOT_ENOUGH_MEMORY	Nicht genügend Arbeitsspeicher zum Abschließen des Vorgangs.
ERROR_INVALID_PARAMETER	Für dwFlags-wurden ungültige Flags angegeben.

Bemerkungen

Das Server Message Block (SMB)-Protokoll unterstützt keine Abfragen für normalisierte Pfade. Wenn Sie diese Funktion also aufrufen, indem Sie das Handle einer datei aufrufen, die mit SMB geöffnet wurde, und mit dem FILE_NAME_NORMALIZED Flag teilt die Funktion den Pfad in seine Komponenten auf und versucht wiederum, den normalisierten Namen jeder dieser Komponenten abzufragen. Wenn der Benutzer keine Zugriffsberechtigung für eine dieser Komponenten besitzt, schlägt der Funktionsaufruf mit ERROR_ACCESS_DENIED fehl.

Ein endgültiger Pfad ist der Pfad, der zurückgegeben wird, wenn ein Pfad vollständig aufgelöst wird. Bei einer symbolischen Verknüpfung mit dem Namen "C:\tmp\mydir", die auf "D:\yourdir" verweist, lautet der letzte Pfad beispielsweise "D:\yourdir".

Die von dieser Funktion zurückgegebene Zeichenfolge verwendet die Syntax "\\?\". Weitere Informationen finden Sie unter CreateFile-.

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

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);
}

Anmerkung

Der Fileapi.h-Header definiert GetFinalPathNameByHandle 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 Vista [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll

Siehe auch

Dateiverwaltungsfunktionen

Freigeben über