Fungsi FltSetStreamHandleContext (fltkernel.h)
Rutinitas FltSetStreamHandleContext mengatur konteks untuk handel streaming.
Sintaks
NTSTATUS FLTAPI FltSetStreamHandleContext(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] FLT_SET_CONTEXT_OPERATION Operation,
[in] PFLT_CONTEXT NewContext,
[out, optional] PFLT_CONTEXT *OldContext
);
Parameter
[in] Instance
Penunjuk instans buram untuk instans driver minifilter yang konteksnya akan dimasukkan, dihapus, atau diganti dalam daftar konteks yang dilampirkan ke handel aliran.
[in] FileObject
Penunjuk ke objek file untuk aliran file. Parameter ini diperlukan dan tidak boleh NULL.
[in] Operation
Bendera yang menentukan detail operasi yang akan dilakukan. Parameter ini harus salah satu dari berikut ini:
| Nilai | Makna |
|---|---|
| FLT_SET_CONTEXT_REPLACE_IF_EXISTS | Jika konteks sudah diatur untuk Instans ini, FltSetStreamHandleContext akan menggantinya dengan konteks yang ditentukan dalam NewContext. Jika tidak, ini akan memasukkan NewContext ke dalam daftar konteks untuk handel aliran. |
| FLT_SET_CONTEXT_KEEP_IF_EXISTS | Jika konteks sudah diatur untuk Instans ini, FltSetStreamHandleContext 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 handel aliran dan menaikkan jumlah referensi. |
[in] NewContext
Penunjuk ke konteks baru yang akan diatur untuk handel aliran. Parameter ini diperlukan dan tidak boleh NULL.
[out, optional] OldContext
Penunjuk ke variabel yang dialokasikan pemanggil yang menerima alamat konteks handel 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.
Nilai kembali
Rutinitas FltSetStreamHandleContext mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu kode kesalahan berikut:
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Jika FLT_SET_CONTEXT_KEEP_IF_EXISTS ditentukan untuk Operasi, kode kesalahan ini menunjukkan bahwa konteks sudah dilampirkan ke handel aliran. |
| STATUS_FLT_CONTEXT_ALREADY_LINKED | Konteks yang dituju 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 sedang dikoyak. Ini adalah kode kesalahan. |
| STATUS_INVALID_PARAMETER | Parameter yang tidak valid telah diteruskan. Misalnya, parameter NewContext tidak menunjuk ke konteks handel aliran yang valid, atau nilai yang tidak valid ditentukan untuk Operasi. |
| STATUS_NOT_SUPPORTED | Terjadi situasi yang tidak didukung, seperti sistem file tidak mendukung konteks per aliran untuk aliran file ini, atau pemanggil menyediakan FileObject NULL. |
Keterangan
Untuk informasi selengkapnya tentang konteks, lihat Tentang konteks minifilter.
Rutinitas FltSetStreamHandleContext menambahkan, menghapus, atau mengganti konteks untuk instans driver minifilter pada handel aliran. Driver minifilter dapat melampirkan satu konteks per instans driver minifilter ke handel aliran.
FltSetStreamHandleContext tidak dapat dipanggil pada FileObject yang tidak dibuka. Oleh karena itu FltSetStreamHandleContext tidak dapat dipanggil dari panggilan balik pra-buat untuk aliran karena aliran belum dibuka pada saat itu. Namun, minifilter dapat mengalokasikan dan menyiapkan konteks handel aliran dalam panggilan balik pra-buat, meneruskannya ke panggilan balik pasca-buat menggunakan parameter konteks penyelesaian dan mengatur konteks handel aliran pada aliran di panggilan balik pasca-buat.
Penghitungan Referensi
Jika FltSetStreamHandleContext berhasil:
- Jumlah referensi pada NewContext bertahap. Ketika NewContext tidak lagi diperlukan, minifilter harus memanggil FltReleaseContext untuk mengurangi jumlah referensinya.
Jika tidak, jika FltSetStreamHandleContext 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 handel aliran. Filter yang memanggil FltSetStreamHandleContext harus memanggil FltReleaseContext untuk OldContext juga ketika penunjuk konteks tidak lagi diperlukan.
Terlepas dari keberhasilannya:
- Filter yang memanggil FltSetStreamHandleContext 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 penanganan aliran didukung untuk file tertentu, panggil FltSupportsStreamHandleContexts
Untuk mengalokasikan konteks baru, panggil FltAllocateContext.
Untuk mendapatkan konteks handel aliran, panggil FltGetStreamHandleContext.
Untuk menghapus konteks handel aliran, panggil FltDeleteStreamHandleContext 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 |