Fungsi FltAllocateExtraCreateParameter (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltAllocateExtraCreateParameter mengalokasikan kumpulan memori halaman untuk struktur konteks parameter buat tambahan (ECP) yang ditentukan pengguna dan menghasilkan penunjuk ke struktur tersebut.

Sintaks

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

Parameter

[in] Filter

Penunjuk filter buram untuk driver minifilter. Pointer ini secara unik mengidentifikasi driver minifilter dan tetap konstan selama driver minifilter dimuat.

[in] EcpType

Arahkan ke GUID yang ditentukan pengguna yang menunjukkan jenis struktur konteks ECP. Lihat Menggunakan GUID di Driver untuk informasi selengkapnya.

[in] SizeOfContext

Ukuran, dalam byte, dari struktur konteks yang ditentukan pengguna.

[in] Flags

Menentukan opsi alokasi kumpulan. Berikut ini menjelaskan bagaimana kumpulan akan dialokasikan ketika satu atau beberapa nilai bendera yang tercantum digabungkan dengan parameter Bendera dengan menggunakan operasi OR bitwise:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL - Kumpulan non-halaman akan dialokasikan. Jika nilai bendera ini tidak digunakan, kumpulan halaman akan dialokasikan.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - Semua kumpulan yang dialokasikan oleh rutinitas ini akan dikenakan terhadap kuota memori proses saat ini.

Jika lebih dari satu bendera digunakan, semua efek yang terkait dengan nilai bendera yang digunakan akan terjadi.

[in, optional] CleanupCallback

Penunjuk opsional ke rutinitas panggilan balik pembersihan tipe PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK yang ditentukan minifilter. Rutinitas panggilan balik pembersihan dipanggil ketika struktur ECP (dibuat oleh rutinitas FltAllocateExtraCreateParameter ) dihapus. Atur parameter ini ke NULL jika rutinitas panggilan balik pembersihan tidak berlaku.

[in] PoolTag

Menentukan tag kumpulan untuk memori yang dialokasikan. Untuk informasi selengkapnya, lihat parameter TagExAllocatePoolWithTag.

[out] EcpContext

Menerima penunjuk ke struktur konteks ECP yang dialokasikan. Jika rutinitas gagal mengalokasikan kumpulan yang memadai, *EcpContext akan null dan rutinitas akan mengembalikan kode status STATUS_INSUFFICIENT_RESOURCES.

Nilai kembali

FltAllocateExtraCreateParameter dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameter tidak dapat mengalokasikan memori yang cukup untuk struktur ECP. Dalam hal ini, EcpContext akan menjadi NULL.
STATUS_SUCCESS	Struktur ECP berhasil dialokasikan. Dalam hal ini, penunjuk ke struktur yang dialokasikan dikembalikan dalam parameter EcpContext .

Keterangan

Secara default, rutinitas FltAllocateExtraCreateParameter mengalokasikan kumpulan memori halaman untuk struktur konteks ECP yang ditentukan pengguna. Jika bitmask FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL digunakan seperti yang dijelaskan di atas, kumpulan memori non-halaman dialokasikan. Setelah kumpulan ini dialokasikan dan struktur konteks ECP telah diinisialisasi, rutinitas FltInsertExtraCreateParameter digunakan untuk memasukkan struktur konteks ECP (elemen daftar ECP) ke dalam struktur daftar ECP (daftar ECP).

Kumpulan memori yang dialokasikan oleh rutinitas FltAllocateExtraCreateParameter tidak secara otomatis dikosongkan oleh sistem operasi. Kumpulan memori ini pada akhirnya harus dirilis dengan menggunakan salah satu metode berikut:

Panggil rutinitas FltRemoveExtraCreateParameter untuk menghapus struktur konteks ECP dari daftar ECP lalu panggil rutinitas FltFreeExtraCreateParameter untuk membebaskan struktur konteks ECP itu sendiri. Daftar ECP tetap ada.
Panggil rutinitas FltFreeExtraCreateParameterList - ini membebaskan daftar ECP termasuk elemen daftar apa pun (struktur konteks ECP). Daftar ECP dihancurkan.

Namun, jika sistem file atau driver filter sistem file melampirkan ECP ke ECP_LIST yang sudah ada atau yang baru dibuat saat memproses permintaan IRP_MJ_CREATE, ECP ini secara otomatis dibersihkan ketika IRP selesai. Akibatnya, driver filter tidak harus membersihkan ECP yang ditambahkan secara dinamis. Hal ini memungkinkan ECP driver filter untuk disebarluaskan dengan benar di seluruh titik reparse--proses yang dapat memerlukan beberapa permintaan IRP_MJ_CREATE untuk dihasilkan.