Fungsi FltSetFileContext (fltkernel.h)

Artikel
08/07/2023

Rutinitas FltSetFileContext menetapkan konteks untuk file.

Sintaks

NTSTATUS FLTAPI FltSetFileContext(
  [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

Pointer buram ke instans driver minifilter untuk pemanggil. Parameter ini diperlukan dan tidak boleh NULL.

[in] FileObject

Penunjuk ke objek file untuk file. Parameter ini diperlukan dan tidak boleh NULL.

[in] Operation

Bendera yang menentukan jenis operasi untuk dilakukan oleh FltSetFileContext . Parameter ini harus menjadi salah satu bendera berikut:

Bendera	Makna
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Jika konteks sudah diatur untuk file yang dituju parameter FileObject , FltSetFileContext akan mengganti konteks tersebut dengan konteks yang ditentukan dalam NewContext. Jika tidak, ini akan menyisipkan NewContext ke dalam daftar konteks untuk file.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Jika konteks sudah diatur untuk file yang ditunjuk oleh FileObject , FltSetFileContext akan mengembalikan STATUS_FLT_CONTEXT_ALREADY_DEFINED, dan tidak akan mengganti konteks yang ada atau menambah jumlah referensi. Jika konteks belum ditetapkan, rutinitas akan menyisipkan konteks yang ditentukan di NewContext ke dalam daftar konteks untuk file dan menaikkan jumlah referensi.

[in] NewContext

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

[out] OldContext

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

Nilai kembali

Rutinitas FltSetFileContext 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 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 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.
STATUS_NOT_SUPPORTED	Konteks file tidak didukung untuk file ini. Ini adalah kode kesalahan.

Keterangan

Untuk informasi selengkapnya tentang konteks, lihat Tentang konteks minifilter.

Driver minifilter memanggil FltSetFileContext untuk mengatur atau mengganti konteks filenya sendiri pada file. Driver minifilter hanya dapat melampirkan satu konteks per instans driver minifilter ke file.

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

Penghitungan Referensi

Jika FltSetFileContext berhasil:

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

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

Terlepas dari keberhasilannya:

Filter yang memanggil FltSetFileContext 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 file, panggil FltGetFileContext.
Untuk menghapus konteks file, panggil FltDeleteFileContext atau FltDeleteContext.
Untuk menentukan apakah konteks file didukung untuk file tertentu, panggil FltSupportsFileContexts atau FltSupportsFileContextsEx.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia dan didukung dimulai dengan Windows Vista.
Target Platform	Universal
Header	fltkernel.h (termasuk Fltkernel.h)
Pustaka	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL