Fungsi GetFinalPathNameByHandleA (fileapi.h)

Mengambil jalur akhir untuk file yang ditentukan.

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

Sintaks

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

Parameter

[in] hFile

Handel ke file atau direktori.

[out] lpszFilePath

Pointer ke buffer yang menerima jalur hFile.

[in] cchFilePath

Ukuran lpszFilePath, dalam TCHARs. Nilai ini harus menyertakan karakter penghentian NULL .

[in] dwFlags

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

Nilai	Makna
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	Makna
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.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah panjang string yang diterima oleh lpszFilePath, dalam TCHARs. Nilai ini tidak termasuk ukuran karakter null yang mengakhiri.

Windows Server 2008 dan Windows Vista: Untuk versi ANSI dari 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, hubungi GetLastError.

Menampilkan 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 kandar, Anda dapat menggunakan jalur GUID volume untuk mengidentifikasinya. Nilai pengembalian ini juga dapat dikembalikan jika Anda mencari jalur GUID volume pada berbagi jaringan. Jalur GUID volume tidak dibuat untuk berbagi jaringan.
ERROR_NOT_ENOUGH_MEMORY	Tidak cukup memori untuk menyelesaikan operasi.
ERROR_INVALID_PARAMETER	Bendera yang tidak valid ditentukan untuk dwFlags.

Keterangan

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

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
SMB 3.0 Transparent Failover (TFO)	Ya
SMB 3.0 dengan Berbagi File Peluasan Skala (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);
}

Catatan

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

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Fungsi Manajemen File