Fungsi FltSetTransactionContext (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltSetTransactionContext menetapkan konteks pada transaksi.

Sintaks

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parameter

[in] Instance

Penunjuk instans buram untuk pemanggil.

[in] Transaction

Pointer transaksi buram untuk transaksi tempat konteks diatur.

[in] Operation

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

Bendera	Makna
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Jika konteks sudah diatur untuk transaksi yang ditujukkan oleh parameter Transaksi , FltSetTransactionContext akan menggantinya dengan konteks yang ditujukkan oleh parameter NewContext . Jika tidak, itu akan mengatur konteks yang ditujukkan oleh parameter NewContext sebagai konteks untuk transaksi yang ditujukkan oleh parameter Transaksi .
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Jika konteks sudah diatur untuk transaksi yang ditunjukkan oleh parameter Transaksi , FltSetTransactionContext akan mengembalikan STATUS_FLT_CONTEXT_ALREADY_DEFINED, dan tidak akan menggantikan konteks yang ada atau meningkatkan jumlah referensi. Jika konteks belum ditetapkan, rutinitas ini akan mengatur konteks yang ditunjukkan oleh parameter NewContext sebagai konteks untuk transaksi yang ditunjukkan oleh parameter Transaksi , dan akan menaikkan jumlah referensi.

Bendera

Makna

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Jika konteks sudah diatur untuk transaksi yang ditujukkan oleh parameter Transaksi , FltSetTransactionContext akan menggantinya dengan konteks yang ditujukkan oleh parameter NewContext . Jika tidak, itu akan mengatur konteks yang ditujukkan oleh parameter NewContext sebagai konteks untuk transaksi yang ditujukkan oleh parameter Transaksi .

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Jika konteks sudah diatur untuk transaksi yang ditunjukkan oleh parameter Transaksi , FltSetTransactionContext akan mengembalikan STATUS_FLT_CONTEXT_ALREADY_DEFINED, dan tidak akan menggantikan konteks yang ada atau meningkatkan jumlah referensi. Jika konteks belum ditetapkan, rutinitas ini akan mengatur konteks yang ditunjukkan oleh parameter NewContext sebagai konteks untuk transaksi yang ditunjukkan oleh parameter Transaksi , dan akan menaikkan jumlah referensi.

[in] NewContext

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

[out, optional] OldContext

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

Nilai kembali

FltSetTransactionContext mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu dari 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 transaksi. Hanya satu konteks yang dapat dilampirkan ke transaksi untuk driver minifilter tertentu.
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 keberhasilan panggilan sebelumnya dari rutinitas KonteksXxxFltSet.
STATUS_FLT_DELETING_OBJECT
Instans yang ditentukan dalam parameter Instans sedang ditumbangkan. Ini adalah kode kesalahan.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid diteruskan. Misalnya, parameter NewContext tidak menunjuk ke konteks transaksi 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 FltSetTransactionContext untuk melampirkan konteks ke transaksi atau untuk menghapus atau mengganti konteks transaksi yang ada. Driver minifilter hanya dapat melampirkan satu konteks ke transaksi tertentu.

Penghitungan Referensi

Jika FltSetTransactionContext berhasil:

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

Jika tidak, jika FltSetTransactionContext 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 transaksi. Filter yang memanggil FltSetTransactionContext harus memanggil FltReleaseContext for OldContext juga ketika penunjuk konteks tidak lagi diperlukan.

Terlepas dari keberhasilannya:

Filter yang memanggil FltSetTransactionContext 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 transaksi, panggil FltGetTransactionContext.

Untuk menghapus konteks transaksi, panggil FltDeleteTransactionContext atau FltDeleteContext.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dan didukung di Windows Vista dan sistem operasi yang lebih baru.
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.