Fungsi FltAllocateCallbackData (fltkernel.h)

Artikel
03/01/2024

FltAllocateCallbackData mengalokasikan struktur data panggilan balik yang dapat digunakan driver minifilter untuk memulai permintaan I/O.

Sintaks

NTSTATUS FLTAPI FltAllocateCallbackData(
  [in]           PFLT_INSTANCE      Instance,
  [in, optional] PFILE_OBJECT       FileObject,
  [out]          PFLT_CALLBACK_DATA *RetNewCallbackData
);

Parameter

[in] Instance

Penunjuk instans buram untuk instans driver minifilter yang memulai operasi I/O. Parameter ini diperlukan dan tidak boleh NULL.

[in, optional] FileObject

Penunjuk objek file yang akan digunakan dalam operasi I/O. Parameter ini bersifat opsional dan dapat berupa NULL.

[out] RetNewCallbackData

Penunjuk ke variabel yang dialokasikan penelepon yang menerima alamat struktur data panggilan balik yang baru dialokasikan (FLT_CALLBACK_DATA).

Nilai kembali

FltAllocateCallbackData mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti berikut ini:

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	FltAllocateCallbackData mengalami kegagalan alokasi kumpulan saat mencoba mengalokasikan struktur data panggilan balik. Ini adalah kode kesalahan.

Keterangan

Driver minifilter dapat memanggil FltAllocateCallbackData untuk mengalokasikan struktur data panggilan balik (FLT_CALLBACK_DATA) untuk operasi I/O yang dimulai oleh driver minifilter.

Catatan Rutinitas FltAllocateCallbackData tidak mengalokasikan semua memori yang mungkin diperlukan oleh permintaan I/O berikutnya. Jika permintaan I/O, seperti FltPerformSynchronousIo atau FltPerformAsynchronousIo, memerlukan memori tambahan untuk beberapa struktur, permintaan dapat menemukan alokasi memori. Rutinitas FltAllocateCallbackDataEx dapat digunakan untuk menghindari potensi masalah ini dengan melakukan pra-alokasi memori untuk struktur tambahan yang akan digunakan dalam permintaan I/O. Jika ada masalah alokasi memori untuk struktur RetNewCallbackData atau struktur tambahan yang diperlukan, itu dapat ditangani pada titik alokasi data panggilan balik.

Struktur data panggilan balik dialokasikan dari kumpulan yang tidak dipagasi.

Setelah menginisialisasi parameter struktur data panggilan balik yang dikembalikan oleh FltAllocateCallbackData, pemanggil memulai operasi I/O dengan meneruskan struktur ke FltPerformSynchronousIo atau FltPerformAsynchronousIo. Rutinitas ini mengirim operasi I/O hanya ke instans driver minifilter yang terpasang di bawah instans yang memulai (ditentukan dalam parameter Instans ) dan ke sistem file. Driver minifilter yang terpasang di atas instans yang ditentukan tidak menerima operasi I/O.

Driver minifilter hanya dapat memulai operasi I/O berbasis IRP. Mereka tidak dapat memulai operasi panggilan balik I/O atau filter sistem file (FSFilter) yang cepat.

Driver minifilter harus menggunakan FltAllocateCallbackData, FltPerformAsynchronousIo, dan FltPerformSynchronousIo hanya untuk operasi I/O yang rutinitasnya seperti berikut ini tidak dapat digunakan:

FltClose

FltCreateFile

FltQueryVolumeInformation

FltReadFile

FltSetVolumeInformation

FltTagFile

FltUntagFile

FltWriteFile

Ketika struktur data panggilan balik yang dialokasikan oleh FltAllocateCallbackData tidak lagi diperlukan, pemanggil bertanggung jawab untuk membebaskannya dengan memanggil FltFreeCallbackData.