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 |
---|---|
|
Mengembalikan nama drive yang dinormalisasi. Ini adalah default. |
|
Mengembalikan nama file yang dibuka (tidak dinormalisasi). |
Parameter ini juga dapat menyertakan salah satu nilai berikut.
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 |
---|---|
|
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. |
|
Tidak cukup memori untuk menyelesaikan operasi. |
|
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
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk