Fungsi FltAllocateContext (fltkernel.h)

Artikel
03/15/2024

Rutinitas FltAllocateContext mengalokasikan struktur konteks untuk jenis konteks tertentu.

Sintaks

NTSTATUS FLTAPI FltAllocateContext(
  [in]  PFLT_FILTER      Filter,
  [in]  FLT_CONTEXT_TYPE ContextType,
  [in]  SIZE_T           ContextSize,
  [in]  POOL_TYPE        PoolType,
  [out] PFLT_CONTEXT     *ReturnedContext
);

Parameter

[in] Filter

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

[in] ContextType

Nilai FLT_CONTEXT_TYPE yang menunjukkan jenis konteks yang akan dialokasikan. ContextType bisa menjadi salah satu hal berikut ini:

Nilai	Makna
FLT_VOLUME_CONTEXT (0x0001)	Mengalokasikan konteks volume.
FLT_INSTANCE_CONTEXT (0x0002)	Mengalokasikan konteks instans.
FLT_FILE_CONTEXT (0x0004)	Mengalokasikan konteks file.
FLT_STREAM_CONTEXT (0x0008)	Mengalokasikan konteks aliran.
FLT_STREAMHANDLE_CONTEXT (0x0010)	Mengalokasikan konteks handel aliran.
FLT_TRANSACTION_CONTEXT (0x0020)	Mengalokasikan konteks transaksi.
FLT_SECTION_CONTEXT (0x0040)	Mengalokasikan konteks bagian. Tersedia mulai dari Windows 8.

[in] ContextSize

Ukuran, dalam byte, dari bagian konteks yang ditentukan oleh driver minifilter. Harus lebih besar dari nol dan kurang dari atau sama dengan MAXUSHORT; untuk konteks ukuran tetap, harus kurang dari atau sama dengan Ukuran yang ditentukan dalam struktur FLT_CONTEXT_REGISTRATION . Minifilter menggunakan bagian konteks ini untuk mempertahankan informasi konteks khusus untuk dirinya sendiri. FltMgr memperlakukan bagian struktur konteks ini sebagai buram. Parameter ini diperlukan dan tidak boleh nol.

[in] PoolType

Jenis kumpulan yang akan dialokasikan. Parameter ini diperlukan dan harus salah satu dari berikut ini. Lihat POOL_TYPE untuk deskripsi terperinci tentang setiap jenis. Lihat Keterangan untuk informasi selengkapnya.

Nilai	Makna
NonPagedPool	Memori sistem yang tidak dapat dimanfaatkan. PoolType harus NonPagedPool jika ContextType FLT_VOLUME_CONTEXT.
PagedPool	Memori sistem yang dapat di-pageable.
NonPagedPoolNx	Kumpulan tanpa eksekusi (NX) yang tidak disebarkan.

[out] ReturnedContext

Penunjuk ke variabel yang dialokasikan pemanggil yang menerima alamat konteks yang baru dialokasikan. Pemanggil bertanggung jawab untuk memanggil FltReleaseContext untuk merilis konteks ini ketika tidak lagi diperlukan.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_FLT_CONTEXT_ALLOCATION_NOT_FOUND	Informasi alokasi untuk konteks jenis yang ditentukan tidak disediakan pada saat pendaftaran filter. ATAU, untuk konteks ukuran tetap, ContextSize yang diminta lebih besar dari Ukuran yang ditentukan dalam struktur FLT_CONTEXT_REGISTRATION untuk ContextType yang ditentukan.
STATUS_FLT_DELETING_OBJECT	Driver minifilter yang ditentukan dalam parameter Filter sedang dirobohkan. Ini adalah kode kesalahan.
STATUS_INSUFFICIENT_RESOURCES	FltAllocateContext mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_INVALID_BUFFER_SIZE	ContextSize tidak boleh lebih besar dari MAXUSHORT. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Nilai yang tidak valid ditentukan untuk parameter ContextType atau ContextSize . Ini adalah kode kesalahan.
STATUS_NOT_SUPPORTED	Sistem file tidak mendukung konteks per aliran. Ini adalah kode kesalahan.

Keterangan

Untuk informasi selengkapnya tentang konteks, lihat Tentang konteks minifilter.

FltAllocateContext mengalokasikan konteks jenis yang ditentukan dari kumpulan yang ditentukan. Mulai dari Windows 11, apakah memori yang dirujuk ReturnedContext adalah nol tergantung sebagai berikut:

Memori dijamin akan di-nol untuk konteks berukuran variabel.
Konten memori ditentukan implementasi untuk konteks berukuran tetap yang dialokasikan oleh fungsi panggilan balik yang disediakan pemanggil.
Jika tidak, memori tidak dapat diasumsikan sebagai nol untuk konteks berukuran tetap karena perilaku daftar yang terlihat. Artinya, entri yang dikembalikan dari daftar lookaside mungkin tidak nol jika itu adalah memori yang sebelumnya dikosongkan ke daftar lookaside dibandingkan dengan alokasi baru.

Sebelum Windows 11, konten konteks yang dikembalikan tidak di-nol.

Mengatur PoolType ke nilai yang tidak valid dapat mengakibatkan perilaku tak terduga seperti menyebabkan daftar lookaside dilewati, yang mengakibatkan hilangnya manfaat performa daftar lookaside. Untuk konteks yang memiliki fungsi panggilan balik ContextAllocateCallback , perilaku karena PoolType yang tidak valid bergantung pada implementasi.

Setelah konteks dialokasikan, konteks dapat diatur pada objek dengan meneruskan penunjuk ReturnedContext ke rutinitas set-context yang sesuai dari tabel berikut.

Jenis Konteks	Rutinitas Set-Context
FLT_FILE_CONTEXT	FltSetFileContext (dimulai dengan Windows Vista)
FLT_INSTANCE_CONTEXT	FltSetInstanceContext
FLT_SECTION_CONTEXT	FltCreateSectionForDataScan (dimulai dengan Windows 8)
FLT_STREAM_CONTEXT	FltSetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltSetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltSetTransactionContext (dimulai dengan Windows Vista)
FLT_VOLUME_CONTEXT	FltSetVolumeContext

Ketika driver minifilter memanggil FltRegisterFilter dari rutinitas DriverEntry-nya , driver harus mendaftarkan setiap jenis konteks yang digunakannya. Untuk informasi selengkapnya, lihat entri referensi untuk struktur FLT_CONTEXT_REGISTRATION , dan Mendaftarkan jenis konteks.

FltAllocateContext tidak menginisialisasi isi bagian struktur konteks khusus untuk driver minifilter.

Untuk mendapatkan konteks objek, panggil FltGetContexts atau rutinitas get-context yang sesuai dari tabel berikut.

Jenis Konteks	Rutinitas Get-Context
FLT_FILE_CONTEXT	FltGetFileContext (dimulai dengan Windows Vista)
FLT_INSTANCE_CONTEXT	FltGetInstanceContext
FLT_SECTION_CONTEXT	FltGetSectionContext (dimulai dengan Windows 8)
FLT_STREAM_CONTEXT	FltGetStreamContext
FLT_STREAMHANDLE_CONTEXT	FltGetStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltGetTransactionContext (dimulai dengan Windows Vista )
FLT_VOLUME_CONTEXT	FltGetVolumeContext

Konteks dihitung referensi, dan pada pengembalian yang berhasil dari FltAllocateContext, konteks yang ditunjukkan oleh ReturnedContext telah diinisialisasi untuk memiliki jumlah referensi 1. Konteks dikosongkan secara otomatis ketika jumlah referensinya mencapai nol. Untuk menambah jumlah referensi pada konteks, panggil FltReferenceContext.

Untuk mengurangi jumlah referensi pada konteks, panggil FltReleaseContext.

Karena konteks dihitung referensi, biasanya tidak perlu menghapusnya. Untuk menghapus konteks secara eksplisit, panggil FltDeleteContext atau rutinitas delete-context yang sesuai dari tabel berikut.

Jenis Konteks	Rutinitas Delete-Context
FLT_FILE_CONTEXT	FltDeleteFileContext (dimulai dengan Windows Vista)
FLT_INSTANCE_CONTEXT	FltDeleteInstanceContext
FLT_SECTION_CONTEXT	FltCloseSectionForDataScan (dimulai dengan Windows 8)
FLT_STREAM_CONTEXT	FltDeleteStreamContext
FLT_STREAMHANDLE_CONTEXT	FltDeleteStreamHandleContext
FLT_TRANSACTION_CONTEXT	FltDeleteTransactionContext (dimulai dengan Windows Vista)
FLT_VOLUME_CONTEXT	FltDeleteVolumeContext