Fungsi FltCreateMailslotFile (fltkernel.h)

Artikel
08/07/2023

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