Fungsi FltCreateNamedPipeFile (fltkernel.h)
Driver minifilter memanggil FltCreateNamedPipeFile untuk membuat pipa baru atau membuka pipa yang ada.
Sintaks
NTSTATUS FLTAPI FltCreateNamedPipeFile(
[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 ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] ULONG NamedPipeType,
[in] ULONG ReadMode,
[in] ULONG CompletionMode,
[in] ULONG MaximumInstances,
ULONG InboundQuota,
ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout,
[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 pipa bernama. 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
Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel file jika panggilan ke FltCreateNamedPipeFile berhasil.
[out, optional] FileObject
Penunjuk ke variabel yang dialokasikan penelepon yang menerima penunjuk objek file jika panggilan ke FltCreateNamedPipeFile 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 pipa 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 pipa bernama dapat dibaca. |
| FILE_WRITE_DATA | Data dapat ditulis ke pipa bernama. |
| FILE_WRITE_ATTRIBUTES | Bendera FileAttributes dapat ditulis. |
| FILE_APPEND_DATA | Data dapat ditambahkan ke file. |
| WRITE_DAC | Daftar kontrol akses diskresi (DACL) yang terkait dengan pipa bernama dapat ditulis. |
| WRITE_OWNER | Informasi kepemilikan yang terkait dengan pipa bernama dapat ditulis. |
| ACCESS_SYSTEM_SECURITY | Pemanggil akan memiliki akses tulis ke SACL pipa bernama |
| 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
Penunjuk ke struktur OBJECT_ATTRIBUTES buram yang sudah diinisialisasi dengan InitializeObjectAttributes. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa null. Jika tidak, penelepon harus mengatur atribut OBJ_KERNEL_HANDLE dalam panggilan ke InitializeObjectAttributes. Anggota struktur ini untuk objek file tercantum dalam tabel berikut.
| Anggota | Nilai |
|---|---|
| PanjangULONG | Jumlah byte data yang terkandung dalam struktur yang ditujukkan oleh ObjectAttributes. Nilai ini harus setidaknya ukuranof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Penunjuk ke struktur UNICODE_STRING yang berisi nama pipa 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\NamedPipe\mypipe" atau "\?? \pipe\mypipe" 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 oleh panggilan sebelumnya ke FltCreateFileEx2. Jika nilai ini NULL, anggota ObjectNameharus menjadi spesifikasi file yang sepenuhnya memenuhi syarat yang menyertakan jalur lengkap ke pipa target. Jika nilai ini bukan NULL, anggota ObjectName menentukan nama pipa yang relatif terhadap direktori ini. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Pendeskripsi keamanan opsional (SECURITY_DESCRIPTOR) yang akan diterapkan ke pipa. ACL yang ditentukan oleh deskriptor keamanan seperti itu hanya diterapkan ke pipa saat dibuat. Jika nilainya ADALAH NULL saat pipa dibuat, ACL yang ditempatkan pada pipa bergantung pada sistem file pipa bernama dan dapat memungkinkan klien dengan akses apa pun untuk membuat instans. |
| AtributULONG | Sekumpulan bendera yang mengontrol atribut objek file. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa nol. Jika tidak, penelepon 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
Penunjuk ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Saat kembali dari FltCreateNamedPipeFile, anggota Informasi variabel berisi salah satu nilai berikut:
FILE_CREATED
FILE_OPENED
[in] ShareAccess
Jenis akses berbagi ke file yang diperlukan pemanggil sebagai salah satu atau kombinasi bendera berikut. Untuk peluang terbesar menghindari kesalahan pelanggaran berbagi, tentukan semua bendera akses berbagi berikut.
| Bendera ShareAccess | Makna |
|---|---|
| FILE_SHARE_READ | File dapat dibuka untuk akses baca oleh panggilan utas lain ke FltCreateNamedPipeFile. |
| FILE_SHARE_WRITE | File dapat dibuka untuk akses tulis oleh panggilan utas lain ke FltCreateNamedPipeFile. |
[in] CreateDisposition
Nilai yang menentukan tindakan yang akan diambil, tergantung pada apakah file sudah ada. Nilainya bisa salah satu dari yang dijelaskan dalam tabel berikut.
| Nilai CreateDisposition | Makna |
|---|---|
| FILE_CREATE | Jika file sudah ada, gagalkan permintaan dan jangan membuat atau membuka file yang ditentukan. Jika tidak, buat file. |
| FILE_OPEN | Jika file sudah ada, buka alih-alih membuat file baru. Jika tidak, gagalkan permintaan dan jangan buat file baru. |
| FILE_OPEN_IF | Jika file sudah ada, buka file tersebut. Jika tidak, buat file. |
[in] CreateOptions
Opsi yang akan diterapkan saat membuat atau membuka pipa, sebagai kombinasi bendera berikut yang kompatibel.
| Bendera CreateOptions | Makna |
|---|---|
| FILE_WRITE_THROUGH | Layanan sistem, sistem pipa, dan driver yang menulis data ke pipa harus benar-benar mentransfer data ke dalam pipa 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 pipa dilakukan secara sinkron. Setiap penantian atas nama penelepon tunduk pada penghentian dini dari pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi pipa. 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 pipa dilakukan secara sinkron. Menunggu di 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] NamedPipeType
Jenis pipa bernama untuk dibuat. Dapat berupa salah satu dari nilai berikut:
[in] ReadMode
Mode untuk membaca dari pipa.
[in] CompletionMode
Mode penyelesaian untuk pembacaan dan penulisan pipa.
| Nilai | Makna |
|---|---|
|
Permintaan baca dan tulis pipa diantrekan dan dapat diblokir hingga selesai. |
|
Permintaan baca dan tulis pipa segera diselesaikan. |
[in] MaximumInstances
Jumlah maksimum instans yang diizinkan untuk pipa bernama ini.
InboundQuota
Jumlah byte yang akan dicadangkan untuk buffer input.
OutboundQuota
Jumlah byte yang akan dicadangkan untuk buffer output.
[in, optional] DefaultTimeout
Batas waktu default dalam kenaikan 100 nanodetik. Nilai ini dinyatakan sebagai bilangan bulat negatif. Misalnya, 250 milidetik ditentukan sebagai –10 * 1000 * 250.
[in, optional] DriverContext
Penunjuk opsional ke struktur IO_DRIVER_CREATE_CONTEXT yang sudah diinisialisasi oleh IoInitializeDriverCreateContext.
Nilai kembali
FltCreateNamedPipeFile mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini.
| Menampilkan kode | Deskripsi |
|---|---|
|
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. |
|
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 FltCreateNamedPipeFile memungkinkan driver minifilter untuk membuat atau membuka instans pipa. Ini berguna untuk membuat pipa virtual atau untuk membuat serikat pipa untuk multipleks I/O.
Parameter instans adalah NULL atau sebelumnya diatur dengan melampirkan ke volume pipa bernama. Penunjuk volume diperoleh dengan meneruskan "\Device\NamedPipe" sebagai nama volume ke FltGetVolumeFromName.
Untuk menentukan parameter pembuatan ekstra (ECP) sebagai bagian dari operasi pembuatan, inisialisasi anggota ExtraCreateParameter dari struktur IO_DRIVER_CREATE_CONTEXT dengan rutinitas FltAllocateExtraCreateParameterList . Jika ECP digunakan, EKP harus dialokasikan, diinisialisasi, dan dibebaskan menggunakan rutinitas dukungan terkait. Setelah kembali dari panggilan FltCreateNamedPipeFile, daftar ECP tidak berubah dan dapat diteruskan ke panggilan tambahan FltCreateNamedPipeFile untuk operasi pembuatan lainnya. Struktur daftar ECP tidak secara otomatis dibatalkan alokasinya. Pemanggil FltCreateNamedPipeFile harus membatalkan alokasi struktur ini dengan memanggil rutinitas FltFreeExtraCreateParameterList .
Jika Instans bukan NULL, permintaan buat dari FltCreateNamedPipeFile hanya dikirim ke instans yang terpasang di bawah instans driver minifilter yang ditentukan dan ke sistem file pipa bernama. 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 pipa bernama.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia di Windows 8. |
| Target Platform | Universal |
| Header | fltkernel.h (termasuk FltKernel.h) |
| Pustaka | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Lihat juga
FltAllocateExtraCreateParameterList