Fungsi FltGetVolumeInstanceFromName (fltkernel.h)

Artikel
03/01/2024

Rutinitas FltGetVolumeInstanceFromName mengembalikan penunjuk instans buram untuk instans driver minifilter yang diberikan pada volume yang diberikan.

Sintaks

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Parameter

[in, optional] Filter

Penunjuk filter buram untuk driver minifilter yang memiliki instans. Parameter ini bersifat opsional dan dapat berupa NULL.

[in] Volume

Penunjuk buram untuk volume tempat instans dilampirkan. Harus berupa handel volume yang valid. Parameter ini diperlukan dan tidak boleh NULL. (Mengatur parameter ini ke nilai yang tidak valid menyebabkan sistem menegaskan pada build yang diperiksa.)

[in, optional] InstanceName

Arahkan ke struktur UNICODE_STRING yang dialokasikan pemanggil yang berisi nama instans untuk instans pada volume. (Ini adalah nilai InstanceName yang diteruskan ke FltAttachVolume atau FltAttachVolumeAtAltitude saat instans dibuat.) Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, FltGetVolumeInstanceFromName mengembalikan instans pencocokan tertinggi yang ditemukan.

[out] RetInstance

Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk instans buram untuk instans yang cocok dengan nilai untuk Filter, Volume, dan InstanceName. Parameter ini diperlukan dan tidak boleh NULL.

Nilai kembali

FltGetVolumeInstanceFromName mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai, seperti salah satu hal berikut:

Menampilkan kode	Deskripsi
STATUS_FLT_DELETING_OBJECT	Instans sedang dikoyak. Ini adalah kode kesalahan.
STATUS_FLT_INSTANCE_NOT_FOUND	Tidak ditemukan instans yang cocok. Ini adalah kode kesalahan.

Keterangan

FltGetVolumeInstanceFromName mencari daftar instans driver minifilter yang dilampirkan ke volume yang ditentukan dalam parameter Volume dalam urutan penurunan ketinggian, dimulai dengan instans paling atas. Jika lebih dari satu instans cocok dengan nilai yang diberikan untuk parameter Filter, Volume, dan InstanceName , FltGetVolumeInstanceFromName mengembalikan instans pencocokan tertinggi yang ditemukan.

Istilah "ketinggian" mengacu pada posisi yang diduduki instans (atau harus menempati) di tumpukan instans driver minifilter untuk volume. Semakin tinggi ketinggian, semakin jauh instans berasal dari sistem file dasar di tumpukan. Hanya satu instans yang dapat dilampirkan pada ketinggian tertentu pada volume tertentu.

Ketinggian ditentukan oleh string ketinggian, yang merupakan string Unicode terhitung yang terdiri dari satu atau beberapa digit desimal dari 0 hingga 9, dan dapat menyertakan satu titik desimal. Misalnya, "100.123456" dan "03333" adalah string ketinggian yang valid.

String "03333" mewakili ketinggian yang lebih tinggi daripada "100.123456". (Nol di depan dan di belakang diabaikan.) Dengan kata lain, instans yang ketinggiannya adalah "03333" lebih jauh dari sistem file dasar daripada instans yang ketinggiannya adalah "100.123456". Namun, perbandingan ini hanya bermakna jika kedua instans dilampirkan ke volume yang sama.

FltGetVolumeInstanceFromName menambahkan referensi rundown ke pointer instans buram yang dikembalikan dalam parameter RetInstance . Ketika pointer ini tidak lagi diperlukan, pemanggil harus melepaskannya dengan memanggil FltObjectDereference. Dengan demikian setiap panggilan yang berhasil ke FltGetVolumeInstanceFromName harus dicocokkan dengan panggilan berikutnya ke FltObjectDereference.