Fungsi FltSetInstanceContext (fltkernel.h)

Artikel
08/07/2023

FltSetInstanceContext menetapkan konteks untuk instans driver minifilter.

Sintaks

NTSTATUS FLTAPI FltSetInstanceContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] PFLT_CONTEXT              *OldContext
);

Parameter

[in] Instance

Penunjuk instans buram untuk instans.

[in] Operation

Bendera yang menentukan detail operasi yang akan dilakukan. Parameter ini harus salah satu dari berikut ini:

Bendera	Makna
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Jika konteks sudah diatur untuk instans yang ditunjukkan parameter Instans , FltSetInstanceContext akan mengganti konteks tersebut dengan konteks yang ditentukan dalam NewContext. Jika tidak, ini akan mengatur NewContext sebagai konteks untuk Instans.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Jika konteks sudah diatur untuk Instans ini, FltSetInstanceContext mengembalikan STATUS_FLT_CONTEXT_ALREADY_DEFINED, dan tidak mengganti konteks yang ada atau meningkatkan jumlah referensi. Jika konteks belum diatur, rutinitas akan mengatur NewContext sebagai konteks untuk Instans dan menaikkan jumlah referensi.

[in] NewContext

Arahkan ke konteks baru yang akan diatur untuk instans. Parameter ini diperlukan dan tidak boleh NULL.

[out] OldContext

Penunjuk ke variabel yang dialokasikan penelepon yang menerima alamat konteks instans yang ada, jika sudah diatur. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya tentang parameter ini, lihat bagian Keterangan berikut.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Jika FLT_SET_CONTEXT_KEEP_IF_EXISTS ditentukan untuk parameter Operasi , kode kesalahan ini menunjukkan bahwa konteks sudah dilampirkan ke instans. Hanya satu konteks yang dapat dilampirkan ke instans.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Konteks yang ditujukkan oleh parameter NewContext sudah ditautkan ke objek. Dengan kata lain, kode kesalahan ini menunjukkan bahwa NewContext sudah digunakan karena panggilan sebelumnya yang berhasil dari rutinitas Konteks FltSetXxx.
STATUS_FLT_DELETING_OBJECT	Instans yang ditentukan dalam parameter Instans sedang dikoyak. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid telah diteruskan. Misalnya, parameter NewContext tidak menunjuk ke konteks file yang valid, atau nilai yang tidak valid ditentukan untuk parameter Operasi . Ini adalah kode kesalahan.

Keterangan

Untuk informasi selengkapnya tentang konteks, lihat Tentang konteks minifilter.

Driver minifilter memanggil FltSetInstanceContext untuk melampirkan konteks instans ke instans driver minifilter milik pemanggil atau untuk menghapus atau mengganti konteks instans yang ada. Driver minifilter hanya dapat melampirkan satu konteks ke instans.

Penghitungan Referensi

Jika FltSetInstanceContext berhasil:

Jumlah referensi pada NewContext bertahap. Ketika konteks yang ditunjukkan oleh NewContext tidak lagi diperlukan, minifilter harus memanggil FltReleaseContext untuk mengurangi jumlah referensinya.

Jika tidak, jika FltSetInstanceContext gagal:

Jumlah referensi pada NewContext tetap tidak berubah.
Jika OldContext bukan NULL dan tidak menunjuk ke NULL_CONTEXT maka OldContext adalah penunjuk yang dirujuk ke konteks yang saat ini terkait dengan instans. Filter yang memanggil FltSetInstanceContext akhirnya harus memanggil FltReleaseContext untuk OldContext juga ketika penunjuk konteks tidak lagi diperlukan.

Terlepas dari keberhasilannya:

Filter yang memanggil FltSetInstanceContext harus memanggil FltReleaseContext untuk mengurangi jumlah referensi pada objek NewContext yang bertambah oleh FltAllocateContext.

Untuk informasi selengkapnya, lihat Mereferensikan Konteks.

Operasi konteks lainnya

Untuk informasi selengkapnya, lihat Mengatur Konteks, dan Merilis Konteks:

Untuk mengalokasikan konteks baru, panggil FltAllocateContext.
Untuk mendapatkan konteks instans, panggil FltGetInstanceContext.
Untuk menghapus konteks instans, panggil FltDeleteInstanceContext atau FltDeleteContext.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dan didukung di Microsoft Windows 2000 Update Rollup 1 untuk SP4, Windows XP SP2, Windows Server 2003 SP1, dan versi sistem operasi yang lebih baru.
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL