Fungsi FltSetStreamContext (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltSetStreamContext menetapkan konteks untuk aliran file.

Sintaks

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

Parameter

[in] Instance

Penunjuk instans buram untuk instans driver minifilter yang konteksnya akan dimasukkan ke dalam, dihapus dari, atau diganti dalam daftar konteks yang dilampirkan ke aliran file.

[in] FileObject

Penunjuk ke objek file untuk aliran file.

[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 Instans, FltSetStreamContext akan menggantinya dengan konteks yang ditentukan dalam NewContext. Jika tidak, ini akan menyisipkan NewContext ke dalam daftar konteks untuk aliran file.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Jika konteks sudah diatur untuk Instans ini, FltSetStreamContext akan mengembalikan STATUS_FLT_CONTEXT_ALREADY_DEFINED, dan tidak akan menggantikan konteks yang ada atau meningkatkan jumlah referensi. Jika konteks belum ditetapkan, rutinitas akan menyisipkan NewContext ke dalam daftar konteks untuk aliran file dan menambahkan jumlah referensi.

[in] NewContext

Penunjuk ke konteks baru yang akan diatur untuk aliran file. Parameter ini diperlukan dan tidak boleh NULL.

[out] OldContext

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

Nilai kembali

Rutinitas FltSetStreamContext 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 Operasi, kode kesalahan ini menunjukkan bahwa konteks aliran sudah dilampirkan ke aliran file.
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 aliran yang valid, atau nilai yang tidak valid ditentukan untuk parameter Operasi . Ini adalah kode kesalahan.
STATUS_NOT_SUPPORTED	Sistem file tidak mendukung konteks per aliran untuk aliran file ini. Ini adalah kode kesalahan.

Keterangan

Untuk informasi selengkapnya tentang konteks, lihat Tentang konteks minifilter.

Driver minifilter memanggil FltSetStreamContext untuk melampirkan konteks aliran ke aliran file, atau untuk menghapus atau mengganti konteks aliran yang ada. Driver minifilter dapat melampirkan satu konteks per instans driver minifilter ke aliran file.

FltSetStreamContext tidak dapat dipanggil pada FileObject yang tidak dibuka. Oleh karena itu tidak dapat dipanggil dari panggilan balik pra-buat untuk aliran karena aliran belum dibuka pada saat itu. Namun, driver minifilter dapat mengalokasikan dan menyiapkan konteks aliran dalam panggilan balik pra-buat, meneruskannya ke panggilan balik pasca-buat menggunakan parameter konteks penyelesaian dan mengatur konteks aliran pada aliran di panggilan balik pasca-buat.

Penghitungan Referensi

Jika FltSetStreamContext berhasil:

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

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

Terlepas dari keberhasilannya:

Filter yang memanggil FltSetStreamContext 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 menentukan apakah konteks aliran didukung untuk file tertentu, panggil FltSupportsStreamContexts
Untuk mengalokasikan konteks baru, panggil FltAllocateContext.
Untuk mendapatkan konteks aliran, panggil FltGetStreamContext.
Untuk menghapus konteks aliran, panggil FltDeleteStreamContext 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 sistem operasi yang lebih baru.
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL