Fungsi FltCbdqInitialize (fltkernel.h)

Artikel
08/07/2023

FltCbdqInitialize menginisialisasi tabel pengiriman antrean data panggilan balik driver minifilter.

Sintaks

NTSTATUS FLTAPI FltCbdqInitialize(
  [in]      PFLT_INSTANCE                                 Instance,
  [in, out] PFLT_CALLBACK_DATA_QUEUE                      Cbdq,
  [in]      PFLT_CALLBACK_DATA_QUEUE_INSERT_IO            CbdqInsertIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO            CbdqRemoveIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO         CbdqPeekNextIo,
  [in]      PFLT_CALLBACK_DATA_QUEUE_ACQUIRE              CbdqAcquire,
  [in]      PFLT_CALLBACK_DATA_QUEUE_RELEASE              CbdqRelease,
  [in]      PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO CbdqCompleteCanceledIo
);

Parameter

[in] Instance

Penunjuk instans buram untuk instans yang antrean data panggilan baliknya akan diinisialisasi.

[in, out] Cbdq

Penunjuk ke antrean data panggilan balik yang dialokasikan oleh driver minifilter.

[in] CbdqInsertIo

Penunjuk ke rutinitas panggilan balik sisipan yang disediakan penelepon. Manajer Filter memanggil rutinitas ini untuk menyisipkan struktur data panggilan balik yang ditentukan ke dalam antrean. Rutinitas ini dinyatakan sebagai berikut:

typedef NTSTATUS
(*PFLT_CALLBACK_DATA_QUEUE_INSERT_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID InsertContext
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Cbd

Arahkan ke struktur data panggilan balik untuk dimasukkan ke dalam antrean.

SisipkanKonteks

Penunjuk informasi konteks yang diteruskan sebagai parameter InsertContext ke FltCbdqInsertIo.

[in] CbdqRemoveIo

Penunjuk ke rutinitas hapus panggilan balik yang disediakan penelepon. Manajer Filter memanggil rutinitas ini untuk menghapus struktur data panggilan balik yang ditentukan dari antrean. Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_REMOVE_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Cbd

Arahkan ke struktur data panggilan balik yang akan dihapus dari antrean.

[in] CbdqPeekNextIo

Penunjuk ke rutinitas panggilan balik intip yang disediakan penelepon. Manajer Filter memanggil fungsi ini untuk mendapatkan penunjuk ke operasi I/O berikutnya yang cocok dengan PeekContext dalam antrean; atau, jika Cbdadalah NULL, untuk mendapatkan penunjuk ke operasi I/O pertama yang cocok dalam antrean. Driver minifilter sepenuhnya mendefinisikan arti PeekContext dan menentukan kapan operasi I/O cocok dengan PeekContext tertentu. Rutinitas ini dinyatakan sebagai berikut:

typedef PFLT_CALLBACK_DATA
(*PFLT_CALLBACK_DATA_QUEUE_PEEK_NEXT_IO)(
      _In_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ PFLT_CALLBACK_DATA Cbd,
      _In_opt_ PVOID PeekContext
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Cbd

Arahkan ke struktur data panggilan balik yang menandai posisi dalam antrean untuk mulai mencari kecocokan dengan PeekContext. Jika CbdNULL, pencarian dimulai di kepala antrean.

PeekContext

Penunjuk informasi konteks yang diteruskan sebagai parameter PeekContext ke FltCbdqRemoveNextIo.

[in] CbdqAcquire

Penunjuk ke rutinitas panggilan balik penguncian antrean yang disediakan penelepon. Manajer Filter memanggil rutinitas ini untuk memperoleh kunci pada antrean sebelum mencoba menyisipkan atau menghapus item dari antrean. Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_ACQUIRE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Out_opt_ PKIRQL Irql
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Irql

Penunjuk ke variabel yang disediakan sistem yang menerima IRQL saat ini. Variabel yang sama diteruskan ke rutinitas CbdqRelease yang sesuai.

[in] CbdqRelease

Penunjuk ke rutinitas panggilan balik kunci antrean rilis yang disediakan penelepon. Manajer Filter memanggil rutinitas ini untuk melepaskan kunci yang diperolehnya dengan memanggil rutinitas CbdqAcquire yang sesuai. Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_RELEASE)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _In_opt_ KIRQL Irql
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Irql

Variabel yang disediakan sistem yang sama yang menerima IRQL saat ini sebagai parameter Irql ke rutinitas CbdqAcquire yang sesuai.

[in] CbdqCompleteCanceledIo

Pointer ke rutinitas pembatalan yang disediakan penelepon. Manajer Filter memanggil rutinitas ini untuk memberi sinyal ke driver minifilter untuk menyelesaikan operasi I/O yang dibatalkan. Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLT_CALLBACK_DATA_QUEUE_COMPLETE_CANCELED_IO)(
      _Inout_ PFLT_CALLBACK_DATA_QUEUE Cbdq,
      _Inout_ PFLT_CALLBACK_DATA Cbd
      );

Cbdq

Arahkan kursor ke antrean data panggilan balik driver minifilter yang batal aman. Antrean ini harus telah diinisialisasi dengan memanggil FltCbdqInitialize.

Cbd

Arahkan ke struktur data panggilan balik untuk operasi I/O yang dibatalkan.

Nilai kembali

FltCbdqInitialize mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai.

Keterangan

Antrean data panggilan balik yang baru diinisialisasi dalam status diaktifkan, yang berarti bahwa item struktur data panggilan balik dapat dimasukkan ke dalam antrean. Antrean dapat dinonaktifkan dengan memanggil FltCbdqDisable dan diaktifkan kembali dengan memanggil FltCbdqEnable.

Driver minifilter dapat menggunakan rutinitas FltCbdqXxx untuk menerapkan antrean data panggilan balik untuk operasi I/O berbasis IRP. Dengan menggunakan rutinitas ini, pengemudi minifilter dapat membuat antrean mereka batal aman; sistem secara transparan menangani pembatalan I/O untuk driver minifilter.

Rutinitas FltCbdqXxx hanya dapat digunakan untuk operasi I/O berbasis IRP. Untuk menentukan apakah struktur data panggilan balik tertentu mewakili operasi I/O berbasis IRP, gunakan makro FLT_IS_IRP_OPERATION .

Driver minifilter dapat menggunakan implementasi internal apa pun untuk antrean. Manajer Filter berinteraksi dengan implementasi antrean driver minifilter hanya melalui serangkaian rutinitas pengiriman yang disediakan oleh FltCbdqInitialize.

Sistem secara otomatis mengunci dan membuka kunci antrean seperlunya. Driver minifilter tidak menerapkan penguncian apa pun di dalam rutinitas CbdqInsertIo, CbdqRemoveIo, dan CbdqPeekNextIo mereka.

Driver minifilter dapat menggunakan salah satu primitif sinkronisasi sistem operasi sebagai mekanisme penguncian dalam rutinitas CbdqAcquire dan CbdqRelease mereka, seperti kunci putar, objek mutex, atau variabel sumber daya. Perhatikan bahwa jika driver minifilter menggunakan kunci putar daripada mutex atau sumber daya untuk melindungi antrean, itu dapat memanggil rutinitas FltCbdqXxx di IRQL <= DISPATCH_LEVEL. Jika mutex atau sumber daya digunakan, driver minifilter harus berjalan di IRQL <= APC_LEVEL ketika memanggil salah satu rutinitas ini kecuali FltCbdqInitialize.

Driver minifilter tidak memanipulasi antrean secara langsung. Sebaliknya, ia memanggil FltCbdqInsertIo, FltCbdqRemoveIo, dan FltCbdqRemoveNextIo untuk menambahkan atau menghapus struktur data panggilan balik. Rutinitas ini pada gilirannya memanggil fungsi panggilan balik yang disediakan driver minifilter untuk FltCbdqInitialize.

Driver minifilter harus menerapkan rutinitas antrean sebagai berikut.

Rutinitas Cbdq	Implementasi
CbdqInsertIo	Sisipkan struktur data panggilan balik yang ditentukan ke dalam antrean.
CbdqRemoveIo	Hapus struktur data panggilan balik yang ditentukan dari antrean.
CbdqPeekNextIo	Rutinitas ini harus memungkinkan sistem untuk mengulangi struktur data panggilan balik dengan PeekContext yang cocok dalam antrean. Cbd = CbdqPeekNextIo(Cbdq, NULL, PeekContext) harus mengembalikan entri pencocokan pertama dalam antrean, dan CbdqPeekNextIo(Cbdq, Cbd, PeekContext) harus mengembalikan entri pencocokan berikutnya setelah struktur data panggilan balik yang diberikan dalam antrean. Driver minifilter sepenuhnya mendefinisikan arti PeekContext dan menentukan kapan struktur data panggilan balik cocok dengan nilai PeekContext .
CbdqAcquire	Rutinitas ini harus mengunci antrean sehingga tidak ada utas lain yang dapat mengaksesnya. Driver minifilter dapat menggunakan mekanisme penguncian apa pun untuk mengunci antrean. Jika driver minifilter menggunakan rutinitas KeAcquireSpinLock , driver minifilter dapat menggunakan lokasi memori yang ditujukkan oleh parameter Irql rutin untuk menyimpan IRQL. Jika tidak, driver minifilter dapat mengabaikan parameter tersebut.
CbdqRelease	Rutinitas ini harus membuka kunci antrean yang dibuat oleh CbdqAcquire. Jika driver minifilter menggunakan kunci putar dan mengembalikan nilai IRQL dalam parameter IrqlCbdqAcquire, sistem meneruskan nilai tersebut dalam parameter IrqlCbdqRelease. Driver minifilter dapat menggunakan IRQL untuk membuka kunci spin dengan memanggil KeReleaseSpinLock. Jika tidak, driver minifilter dapat mengabaikan parameter Irql .
CbdqCompleteCanceledIo	Rutinitas ini harus menyelesaikan operasi I/O yang dibatalkan. Biasanya, driver minifilter hanya dapat memanggil FltCompletePendedPreOperation(Data, FLT_PREOP_COMPLETE, NULL). Driver minifilter tidak perlu menghapus antrean struktur data panggilan balik -- Manajer Filter secara otomatis memanggil CbdqRemoveIo antrean sebelum memanggil CbdqCompleteCanceledIo.