Fungsi FltCreateSectionForDataScan (fltkernel.h)
Rutinitas FltCreateSectionForDataScan membuat objek bagian untuk file. Manajer filter dapat secara opsional menyinkronkan I/O dengan bagian yang dibuat.
Sintaks
NTSTATUS FLTAPI FltCreateSectionForDataScan(
[in] PFLT_INSTANCE Instance,
[in] PFILE_OBJECT FileObject,
[in] PFLT_CONTEXT SectionContext,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PLARGE_INTEGER MaximumSize,
[in] ULONG SectionPageProtection,
[in] ULONG AllocationAttributes,
[in] ULONG Flags,
[out] PHANDLE SectionHandle,
[out] PVOID *SectionObject,
[out, optional] PLARGE_INTEGER SectionFileSize
);
Parameter
[in] Instance
Penunjuk instans buram untuk instans driver minifilter yang konteksnya akan diambil.
[in] FileObject
Objek file untuk file yang terbuka. Objek bagian akan didukung oleh file yang ditentukan. Parameter ini diperlukan dan tidak boleh NULL.
[in] SectionContext
Penunjuk ke konteks bagian yang dialokasikan sebelumnya.
[in] DesiredAccess
Jenis akses untuk objek bagian sebagai satu atau beberapa bendera ACCESS_MASK berikut.
| Bendera | Memperbolehkan penelepon untuk |
|---|---|
| SECTION_MAP_READ | Baca tampilan bagian. |
| SECTION_MAP_WRITE | Tulis tampilan bagian . |
| SECTION_QUERY | Kueri objek bagian untuk informasi tentang bagian tersebut. Driver harus mengatur bendera ini. |
| SECTION_ALL_ACCESS | Semua tindakan yang ditentukan oleh bendera sebelumnya serta yang ditentukan oleh STANDARD_RIGHTS_REQUIRED. Untuk informasi selengkapnya tentang STANDARD_RIGHTS_REQUIRED, lihat ACCESS_MASK. |
[in, optional] ObjectAttributes
Penunjuk ke struktur OBJECT_ATTRIBUTES opsional yang menentukan nama objek dan atribut lainnya. Gunakan makro InitializeObjectAttributes untuk menginisialisasi struktur ini.
[in, optional] MaximumSize
Parameter ini dicadangkan untuk digunakan di masa mendatang.
[in] SectionPageProtection
Perlindungan untuk ditempatkan pada setiap halaman di bagian . Tentukan salah satu nilai berikut ini. Parameter ini diperlukan dan tidak boleh nol.
| Bendera | Makna |
|---|---|
| PAGE_READONLY | Mengaktifkan akses baca-saja ke wilayah halaman yang diterapkan. Upaya untuk menulis ke wilayah yang berkomitmen menghasilkan pelanggaran akses. Jika sistem membedakan antara akses baca-saja dan menjalankan akses, upaya untuk menjalankan kode di wilayah yang dilakukan menghasilkan pelanggaran akses. |
| PAGE_READWRITE | Memungkinkan akses baca dan tulis ke wilayah halaman yang berkomitmen. |
[in] AllocationAttributes
Bitmasks dari bendera SEC_XXX menentukan atribut alokasi bagian. Tentukan satu atau beberapa nilai berikut ini. Parameter ini diperlukan dan tidak boleh nol.
| Bendera | Makna |
|---|---|
| SEC_COMMIT | Mengalokasikan penyimpanan fisik dalam memori atau dalam file halaman pada disk untuk semua halaman bagian. Ini adalah pengaturan default. Perhatikan bahwa bendera ini diperlukan dan tidak dapat dihilangkan. |
| SEC_FILE | File yang ditentukan oleh parameter FileObject adalah file yang dipetakan. |
[in] Flags
Parameter ini dicadangkan untuk digunakan di masa mendatang.
[out] SectionHandle
Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel buram ke bagian . Secara default, handel bagian adalah handel pengguna. Jika penelepon memerlukan handel kernel, mereka harus meneruskan penunjuk ke struktur OBJECT_ATTRIBUTES yang diinisialisasi dalam parameter ObjectAttributes dengan set bendera OBJ_KERNEL_HANDLE.
[out] SectionObject
Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk buram ke objek bagian.
[out, optional] SectionFileSize
Penunjuk ke variabel yang dialokasikan penelepon yang menerima ukuran, dalam byte, file pada saat objek bagian dibuat. Parameter ini bersifat opsional dan dapat berupa NULL.
Nilai kembali
FltCreateSectionForDataScan mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai, seperti salah satu hal berikut ini.
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_END_OF_FILE | Ukuran file yang ditentukan oleh parameter FileObject adalah nol. |
| STATUS_FILE_LOCK_CONFLICT | File yang ditentukan oleh parameter FileObject dikunci. |
| STATUS_INSUFFICIENT_RESOURCES | FltCreateSectionForDataScan mengalami kegagalan alokasi kumpulan. |
| STATUS_INVALID_FILE_FOR_SECTION | File yang ditentukan oleh parameter FileObject tidak mendukung bagian. |
| STATUS_INVALID_PARAMETER | Minifilter tidak terdaftar. |
| STATUS_INVALID_PARAMETER_8 | Nilai yang ditentukan untuk parameter SectionPageProtection tidak valid. |
| STATUS_INVALID_PARAMETER_9 | Pemanggil menentukan nilai yang tidak valid untuk parameter AllocationAttributes . |
| STATUS_NOT_SUPPORTED | Volume yang dilampirkan ke instans ini tidak mendukung konteks bagian. |
| STATUS_PRIVILEGE_NOT_HELD | Pemanggil tidak memiliki hak istimewa yang diperlukan untuk membuat objek bagian dengan akses yang ditentukan dalam parameter DesiredAccess . |
| STATUS_FILE_IS_A_DIRECTORY | File yang ditentukan oleh parameter FileObject adalah direktori. |
| STATUS_FLT_CONTEXT_ALREADY_DEFINED | Instans filter yang ditentukan oleh Instans sudah memiliki bagian terbuka untuk aliran. Hanya satu bagian per aliran, dan oleh karena itu, per instans didukung. |
Keterangan
Sebelum memanggil FltCreateSectionForDataScan, minifilter harus terlebih dahulu mendaftarkan volumenya untuk pemindaian data dengan memanggil FltRegisterForDataScan. Seperti halnya elemen konteks filter lainnya, SectionContext pertama kali dialokasikan dengan FltAllocateContext.
FltCreateSectionForDataScan menyisipkan handel ke objek (SectionHandle) ke dalam tabel handel proses untuk utas yang dipanggil FltCreateSectionForDataScan .
Handel dapat berupa handel pengguna atau handel kernel. Handel yang dibuat dengan OBJ_KERNEL_HANDLE diatur dalam struktur OBJECT_ATTRIBUTES yang ditunjuk objectAttributes adalah handel kernel, dan hanya dapat diakses dari mode kernel. Handel yang dibuat tanpa bendera OBJ_KERNEL_HANDLE adalah handel pengguna, yang dapat diakses dari mode pengguna atau kernel. Filter dapat membuat handel pengguna lalu meneruskannya ke aplikasi mode pengguna untuk diproses. Misalnya, mesin pemindaian virus dapat hidup dalam aplikasi mode pengguna dan diberi makan handel pengguna dari filter sistem file.
Situasi tertentu dapat terjadi di mana menahan pembukaan bagian tidak kompatibel dengan I/O file saat ini. Secara khusus, I/O file yang memicu penghapusan menyeluruh cache dapat menyebabkan ketidakcocokan cache jika penghapusan menyeluruh cache dicegah karena bagian terbuka. Minifilter dapat menyediakan rutinitas panggilan balik opsional untuk pemberitahuan peristiwa ini. Driver minifilter mengimplementasikan PFLT_SECTION_CONFLICT_NOTIFICATION_CALLBACK untuk menerima pemberitahuan ini. Pemberitahuan konflik diaktifkan jika anggota SectionNotificationCallbackFLT_REGISTRATION diatur ke rutinitas panggilan balik ini saat minifilter terdaftar. Saat pemberitahuan diterima, bagian dapat ditutup untuk memungkinkan operasi I/O yang bertentangan berlanjut.
Catatan
Panggilan balik pemberitahuan bagian mungkin terjadi sebelum FltCreateSectionForDataScan kembali. Minifilter harus dapat menerima panggilan balik dan menangani kasus di mana SectionHandle dan SectionObject belum valid.
Ketika objek bagian yang dibuat oleh rutinitas ini tidak lagi diperlukan, pastikan untuk menutup handel objek bagian (SectionHandle) dengan memanggil rutinitas ZwClose dan dereferensi objek bagian itu sendiri (SectionObject) dengan memanggil rutinitas ObDereferenceObject .
Untuk informasi gambaran umum tentang membuat bagian dan tampilan memori yang dipetakan, lihat Objek dan Tampilan Bagian. Lihat juga dokumentasi untuk rutinitas CreateFileMapping di Microsoft Windows SDK.
Penting
Minifilter tidak boleh secara eksplisit menghapus konteks bagian yang diteruskan ke FltCreateSectionForDataScan. Jangan panggil FltDeleteContext setelah konteks bagian diteruskan ke FltCreateSectionForDataScan. Konteks bagian dibatalkan alokasinya dan dihapus dari aliran dengan memanggil FltCloseSectionForDataScan dalam kasus ini.
Secara umum, bagian harus dibuat sebagai baca-saja. Secara khusus, jika file baca-saja berada dalam transaksi dan minifilter tidak membuat bagian baca-saja, tulis ke bagian tersebut dibuang dan tidak disertakan sebagai bagian dari transaksi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8 |
| Target Platform | Universal |
| Header | fltkernel.h (termasuk Fltkernel.h) |
| Pustaka | FltMgr.lib |
| IRQL | <= APC_LEVEL |