Fungsi GetFinalPathNameByHandleA (fileapi.h)

2025-02-19

Mengambil jalur akhir untuk file yang ditentukan.

Untuk informasi selengkapnya tentang nama file dan jalur, lihat Penamaan File.

Sintaksis

DWORD GetFinalPathNameByHandleA(
  [in]  HANDLE hFile,
  [out] LPSTR  lpszFilePath,
  [in]  DWORD  cchFilePath,
  [in]  DWORD  dwFlags
);

Parameter

[in] hFile

Handel ke file atau direktori.

[out] lpszFilePath

Penunjuk ke buffer yang menerima jalur hFile.

[in] cchFilePath

UkuranlpszFilePath , dalam TCHAR. Nilai ini harus menyertakan karakter penghentian NULL.

[in] dwFlags

Jenis hasil yang akan dikembalikan. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Arti
FILE_NAME_NORMALIZED 0x0	Mengembalikan nama drive yang dinormalisasi. Ini adalah default.
FILE_NAME_OPENED 0x8	Mengembalikan nama file yang dibuka (tidak dinormalisasi).

Parameter ini juga dapat menyertakan salah satu nilai berikut.

Nilai	Arti
VOLUME_NAME_DOS 0x0	Mengembalikan jalur dengan huruf kandar. Ini adalah default.
VOLUME_NAME_GUID 0x1	Mengembalikan jalur dengan jalur GUID volume alih-alih nama drive.
VOLUME_NAME_NONE 0x4	Mengembalikan jalur tanpa informasi drive.
VOLUME_NAME_NT 0x2	Mengembalikan jalur dengan jalur perangkat volume.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah panjang string yang diterima oleh lpszFilePath, dalamTCHAR . Nilai ini tidak termasuk ukuran karakter null yang dihentikan.

Windows Server 2008 dan Windows Vista: Untuk versi ANSI fungsi ini, GetFinalPathNameByHandleA, nilai yang dikembalikan mencakup ukuran karakter null yang mengakhiri.

Jika fungsi gagal karena lpszFilePath terlalu kecil untuk menahan string ditambah karakter null yang mengakhiri, nilai yang dikembalikan adalah ukuran buffer yang diperlukan, dalam TCHARs. Nilai ini mencakup ukuran karakter null yang mengakhiri.

Jika fungsi gagal karena alasan lain, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Mengembalikan kode	Deskripsi
ERROR_PATH_NOT_FOUND	Dapat dikembalikan jika Anda mencari huruf kandar dan huruf kandar tidak ada. Misalnya, handel dibuka pada drive yang saat ini tidak dipasang, atau jika Anda membuat volume dan tidak menetapkan huruf kandar. Jika volume tidak memiliki huruf drive, Anda dapat menggunakan volume jalur GUID untuk mengidentifikasinya. Nilai pengembalian ini juga dapat dikembalikan jika Anda mencari volume jalur GUID pada berbagi jaringan. Jalur GUID volume tidak dibuat untuk berbagi jaringan.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup untuk menyelesaikan operasi.
ERROR_INVALID_PARAMETER	Bendera yang tidak valid ditentukan untuk dwFlags.

Komentar

Protokol Blok Pesan Server (SMB) tidak mendukung kueri untuk jalur yang dinormalisasi. Akibatnya, ketika Anda memanggil fungsi ini melewati handel file yang dibuka menggunakan SMB, dan dengan bendera FILE_NAME_NORMALIZED, fungsi membagi jalur menjadi komponennya dan mencoba meminta nama yang dinormalisasi dari setiap komponen tersebut secara bergantian. Jika pengguna tidak memiliki izin akses ke salah satu komponen tersebut, maka panggilan fungsi gagal dengan ERROR_ACCESS_DENIED.

Nota

Windows 10 versi 1709 dan yang lebih baru dan Windows Server versi 1709 dan yang lebih baru mendukung kelas informasi FileNormalizedNameInformation melalui SMB. Lihat spesifikasi [MS-SMB2] (/openspecs/windows_protocols/ms-smb2/a64e55aa-1152-48e4-8206-edd96444e7f7#Appendix_A_414) Lampiran A, Bagian 3.3.5.20.1 untuk informasi selengkapnya.

Jalur akhir adalah jalur yang dikembalikan ketika jalur diselesaikan sepenuhnya. Misalnya, untuk tautan simbolis bernama "C:\tmp\mydir" yang menunjuk ke "D:\yourdir", jalur akhir adalah "D:\yourdir".

String yang dikembalikan oleh fungsi ini menggunakan sintaks "\\?\". Untuk informasi selengkapnya, lihat CreateFile.

Di Windows 8 dan Windows Server 2012, fungsi ini didukung oleh teknologi berikut.

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Ya
Failover Transparan (TFO) SMB 3.0	Ya
SMB 3.0 dengan Scale-out File Shares (SO)	Ya
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

Contoh

Contoh berikut menunjukkan penggunaan fungsi GetFinalPathNameByHandle.

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

Nota

Header fileapi.h mendefinisikan GetFinalPathNameByHandle sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	fileapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

File Management Functions

Bagikan melalui