Fungsi FltAttachVolumeAtAltitude (fltkernel.h)

Artikel
02/26/2024

FltAttachVolumeAtAltitude adalah rutinitas dukungan debugging yang melampirkan instans driver minifilter ke volume pada ketinggian yang ditentukan, mengesampingkan pengaturan apa pun dalam file INF driver minifilter.

Sintaks

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

Parameter

[in, out] Filter

Penunjuk filter buram untuk pemanggil. Parameter ini diperlukan dan tidak boleh NULL.

[in, out] Volume

Penunjuk volume buram untuk volume tempat instans driver minifilter dilampirkan. Parameter ini diperlukan dan tidak boleh NULL.

[in] Altitude

Penunjuk ke struktur UNICODE_STRING yang berisi string ketinggian untuk instans. Parameter ini diperlukan dan tidak boleh NULL. (Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.)

[in, optional] InstanceName

Arahkan ke struktur UNICODE_STRING yang berisi nama instans untuk instans baru. Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, FltAttachVolumeAtAltitude menghasilkan nama instans dari nama driver minifilter dan string ketinggian yang dituju oleh Ketinggian . Nama yang dihasilkan dipotok, jika perlu, untuk INSTANCE_NAME_MAX_CHARS karakter.

[out, optional] RetInstance

Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk instans buram untuk instans yang baru dibuat. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

FltAttachVolumeAtAltitude mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode	Deskripsi
STATUS_FLT_DELETING_OBJECT	Filter atau Volume yang ditentukan sedang ditumbangkan. Ini adalah kode kesalahan.
STATUS_FLT_FILTER_NOT_READY	Driver minifilter belum mulai memfilter. Untuk informasi selengkapnya, lihat FltStartFiltering. Ini adalah kode kesalahan.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Instans sudah ada di ketinggian ini pada volume yang ditentukan. Ini adalah kode kesalahan.
STATUS_FLT_INSTANCE_NAME_COLLISION	Instans sudah ada dengan nama ini pada volume yang ditentukan. Ini adalah kode kesalahan.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Struktur UNICODE_STRING yang menunjuk Ketinggian tidak berisi string ketinggian yang valid. Ini adalah kode kesalahan.

Keterangan

Driver minifilter hanya boleh menggunakan FltAttachVolumeAtAltitude untuk debugging. Seharusnya tidak menyebut rutinitas ini dalam versi ritel driver minifilter.

FltAttachVolumeAtAltitude adalah kernel yang setara dengan fungsi Win32 FilterAttachAtAltitude .

Istilah "ketinggian" mengacu pada posisi yang ditempati instans (atau harus menempati) dalam 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 array karakter lebar yang berisi satu atau beberapa digit desimal dari 0 hingga 9; array 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.

Nama instans yang ditentukan dalam parameter InstanceName harus unik di seluruh sistem.

FltAttachVolumeAtAltitude mengembalikan pointer instans buram untuk instans baru di *RetInstance. Nilai pointer ini secara unik mengidentifikasi instans driver minifilter dan tetap konstan selama instans dilampirkan ke volume.

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

Untuk membandingkan ketinggian dua instans driver minifilter yang melekat pada volume yang sama, panggil FltCompareInstanceAltitudes.

Untuk melepaskan instans driver minifilter dari volume, panggil FltDetachVolume.