Fungsi FltGetVolumeGuidName (fltkernel.h)

Artikel
08/07/2023

FltGetVolumeGuidName mendapatkan nama volume untuk volume tertentu, dalam format pengidentifikasi unik global volume (GUID).

Sintaks

NTSTATUS FLTAPI FltGetVolumeGuidName(
  [in]               PFLT_VOLUME     Volume,
  [in/out, optional] PUNICODE_STRING VolumeGuidName,
  [out, optional]    PULONG          BufferSizeNeeded
);

Parameter

[in] Volume

Penunjuk buram untuk volume. Harus berupa volume sistem file lokal. Parameter ini diperlukan dan tidak boleh NULL.

[in/out, optional] VolumeGuidName

Penunjuk ke struktur UNICODE_STRING yang dialokasikan pemanggil yang menerima nama GUID volume saat STATUS_SUCCESS dikembalikan. Ketahuilah bahwa kumpulan untuk VolumeGuidName-Buffer> juga dialokasikan pemanggil.

Jika VolumeGuidName adalah NULL dan BufferSizeNeeded bukan NULL, FltGetVolumeGuidName menyimpan ukuran buffer yang diperlukan untuk GUID volume yang diminta di parameter BufferSizeNeeded dan mengembalikan STATUS_BUFFER_TOO_SMALL. Lihat Keterangan.

[out, optional] BufferSizeNeeded

Penunjuk ke variabel yang dialokasikan penelepon yang menerima ukuran, dalam byte, dari nama GUID volume yang diminta. Parameter ini bersifat opsional dan dapat berupa NULL; namun, itu harus non-NULL jika VolumeGuidName adalah NULL sehingga FltGetVolumeGuidName dapat menyimpan ukuran buffer yang diperlukan untuk GUID volume yang diminta.

Mengembalikan nilai

FltGetVolumeGuidName mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai, seperti salah satu dari berikut ini:

Menampilkan kode	Deskripsi
STATUS_BUFFER_TOO_SMALL	Buffer yang ditunjukkan oleh VolumeGuidName adalah NULL atau terlalu kecil untuk menahan GUID volume. Jika penelepon memberikan nilai non-NULL untuk BufferSizeNeeded, FltGetVolumeGuidName menyimpan ukuran buffer yang diperlukan di BufferSizeNeeded. Ini dianggap sebagai kode kesalahan karena nama GUID volume tidak diambil.
STATUS_INSUFFICIENT_RESOURCES	FltGetVolumeGuidName mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_DEVICE_REQUEST	Parameter Volume adalah handel untuk volume jaringan. Ini adalah kode kesalahan.
STATUS_FLT_VOLUME_NOT_FOUND	Tidak ditemukan volume yang cocok. Ini adalah kode kesalahan.

Keterangan

Nama GUID volume yang dikembalikan dinyatakan dalam format berikut:

\?? \Volume{GUID}

di mana GUID adalah pengidentifikasi unik global yang mengidentifikasi volume. Format ini, yang sama dengan yang digunakan oleh manajer pemasangan, dijelaskan dalam Mendukung Permintaan Mount Manager di Driver Kelas Penyimpanan.

Jika BufferSizeNeeded tidak diketahui, panggil FltGetVolumeGuidName dua kali:

Pada panggilan pertama, atur VolumeGuidName ke NULL dan BufferSizeNeeded ke non-NULL. FltGetVolumeGuidName akan menyimpan jumlah byte yang diperlukan untuk nama volume GUID di BufferSizeNeeded dan mengembalikan STATUS_BUFFER_TOO_SMALL.
Pada panggilan kedua, atur VolumeGuidName untuk menunjuk ke struktur yang merupakan ukuran nilai BufferSizeNeeded yang dikembalikan dalam panggilan pertama.

FltGetVolumeGuidName tidak dapat dipanggil dengan aman dari panggilan balik pra-pemasangan atau pasca-pemasangan. Ini tidak dapat dipanggil dengan aman karena bahkan ketika panggilan balik pasca-pemasangan dipanggil, pemrosesan pemasangan belum diselesaikan oleh manajer I/O, dan ini menyebabkan kebuntuan dengan manajer pemasangan dalam kasus tertentu.

Pada Windows Vista dan yang lebih baru, driver minifilter dapat dengan aman memanggil FltGetVolumeGuidName dari rutinitas InstanceSetupCallback (PFLT_INSTANCE_SETUP_CALLBACK) karena panggilan balik dipanggil pada operasi I/O pertama untuk volume baru setelah semua pemrosesan pemasangan selesai.

Pada sistem operasi Windows yang lebih lama dari Windows Vista, FltGetVolumeGuidName tidak dapat dipanggil dengan aman dari rutinitas InstanceSetupCallback karena manajer pemasangan mungkin mengeluarkan operasi I/O file saat menahan kunci, yang dapat menyebabkan kebuntuan.

Penting untuk dicatat bahwa GUID volume tidak sama dengan ID objek volume. GUID volume, atau nama volume unik, adalah nilai independen sistem file; ini ditetapkan ke volume penyimpanan yang mendasar oleh manajer pemasangan. ID objek volume ditetapkan ke volume sistem file oleh sistem file.

Untuk mendapatkan ID objek volume untuk volume, panggil ZwQueryVolumeInformationFile, menentukan FileFsObjectIdInformation untuk parameter FsInformationClass .

FltGetVolumeGuidName kira-kira setara dengan fungsi Win32 GetVolumeNameForVolumeMountPoint . (GetVolumeNameForVolumeMountPoint didokumenkan dalam Microsoft Windows SDK.)