Fungsi GetVolumePathNameW (fileapi.h)

Artikel
08/23/2023

Mengambil titik pemasangan volume tempat jalur yang ditentukan dipasang.

Sintaks

BOOL GetVolumePathNameW(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Parameter

[in] lpszFileName

Penunjuk ke string jalur input. Nama file dan direktori absolut dan relatif, misalnya, "..", dapat diterima di jalur ini.

Jika Anda menentukan direktori relatif atau nama file tanpa kualifikasi volume, GetVolumePathName mengembalikan huruf kandar volume boot.

Jika parameter ini adalah string kosong, "", fungsi gagal tetapi kesalahan terakhir diatur ke ERROR_SUCCESS.

[out] lpszVolumePathName

Penunjuk ke string yang menerima titik pemasangan volume untuk jalur input.

[in] cchBufferLength

Panjang buffer output, dalam TCHAR.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Jika jalur yang ditentukan diteruskan, GetVolumePathName mengembalikan jalur ke titik pemasangan volume, yang berarti bahwa jalur tersebut mengembalikan akar volume tempat titik akhir jalur yang ditentukan berada.

Misalnya, asumsikan bahwa Anda memiliki volume D yang dipasang pada C:\Mnt\Ddrive dan volume E yang dipasang di C:\Mnt\Ddrive\Mnt\Edrive. Asumsikan juga bahwa Anda memiliki file dengan jalur E:\Dir\Subdir\MyFile. Jika Anda meneruskan C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile ke GetVolumePathName, itu mengembalikan jalur C:\Mnt\Ddrive\Mnt\Edrive\.

Jika direktori relatif atau file diteruskan tanpa kualifikasi volume, fungsi mengembalikan huruf drive volume boot. Huruf kandar volume boot juga dikembalikan jika file atau nama direktori yang tidak valid ditentukan tanpa kualifikasi volume yang valid. Jika penentu volume yang valid diberikan, dan volume ada, tetapi file atau nama direktori yang tidak valid ditentukan, fungsi akan berhasil dan nama volume tersebut akan dikembalikan. Misalnya, lihat bagian Contoh dari topik ini.

Anda harus menentukan jalur namespace Win32 yang valid. Jika Anda menentukan jalur namespace layanan NT, misalnya, \DosDevices\H: atau \Device\HardDiskVolume6, fungsi mengembalikan huruf drive volume boot, bukan huruf drive dari jalur namespace NT tersebut.

Untuk informasi selengkapnya tentang nama jalur dan namespace layanan, lihat Menamai File, Jalur, dan Namespace.

Anda dapat menentukan jalur lokal dan jarak jauh. Jika Anda menentukan jalur lokal, GetVolumePathName mengembalikan jalur lengkap yang awalannya adalah awalan terpanjang yang mewakili volume.

Jika berbagi jaringan ditentukan, GetVolumePathName mengembalikan jalur terpendek di mana GetDriveType mengembalikan DRIVE_REMOTE, yang berarti bahwa jalur divalidasi sebagai drive jarak jauh yang ada, yang dapat diakses pengguna saat ini.

Ada kasus khusus tertentu yang tidak mengembalikan garis miring terbelakang. Ini terjadi ketika panjang buffer output adalah satu karakter terlalu pendek. Misalnya, jika lpszFileName adalah C: dan lpszVolumePathName panjangnya 4 karakter, nilai yang dikembalikan adalah C:\; namun, jika lpszVolumePathName panjangnya 3 karakter, nilai yang dikembalikan adalah C:. Cara yang lebih aman tetapi lebih lambat untuk mengatur ukuran buffer pengembalian adalah dengan memanggil fungsi GetFullPathName , lalu memastikan bahwa ukuran buffer setidaknya berukuran sama dengan jalur lengkap yang dikembalikan GetFullPathName . Jika buffer output lebih dari satu karakter terlalu pendek, fungsi akan gagal dan mengembalikan kesalahan.

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

Teknologi	Didukung
Protokol Server Message Block (SMB) 3.0	Tidak
SMB 3.0 Transparent Failover (TFO)	Tidak
SMB 3.0 dengan Berbagi File Peluasan Skala (SO)	Tidak
Sistem File Volume Bersama Kluster (CsvFS)	Ya
Sistem File Tangguh (ReFS)	Ya

SMB tidak mendukung fungsi manajemen volume.

Elemen Jalur Berikutnya

Elemen jalur berikutnya yang tidak valid diabaikan. Untuk jalur jarak jauh, seluruh jalur (bukan hanya elemen berikutnya) dianggap tidak valid jika salah satu kondisi berikut ini benar:

Jalur tidak terbentuk dengan benar.
Jalur tidak ada.
Pengguna saat ini tidak memiliki akses ke jalur tersebut.

Titik Persimpangan dan Folder terpasang

Jika jalur yang ditentukan melintasi titik persimpangan, GetVolumePathName mengembalikan volume yang dirujuk oleh titik persimpangan. Misalnya, jika W:\Adir adalah titik persimpangan yang menunjuk ke C:\Adir, maka GetVolumePathName dipanggil pada W:\Adir\Afile pengembalian C:\. Jika jalur yang ditentukan melintasi beberapa titik persimpangan, seluruh rantai diikuti, dan GetVolumePathName mengembalikan volume yang dirujuk oleh titik persimpangan terakhir dalam rantai.

Jika jalur jarak jauh ke folder atau titik persimpangan yang dipasang ditentukan, jalur diurai sebagai jalur jarak jauh, dan folder atau titik persimpangan yang dipasang diabaikan. Misalnya jika C:\Dir_C ditautkan ke D:\Dir_D dan C: dipetakan ke X: di komputer jarak jauh, memanggil GetVolumePathName dan menentukan X:\Dir_C pada komputer jarak jauh mengembalikan X:\.

Contoh

Untuk kumpulan contoh berikut, U: dipetakan ke komputer \\_YourComputer_\C$jarak jauh , dan Q adalah drive lokal.

Jalur yang ditentukan	Fungsi mengembalikan
`\\_YourComputer_\C$\Windows`	`\\_YourComputer_\C$\`
`\\?\UNC\_YourComputer_\C$\Windows`	`\\?\UNC\_YourComputer_\C$\`
`Q:\Windows`	`Q:\`
`\\?\Q:\Windows`	`\\?\Q:\`
`\\.\Q:\Windows`	`\\.\Q:\`
`\\?\UNC\W:\Windows`	FALSE dengan kesalahan 123 karena jalur jarak jauh yang ditentukan tidak valid; Berbagi W$ tidak ada atau tidak ada akses pengguna yang diberikan.
`C:\COM2` (yang ada)	`\\.\COM2\`
`C:\COM3` (tidak ada)	FALSE dengan kesalahan 123 karena perangkat COM yang tidak ada ditentukan.

Untuk kumpulan contoh berikut, jalur berisi elemen jalur berikutnya yang tidak valid.

Jalur yang ditentukan	Fungsi mengembalikan
`G:\invalid` (jalur tidak valid)	`G:\`
`\\.\I:\aaa\invalid` (jalur tidak valid)	`\\.\I:\`
`\\_YourComputer_\C$\invalid` (elemen jalur berikutnya tidak valid)	`\\_YourComputer_\C$\`

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	fileapi.h (sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Bagikan melalui