Fungsi NtCreateNamedPipeFile
Membuat dan membuka handel ujung server dari instans pertama dari pipa bernama tertentu atau instans lain dari pipa bernama yang ada. Fungsi mengembalikan handel yang dapat digunakan untuk mengakses pipa.
Sintaks
NTSTATUS NtCreateNamedPipeFile(
[out] PHANDLE FileHandle,
[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,
[in] ULONG InboundQuota,
[in] ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout
);
Parameter
FileHandle [out]
Penunjuk ke variabel yang menerima handel file jika panggilan berhasil.
DesiredAccess [in]
Bitmask bendera yang menentukan jenis akses ke file atau direktori yang diperlukan pemanggil. Kumpulan bendera DesiredAccess yang ditentukan sistem ini menentukan hak akses khusus berikut untuk objek file.
| Bendera | Deskripsi |
|---|---|
| DELETE | File dapat dihapus. |
| FILE_READ_DATA | Data dapat dibaca dari file . |
| FILE_READ_ATTRIBUTES | Bendera FileAttributes, yang dijelaskan di bawah ini, dapat dibaca. |
| FILE_READ_EA | Atribut yang diperluas (EA) yang terkait dengan file dapat dibaca. |
| READ_CONTROL | Daftar kontrol akses (ACL) dan informasi kepemilikan yang terkait dengan file dapat dibaca. |
| FILE_WRITE_DATA | Data dapat ditulis ke file. |
| FILE_WRITE_ATTRIBUTES | Bendera FileAttributes dapat ditulis. |
| FILE_WRITE_EA | EA yang terkait dengan file dapat ditulis. |
| FILE_APPEND_DATA | Data dapat ditambahkan ke file. |
| WRITE_DAC | Daftar kontrol akses diskresi (DACL) yang terkait dengan file dapat ditulis. |
| WRITE_OWNER | Informasi kepemilikan yang terkait dengan file dapat ditulis. |
| MENSINKRONISASI | Pemanggil dapat menyinkronkan penyelesaian operasi I/O dengan menunggu FileHandle yang dikembalikan diatur ke status Sinyal. Bendera ini harus diatur jika CreateOptionsFILE_SYNCHRONOUS_IO_ALERT atau FILE_SYNCHRONOUS_IO_NONALERT bendera diatur. |
| FILE_EXECUTE | Data dapat dibaca ke dalam memori dari file menggunakan I/O halaman sistem. |
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.
| Akses yang diinginkan ke nilai file | Peta ke bendera DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SINKRONKAN. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SINKRONKAN. |
| GENERIC_EXECUTE | STANDARD_RIGHTS_EXECUTE, SINKRONKAN, FILE_READ_ATTRIBUTES, FILE_EXECUTE. |
Untuk direktori (FILE_DIRECTORY_FILEbendera CreateOptions diatur), Anda dapat menentukan satu atau beberapa bendera ACCESS_MASK berikut, yang juga dapat Anda gabungkan dengan bendera yang kompatibel yang dijelaskan sebelumnya.
| Akses yang diinginkan ke nilai direktori | Deskripsi |
|---|---|
| FILE_LIST_DIRECTORY | File dalam direktori dapat dicantumkan. |
| FILE_TRAVERSE | Direktori dapat dilalui; yaitu, dapat menjadi bagian dari nama jalur file. |
Bendera FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE, dan FILE_APPEND_DATADesiredAccess tidak kompatibel dengan pembuatan atau pembukaan file direktori.
ObjectAttributes [in]
Penunjuk ke struktur yang OBJECT_ATTRIBUTES sudah diinisialisasi oleh rutinitas InitializeObjectAttributes . Jika pemanggil berjalan dalam konteks proses sistem, parameter ini dapat berupa NULL. Jika tidak, penelepon harus mengatur OBJ_KERNEL_HANDLE atribut dalam panggilan ke InitializeObjectAttributes.
Anggota struktur ini untuk objek file meliputi yang berikut ini:
| Anggota | Nilai |
|---|---|
| Panjang ULONG | Jumlah byte dari data ObjectAttributes yang disediakan. Nilai ini harus setidaknya sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Penunjuk ke string Unicode buffer yang berisi nama file yang akan dibuat atau dibuka. Nilai ini harus merupakan spesifikasi file yang sepenuhnya memenuhi syarat, kecuali itu adalah nama file yang relatif terhadap direktori yang ditentukan oleh RootDirectory. Misalnya, "\Device\Floppy1\myfile.dat" atau "?? \B:\myfile.dat" bisa menjadi spesifikasi file yang sepenuhnya memenuhi syarat, selama driver disk drive floppy dan sistem file yang terlalu berlebihan sudah dimuat. (Catatan: "??" menggantikan "\DosDevices" sebagai nama namespace objek Win32. "\DosDevices" masih berfungsi, tetapi "??" diterjemahkan lebih cepat oleh manajer objek.) |
| HANDLE RootDirectory | Handel opsional ke direktori yang diperoleh oleh panggilan sebelumnya ke NtCreateNamedPipeFile. Jika nilai ini NULL, anggota ObjectName harus menjadi spesifikasi file yang sepenuhnya memenuhi syarat yang menyertakan jalur lengkap ke file target. Jika nilai ini bukan NULL, anggota ObjectName menentukan nama file yang relatif terhadap direktori ini. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Deskriptor keamanan opsional yang akan diterapkan ke file. ACL yang ditentukan oleh deskriptor keamanan seperti itu hanya diterapkan ke file saat dibuat. Jika nilainya ADALAH NULL saat file dibuat, ACL yang ditempatkan pada file bergantung pada sistem file; sebagian besar sistem file menyebarkan beberapa bagian dari ACL seperti itu dari file direktori induk yang dikombinasikan dengan ACL default pemanggil. |
| Atribut ULONG | Sekumpulan bendera yang mengontrol atribut objek file. Jika pemanggil berjalan dalam konteks proses sistem, parameter ini bisa nol. Jika tidak, penelepon harus mengatur OBJ_KERNEL_HANDLE bendera . Pemanggil juga dapat secara opsional mengatur OBJ_CASE_INSENSITIVE bendera, yang menunjukkan bahwa kode pencarian nama harus mengabaikan kasus ObjectName alih-alih melakukan pencarian yang sama persis. |
IoStatusBlock [out]
Penunjuk ke variabel jenis IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi tentang operasi yang diminta. Saat dikembalikan dari NtCreateNamedPipeFile, anggota Informasi variabel berisi salah satu nilai berikut:
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
ShareAccess [in]
Menentukan jenis akses berbagi ke file yang diinginkan pemanggil, sebagai nol, atau satu, atau kombinasi bendera berikut. Untuk meminta akses eksklusif, atur parameter ini ke nol. Untuk membantu Anda menghindari kesalahan berbagi pelanggaran, tentukan semua bendera akses berbagi berikut.
| Bendera ShareAccess | Deskripsi |
|---|---|
| FILE_SHARE_READ | File dapat dibuka untuk akses baca oleh panggilan pembuatan file utas lainnya. |
| FILE_SHARE_WRITE | File dapat dibuka untuk akses tulis oleh panggilan pembuatan file utas lainnya. |
| FILE_SHARE_DELETE | File dapat dibuka untuk akses penghapusan oleh panggilan pembuatan file utas lainnya. |
Driver perangkat dan driver perantara biasanya mengatur ShareAccess ke nol, yang memberi pemanggil akses eksklusif ke file terbuka.
CreateDisposition [in]
Nilai yang menentukan bagaimana file harus ditangani ketika file sudah ada. CreateDisposition dapat berupa salah satu hal berikut ini:
| Nilai | Deskripsi |
|---|---|
| FILE_SUPERSEDE | Jika file sudah ada, ganti dengan file yang diberikan. Jika tidak ada, buat file yang diberikan. |
| FILE_CREATE | Jika file sudah ada, gagalkan permintaan dan jangan membuat atau membuka file yang diberikan. Jika tidak ada, buat file yang diberikan. |
| FILE_OPEN | Jika file sudah ada, buka alih-alih membuat file baru. Jika tidak ada, gagalkan permintaan dan jangan buat file baru. |
| FILE_OPEN_IF | Jika file sudah ada, buka file tersebut. Jika tidak ada, buat file yang diberikan. |
| FILE_OVERWRITE | Jika file sudah ada, buka dan timpa. Jika tidak ada, gagalkan permintaan. |
| FILE_OVERWRITE_IF | Jika file sudah ada, buka dan timpa. Jika tidak ada, buat file yang diberikan. |
CreateOptions [in]
Menentukan opsi yang akan diterapkan saat membuat atau membuka file, sebagai kombinasi bendera berikut yang kompatibel.
| Bendera CreateOptions | Deskripsi |
|---|---|
| FILE_DIRECTORY_FILE (0x00000001) | File yang sedang dibuat atau dibuka adalah file direktori. Dengan bendera ini, parameter Disposisi harus diatur ke salah satu dari FILE_CREATE, , FILE_OPENatau FILE_OPEN_IF. Bendera CreateOptions yang kompatibel dengan bendera ini adalah sebagai berikut: FILE_SYNCHRONOUS_IO_ALERT, , FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGHFILE_OPEN_FOR_BACKUP_INTENT, dan FILE_OPEN_BY_FILE_ID. |
| FILE_WRITE_THROUGH (0x00000002) | Layanan sistem, sistem file, dan driver yang menulis data ke file harus benar-benar mentransfer data ke dalam file sebelum operasi tulis yang diminta dianggap selesai. |
| FILE_SEQUENTIAL_ONLY (0x00000004) | Semua akses ke file akan berurutan. |
| FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) | File tidak dapat di-cache atau di-buffer dalam buffer internal driver. Bendera ini tidak kompatibel dengan bendera DesiredAccessFILE_APPEND_DATA . |
| FILE_SYNCHRONOUS_IO_ALERT (0x00000010) | Semua operasi pada file dilakukan secara sinkron. Setiap tunggu atas nama pemanggil tunduk pada penghentian dini dari pemberitahuan. Bendera ini juga menyebabkan sistem I/O mempertahankan konteks posisi file. Jika bendera ini diatur, bendera DesiredAccessSYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi. |
| FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) | Semua operasi pada file 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 DesiredAccessSYNCHRONIZE juga harus diatur sehingga Manajer I/O menggunakan objek file sebagai objek sinkronisasi. |
| FILE_NON_DIRECTORY_FILE (0x00000040) | File yang sedang dibuka tidak boleh berupa file direktori atau panggilan ini gagal. Objek file yang sedang dibuka dapat mewakili file data; perangkat logis, virtual, atau fisik; atau volume. |
| FILE_CREATE_TREE_CONNECTION (0x00000080) | Buat koneksi pohon untuk file ini untuk membukanya melalui jaringan. |
| FILE_COMPLETE_IF_OPLOCKED (0x00000100) | Selesaikan operasi ini segera dengan kode keberhasilan alternatif jika file target di-oplock, daripada memblokir utas pemanggil. Jika file di-oplock, penelepon lain sudah memiliki akses ke file melalui jaringan. |
| FILE_NO_EA_KNOWLEDGE (0x00000200) | Jika atribut yang diperluas pada file yang ada dibuka menunjukkan bahwa pemanggil harus memahami atribut yang diperluas untuk menginterpretasikan file dengan benar, gagalkan permintaan ini karena pemanggil tidak memahami cara menangani atribut yang diperluas. |
| FILE_OPEN_REMOTE_INSTANCE (0x00000400) | Dicadangkan untuk penggunaan sistem; jangan gunakan. |
| FILE_RANDOM_ACCESS (0x00000800) | Akses ke file bisa acak, jadi tidak ada operasi read-ahead berurutan yang harus dilakukan pada file dengan sistem file atau sistem operasi. |
| FILE_DELETE_ON_CLOSE (0x00001000) | Hapus file ketika handel terakhir diteruskan ke FltClose. |
| FILE_OPEN_BY_FILE_ID (0x00002000) | File sedang dibuka oleh ID. Nama file berisi nama perangkat dan ID 64-bit yang akan digunakan untuk membuka file. |
| FILE_OPEN_FOR_BACKUP_INTENT (0x000004000) | File sedang dibuka untuk tujuan pencadangan; oleh karena itu, sistem harus memeriksa hak akses tertentu dan memberi pemanggil akses yang sesuai ke file sebelum memeriksa input DesiredAccess terhadap deskriptor keamanan file. |
| FILE_NO_COMPRESSION (0x00008000) | Menekan pewarisan FILE_ATTRIBUTE_COMPRESSED dari direktori induk. Ini memungkinkan pembuatan file yang tidak dikompresi dalam direktori yang ditandai terkompresi. |
| FILE_OPEN_REQUIRING_OPLOCK (0x00010000) | File sedang dibuka dan kunci oportunistik (oplock) pada file diminta sebagai operasi atom tunggal. Sistem file memeriksa oplock sebelum melakukan operasi pembuatan, dan operasi pembuatan akan gagal dengan kode STATUS_CANNOT_BREAK_OPLOCK pengembalian jika operasi pembuatan akan merusak oplock yang ada. Bendera ini tersedia di Windows 7, Windows Server 2008 R2 dan sistem operasi Windows yang lebih baru. |
| FILE_DISALLOW_EXCLUSIVE (0x00020000) | Saat membuka file yang ada, jika FILE_SHARE_READ tidak ditentukan dan pemeriksaan akses sistem file tidak akan memberikan akses tulis pemanggil ke file, gagal membuka ini dengan STATUS_ACCESS_DENIED. Ini adalah perilaku default sebelum Windows 7. |
| FILE_SESSION_AWARE (0x00040000) | File atau perangkat sedang dibuka dengan kesadaran sesi. Jika bendera ini tidak ditentukan, maka perangkat per sesi (seperti perangkat yang menggunakan Pengalihan USB RemoteFX) tidak dapat dibuka oleh proses yang berjalan di sesi 0. Bendera ini tidak berpengaruh bagi penelepon yang tidak berada di sesi 0. Bendera ini hanya didukung pada Windows edisi server. Bendera ini tidak didukung sebelum Windows Server 2012. |
| FILE_RESERVE_OPFILTER (0x00100000) | Bendera ini memungkinkan aplikasi untuk meminta kunci oportunistik filter (oplock) untuk mencegah aplikasi lain mendapatkan pelanggaran berbagi. Jika sudah ada handel terbuka, permintaan buat akan gagal dengan STATUS_OPLOCK_NOT_GRANTED. |
| FILE_OPEN_REPARSE_POINT (0x00200000) | Buka file dengan titik pemisahan ulang dan lewati pemrosesan titik pemilah ulang normal untuk file. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini. |
| FILE_OPEN_NO_RECALL (0x00400000) | Menginstruksikan filter apa pun yang melakukan penyimpanan offline atau virtualisasi untuk tidak memanggil kembali konten file sebagai akibat dari pembukaan ini. |
| FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) | Bendera ini menginstruksikan sistem file untuk menangkap pengguna yang terkait dengan utas panggilan. Setiap panggilan berikutnya ke FltQueryVolumeInformation atau ZwQueryVolumeInformationFile menggunakan handel yang dikembalikan akan mengasumsikan pengguna yang ditangkap, daripada pengguna panggilan pada saat itu, untuk tujuan menghitung ruang kosong yang tersedia untuk pemanggil. Ini berlaku untuk nilai FsInformationClass berikut: FileFsSizeInformation, , FileFsFullSizeInformationdan FileFsFullSizeInformationEx. |
NamedPipeType [in]
Jenis pipa bernama untuk membuat (byte-type atau message-type).
ReadMode [in]
Mode untuk membaca pipa (jenis byte atau jenis pesan).
CompletionMode [in]
Menentukan bagaimana operasi akan diselesaikan.
MaximumInstances [in]
Jumlah maksimum instans simultan dari pipa bernama.
InboundQuota [in]
Menentukan kuota kumpulan yang dicadangkan untuk penulisan ke sisi masuk dari pipa bernama.
OutboundQuota [in]
Menentukan kuota kumpulan yang dicadangkan untuk penulisan ke sisi masuk dari pipa bernama.
DefaultTimeout [in, opsional]
Penunjuk opsional ke nilai batas waktu yang digunakan jika nilai batas waktu tidak ditentukan saat menunggu instans pipa bernama.
Mengembalikan
Nilai fungsi adalah status akhir dari operasi buat/buka.
Keterangan
Untuk membuat instans pipa bernama, pengguna harus memiliki akses FILE_CREATE_PIPE_INSTANCE ke objek pipa bernama. Jika pipa bernama baru sedang dibuat, daftar kontrol akses (ACL) dari parameter atribut keamanan menentukan kontrol akses diskresi untuk pipa bernama.
Semua instans pipa bernama harus menentukan jenis pipa yang sama (jenis byte atau jenis pesan), akses pipa (dupleks, masuk, atau keluar), jumlah instans, dan nilai waktu habis. Jika nilai yang berbeda digunakan, fungsi ini gagal dan GetLastError mengembalikan ERROR_ACCESS_DENIED.
Proses klien tersambung ke pipa bernama dengan menggunakan fungsi CreateFile atau CallNamedPipe . Sisi klien dari pipa bernama dimulai dalam mode byte, bahkan jika sisi server dalam mode pesan. Untuk menghindari masalah saat menerima data, atur sisi klien ke mode pesan juga. Untuk mengubah mode pipa, klien pipa harus membuka pipa baca-saja dengan akses GENERIC_READ dan FILE_WRITE_ATTRIBUTES .
Server pipa tidak boleh melakukan operasi baca pemblokiran hingga klien pipa dimulai. Jika tidak, kondisi balapan dapat terjadi. Ini biasanya terjadi ketika kode inisialisasi, seperti run-time C, perlu mengunci dan memeriksa handel yang diwariskan.
Setiap kali pipa bernama dibuat, sistem membuat buffer masuk dan/atau keluar menggunakan kumpulan yang tidak disebarkan, yang merupakan memori fisik yang digunakan oleh kernel. Jumlah instans pipa (serta objek seperti utas dan proses) yang dapat Anda buat dibatasi oleh kumpulan yang tidak disebarkan yang tersedia. Setiap permintaan baca atau tulis memerlukan ruang di buffer untuk data baca atau tulis, ditambah ruang tambahan untuk struktur data internal.
Ukuran buffer input dan output adalah saran. Ukuran buffer aktual yang dicadangkan untuk setiap ujung pipa bernama adalah default sistem, minimum atau maksimum sistem, atau ukuran yang ditentukan dibulatkan ke batas alokasi berikutnya. Ukuran buffer yang ditentukan harus cukup kecil sehingga proses Anda tidak akan kehabisan kumpulan yang tidak di-patahkan, tetapi cukup besar untuk mengakomodasi permintaan umum.
Setiap kali operasi penulisan pipa terjadi, sistem pertama-tama mencoba mengisi daya memori terhadap kuota penulisan pipa. Jika kuota tulis pipa yang tersisa cukup untuk memenuhi permintaan, operasi tulis segera selesai. Jika kuota tulis pipa yang tersisa terlalu kecil untuk memenuhi permintaan, sistem akan mencoba memperluas buffer untuk mengakomodasi data menggunakan kumpulan yang tidak disebarkan yang dicadangkan untuk proses tersebut. Operasi tulis akan memblokir hingga data dibaca dari pipa sehingga kuota buffer tambahan dapat dirilis. Oleh karena itu, jika ukuran buffer yang Anda tentukan terlalu kecil, sistem akan menumbuhkan buffer sesuai kebutuhan, tetapi kelemahannya adalah operasi akan diblokir. Jika operasi tumpang tindih, utas sistem akan diblokir; jika tidak, utas aplikasi diblokir.
Untuk membebaskan sumber daya yang digunakan oleh pipa bernama, aplikasi harus selalu menutup handel ketika tidak lagi diperlukan, yang dicapai baik dengan memanggil fungsi CloseHandle atau ketika proses yang terkait dengan handel instans berakhir. Perhatikan bahwa instans pipa bernama mungkin memiliki lebih dari satu handel yang terkait dengannya. Instans pipa bernama selalu dihapus ketika handel terakhir ke instans pipa bernama ditutup.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Header | ntioapi.h |
| Pustaka | ntdll.lib |