Fungsi FltCreateMailslotFile (fltkernel.h)
Driver minifilter memanggil FltCreateMailslotFile untuk membuat pipa baru atau membuka mailslot yang ada.
Sintaks
NTSTATUS FLTAPI FltCreateMailslotFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[in] ULONG DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Parameter
[in] Filter
Penunjuk filter buram untuk pemanggil.
[in, optional] Instance
Penunjuk instans buram untuk instans driver minifilter tempat permintaan pembuatan akan dikirim. Instans harus dilampirkan ke volume untuk sistem file mailslot. Parameter ini bersifat opsional dan dapat berupa NULL. Jika parameter ini NULL, permintaan dikirim ke objek perangkat di bagian atas tumpukan driver sistem file untuk volume. Jika bukan NULL, permintaan hanya dikirim ke instans driver minifilter yang dilampirkan di bawah instans yang ditentukan.
[out] FileHandle
Pointer ke variabel yang dialokasikan penelepon yang menerima handel file jika panggilan ke FltCreateMailslotFile berhasil.
[out, optional] FileObject
Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk objek file jika panggilan ke FltCreateMailslotFile berhasil. Parameter ini bersifat opsional dan dapat berupa NULL.
[in] DesiredAccess
Bitmask bendera yang menentukan jenis akses yang diperlukan pemanggil ke file atau direktori. Kumpulan bendera DesiredAccess yang ditentukan sistem menentukan hak akses khusus berikut untuk objek file.
| Bendera DesiredAccess | Makna |
|---|---|
| FILE_READ_DATA | Data dapat dibaca dari mailslot bernama. |
| FILE_READ_ATTRIBUTES | Bendera FileAttributes dapat dibaca. Untuk informasi tambahan, lihat tabel nilai bendera yang valid di parameter FileAttributesdari FltCreateFileEx2. |
| READ_CONTROL | Daftar kontrol akses ACL dan informasi kepemilikan yang terkait dengan mailslot dapat dibaca. |
| FILE_WRITE_DATA | Data dapat ditulis ke mailslot. |
| FILE_WRITE_ATTRIBUTES | Bendera FileAttributes dapat ditulis. |
| FILE_APPEND_DATA | Data dapat ditambahkan ke mailslot. |
| WRITE_DAC | DACL daftar kontrol akses diskresi yang terkait dengan mailslot dapat ditulis. |
| WRITE_OWNER | Informasi kepemilikan yang terkait dengan mailslot dapat ditulis. |
| ACCESS_SYSTEM_SECURITY | Pemanggil akan memiliki akses tulis ke SACL mailslot. |
| MENSINKRONISASI | Pemanggil dapat menyinkronkan penyelesaian operasi I/O dengan menunggu FileHandle yang dikembalikan diatur ke status Sinyal. Bendera ini harus diatur jika bendera CreateOptions FILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT diatur. |
Atau, untuk objek file apa pun yang tidak mewakili direktori, Anda dapat menentukan satu atau beberapa bendera ACCESS_MASK generik berikut. (Bendera STANDARD_RIGHTS_XXX adalah nilai sistem yang telah ditentukan sebelumnya yang digunakan untuk menegakkan keamanan pada objek sistem.) Anda juga dapat menggabungkan bendera generik ini dengan bendera tambahan dari tabel sebelumnya.
| DesiredAccess ke Nilai File | Peta ke Bendera DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA, dan SINKRONKAN. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA, dan SINKRONKAN. |
[in] ObjectAttributes
Pointer ke struktur OBJECT_ATTRIBUTES buram yang sudah diinisialisasi dengan InitializeObjectAttributes. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa NULL. Jika tidak, pemanggil harus mengatur atribut OBJ_KERNEL_HANDLE dalam panggilan ke InitializeObjectAttributes. Anggota struktur ini untuk objek file tercantum dalam tabel berikut.
| Anggota | Nilai |
|---|---|
| Panjang ULONG | Jumlah byte data yang terkandung dalam struktur yang ditujukkan oleh ObjectAttributes. Nilai ini setidaknya harus sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Penunjuk ke struktur UNICODE_STRING yang berisi nama mailslot yang akan dibuat atau dibuka. Nama ini harus merupakan spesifikasi file yang sepenuhnya memenuhi syarat atau nama objek perangkat kecuali itu adalah nama file yang relatif terhadap direktori yang ditentukan oleh RootDirectory. Misalnya, "\Device\Mailslot\myslot" atau "?? \mailslot\myslot" bisa berupa spesifikasi file yang valid. (Catatan: "??" menggantikan "\DosDevices" sebagai nama namespace objek Win32. "\DosDevices" masih berfungsi, tetapi "??" diterjemahkan lebih cepat oleh manajer objek. |
| HANDLE RootDirectory | Handel opsional ke direktori, diperoleh dengan panggilan sebelumnya ke FltCreateFileEx2. Jika nilai ini NULL, anggota ObjectName harus merupakan spesifikasi file yang sepenuhnya memenuhi syarat yang menyertakan jalur lengkap ke mailslot target. Jika nilai ini bukan NULL, anggota ObjectName menentukan nama mailslot yang relatif terhadap direktori ini. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | SECURITY_DESCRIPTOR opsional untuk diterapkan ke mailslot. ACL yang ditentukan oleh deskriptor keamanan seperti itu hanya diterapkan ke mailslot saat dibuat. Jika nilainya NULL saat mailslot dibuat, ACL yang ditempatkan pada mailslot bergantung pada sistem file mailslot dan dapat memungkinkan klien dengan akses apa pun untuk membuat instans. |
| Atribut ULONG | Sekumpulan bendera yang mengontrol atribut objek file. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa nol. Jika tidak, pemanggil harus mengatur bendera OBJ_KERNEL_HANDLE. Pemanggil juga dapat secara opsional mengatur bendera OBJ_CASE_INSENSITIVE, yang menunjukkan bahwa kode pencarian nama harus mengabaikan kasus ObjectName daripada melakukan pencarian yang sama persis. |
[out] IoStatusBlock
Arahkan ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Saat kembali dari FltCreateMailslotFile, anggota Informasi variabel berisi salah satu nilai berikut:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Opsi yang akan diterapkan saat membuat atau membuka mailslot, sebagai kombinasi bendera berikut yang kompatibel.
| Bendera | Makna |
|---|---|
| FILE_WRITE_THROUGH | Layanan sistem, sistem file, dan driver yang menulis data ke mailslot harus benar-benar mentransfer data ke dalam mailslot sebelum operasi tulis yang diminta dianggap selesai. Bendera ini secara otomatis diatur jika bendera CreateOptions FILE_NO_INTERMEDIATE_BUFFERING diatur. |
| FILE_SYNCHRONOUS_IO_ALERT | Semua operasi pada mailslot dilakukan secara sinkron. Setiap tunggu atas nama pemanggil tunduk pada penghentian dini dari pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi mailslot. Jika bendera ini diatur, bendera DesiredAccess SYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi. |
| FILE_SYNCHRONOUS_IO_NONALERT | Semua operasi pada mailslot dilakukan secara sinkron. Menunggu dalam sistem untuk menyinkronkan antrean I/O dan penyelesaian tidak tunduk pada pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi file. Jika bendera ini diatur, bendera DesiredAccess SYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi. |
[in] MailslotQuota
Ukuran, dalam byte, dari buffer untuk menulis ke mailslot.
[in] MaximumMessageSize
Ukuran maksimum, dalam byte, dari pesan untuk ditulis ke mailslot. Pesan dengan ukuran apa pun ditentukan oleh nilai 0.
[in] ReadTimeout
Waktu operasi baca menunggu pesan tersedia di mailslot. Batas waktu default dinyatakan dalam kenaikan 100 nanodetik sebagai bilangan bulat negatif. Misalnya, 250 milidetik ditentukan sebagai –10*1000*250. Selain itu, nilai berikut memiliki arti khusus.
| Nilai | Makna |
|---|---|
| 0 | Segera kembali jika tidak ada pesan yang ada. |
| -1 | Menunggu selamanya untuk pesan. |
[in, optional] DriverContext
Penunjuk opsional ke struktur IO_DRIVER_CREATE_CONTEXT yang sudah diinisialisasi oleh IoInitializeDriverCreateContext.
Mengembalikan nilai
FltCreateMailslotFile mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini.
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Filter atau instans yang ditentukan dalam parameter Filter atau Instans sedang ditumbangkan. Kode status ini dapat diterima jika permintaan terbuka melewati titik pemasangan volume dan parameter Instans bukan NULL. Ini adalah kode kesalahan. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | Parameter ObjectAttributes tidak berisi anggota RootDirectory , tetapi anggota ObjectName dalam struktur OBJECT_ATTRIBUTES adalah string kosong atau tidak berisi karakter OBJECT_NAME_PATH_SEPARATOR. Kode kesalahan ini menunjukkan sintaks yang salah untuk jalur objek. |
Keterangan
Fungsi FltCreateMailslotFile memungkinkan driver minifilter untuk membuat atau membuka instans mailslot. Ini berguna untuk membuat mailslots virtual atau untuk membuat grup mailslot yang mendistribusikan ke beberapa mailslots lainnya.
Parameter Instans adalah NULL atau sebelumnya diatur dengan melampirkan ke volume mailslot. Penunjuk volume diperoleh dengan meneruskan "\Device\Mailslot" sebagai nama volume ke FltGetVolumeFromName.
Untuk menentukan parameter buat ekstra (ECP) sebagai bagian dari operasi buat, inisialisasi anggota ExtraCreateParameter dari struktur IO_DRIVER_CREATE_CONTEXT dengan rutinitas FltAllocateExtraCreateParameterList . Jika ECP digunakan, ECP harus dialokasikan, diinisialisasi, dan dibebaskan menggunakan rutinitas dukungan terkait. Setelah kembali dari panggilan FltCreateMailslotFile, daftar ECP tidak berubah dan dapat diteruskan ke panggilan tambahan FltCreateMailslotFile untuk operasi pembuatan lainnya. Struktur daftar ECP tidak secara otomatis dibatalkan alokasinya. Penelepon FltCreateMailslotFile harus membatalkan alokasi struktur ini dengan memanggil rutinitas FltFreeExtraCreateParameterList .
Jika Instans bukan NULL, permintaan buat dari FltCreateMailslotFile hanya dikirim ke instans yang dilampirkan di bawah instans driver minifilter yang ditentukan dan ke sistem file mailslot. Instans yang ditentukan dan instans yang terpasang di atasnya tidak menerima permintaan buat. Jika tidak ada instans yang ditentukan, permintaan masuk ke bagian atas tumpukan dan diterima oleh semua instans dan sistem file mailslot.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia dalam Windows 8. |
| Target Platform | Universal |
| Header | fltkernel.h (termasuk FltKernel.h) |
| Pustaka | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Lihat juga
FltAllocateExtraCreateParameterList