Fungsi CreateNamedPipeA (winbase.h)
Membuat instans pipa bernama dan mengembalikan handel untuk operasi pipa berikutnya. Proses server pipa bernama menggunakan fungsi ini baik untuk membuat instans pertama dari pipa bernama tertentu dan membuat atribut dasarnya atau untuk membuat instans baru dari pipa bernama yang ada.
Sintaks
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
Parameter
[in] lpName
Nama pipa yang unik. String ini harus memiliki formulir berikut:
\\.\pipe\pipename
Bagian nama pipa dari nama dapat mencakup karakter apa pun selain garis miring terbelakang, termasuk angka dan karakter khusus. Seluruh string nama pipa dapat memiliki panjang hingga 256 karakter. Nama pipa tidak peka huruf besar/kecil.
[in] dwOpenMode
Mode terbuka.
Fungsi gagal jika dwOpenMode menentukan apa pun selain 0 atau bendera yang tercantum dalam tabel berikut.
Parameter ini harus menentukan salah satu mode akses pipa berikut. Mode yang sama harus ditentukan untuk setiap instans pipa.
| Mode | Makna |
|---|---|
|
Pipa dua arah; proses server dan klien dapat membaca dari dan menulis ke pipa. Mode ini memberi server setara dengan akses GENERIC_READ dan GENERIC_WRITE ke pipa. Klien dapat menentukan GENERIC_READ atau GENERIC_WRITE, atau keduanya, saat tersambung ke pipa menggunakan fungsi CreateFile . |
|
Aliran data dalam pipa hanya berubah dari klien ke server. Mode ini memberi server akses yang setara dengan GENERIC_READ ke pipa. Klien harus menentukan akses GENERIC_WRITE saat menyambungkan ke pipa. Jika klien harus membaca pengaturan pipa dengan memanggil fungsi GetNamedPipeInfo atau GetNamedPipeHandleState , klien harus menentukan akses GENERIC_WRITE dan FILE_READ_ATTRIBUTES saat menyambungkan ke pipa. |
|
Aliran data dalam pipa beralih dari server ke klien saja. Mode ini memberi server setara dengan akses GENERIC_WRITE ke pipa. Klien harus menentukan akses GENERIC_READ saat menyambungkan ke pipa. Jika klien harus mengubah pengaturan pipa dengan memanggil fungsi SetNamedPipeHandleState , klien harus menentukan akses GENERIC_READ dan FILE_WRITE_ATTRIBUTES saat menyambungkan ke pipa. |
Parameter ini juga dapat mencakup satu atau beberapa bendera berikut, yang memungkinkan mode write-through dan tumpang tindih. Mode ini dapat berbeda untuk instans yang berbeda dari pipa yang sama.
| Mode | Makna |
|---|---|
|
Jika Anda mencoba membuat beberapa instans pipa dengan bendera ini, pembuatan instans pertama berhasil, tetapi pembuatan instans berikutnya gagal dengan ERROR_ACCESS_DENIED. |
|
Mode write-through diaktifkan. Mode ini hanya memengaruhi operasi tulis pada pipa jenis byte dan, kemudian, hanya ketika proses klien dan server berada di komputer yang berbeda. Jika mode ini diaktifkan, fungsi yang menulis ke pipa bernama tidak kembali sampai data yang ditulis dikirimkan di seluruh jaringan dan berada di buffer pipa di komputer jarak jauh. Jika mode ini tidak diaktifkan, sistem meningkatkan efisiensi operasi jaringan dengan menyangga data hingga jumlah minimum byte terakumulasi atau sampai waktu maksimum berlalu. |
|
Mode tumpang tindih diaktifkan. Jika mode ini diaktifkan, fungsi yang melakukan operasi baca, tulis, dan sambungkan yang mungkin membutuhkan waktu signifikan untuk diselesaikan dapat segera kembali. Mode ini memungkinkan utas yang memulai operasi untuk melakukan operasi lain saat operasi yang memakan waktu dijalankan di latar belakang. Misalnya, dalam mode tumpang tindih, utas dapat menangani operasi input dan output (I/O) simultan pada beberapa instans pipa atau melakukan operasi baca dan tulis simultan pada handel pipa yang sama. Jika mode tumpang tindih tidak diaktifkan, fungsi yang melakukan operasi baca, tulis, dan sambungkan pada handel pipa tidak kembali hingga operasi selesai. Fungsi ReadFileEx dan WriteFileEx hanya dapat digunakan dengan handel pipa dalam mode tumpang tindih. Fungsi ReadFile, WriteFile, ConnectNamedPipe, dan TransactNamedPipe dapat dijalankan secara sinkron atau sebagai operasi yang tumpang tindih. |
Parameter ini dapat mencakup kombinasi mode akses keamanan berikut. Mode ini dapat berbeda untuk instans yang berbeda dari pipa yang sama.
| Mode | Makna |
|---|---|
|
Pemanggil akan memiliki akses tulis ke daftar kontrol akses diskresi (ACL) pipa bernama. |
|
Pemanggil akan memiliki akses tulis ke pemilik pipa bernama. |
|
Pemanggil akan memiliki akses tulis ke SACL pipa bernama. Untuk informasi selengkapnya, lihat Access-Control Lists (ACL) dan SACL Access Right. |
[in] dwPipeMode
Mode pipa.
Fungsi gagal jika dwPipeMode menentukan apa pun selain 0 atau bendera yang tercantum dalam tabel berikut.
Salah satu mode jenis berikut dapat ditentukan. Mode jenis yang sama harus ditentukan untuk setiap instans pipa.
| Mode | Makna |
|---|---|
|
Data ditulis ke pipa sebagai aliran byte. Mode ini tidak dapat digunakan dengan PIPE_READMODE_MESSAGE. Pipa tidak membedakan byte yang ditulis selama operasi penulisan yang berbeda. |
|
Data ditulis ke pipa sebagai aliran pesan. Pipa memperlakukan byte yang ditulis selama setiap operasi tulis sebagai unit pesan. Fungsi GetLastError mengembalikan ERROR_MORE_DATA saat pesan tidak dibaca sepenuhnya. Mode ini dapat digunakan dengan PIPE_READMODE_MESSAGE atau PIPE_READMODE_BYTE. |
Salah satu mode baca berikut dapat ditentukan. Instans yang berbeda dari pipa yang sama dapat menentukan mode baca yang berbeda.
Salah satu mode tunggu berikut dapat ditentukan. Instans yang berbeda dari pipa yang sama dapat menentukan mode tunggu yang berbeda.
| Mode | Makna |
|---|---|
|
Mode pemblokiran diaktifkan. Ketika handel pipa ditentukan dalam fungsi ReadFile, WriteFile, atau ConnectNamedPipe , operasi tidak selesai sampai ada data untuk dibaca, semua data ditulis, atau klien tersambung. Penggunaan mode ini dapat berarti menunggu tanpa batas waktu dalam beberapa situasi bagi proses klien untuk melakukan tindakan. |
|
Mode nonblocking diaktifkan. Dalam mode ini, ReadFile, WriteFile, dan ConnectNamedPipe selalu segera kembali.
Perhatikan bahwa mode nonblocking didukung untuk kompatibilitas dengan Microsoft LAN Manager versi 2.0 dan tidak boleh digunakan untuk mencapai I/O asinkron dengan pipa bernama. Untuk informasi selengkapnya tentang I/O pipa asinkron, lihat Input dan Output Sinkron dan Tumpang Tindih. |
Salah satu mode klien jarak jauh berikut dapat ditentukan. Instans yang berbeda dari pipa yang sama dapat menentukan mode klien jarak jauh yang berbeda.
[in] nMaxInstances
Jumlah maksimum instans yang dapat dibuat untuk pipa ini. Instans pertama pipa dapat menentukan nilai ini; angka yang sama harus ditentukan untuk instans pipa lainnya. Nilai yang dapat diterima berada dalam rentang 1 hingga PIPE_UNLIMITED_INSTANCES (255).
Jika parameter ini PIPE_UNLIMITED_INSTANCES, jumlah instans pipa yang dapat dibuat hanya dibatasi oleh ketersediaan sumber daya sistem. Jika nMaxInstances lebih besar dari PIPE_UNLIMITED_INSTANCES, nilai yang dikembalikan adalah INVALID_HANDLE_VALUE dan GetLastError mengembalikan ERROR_INVALID_PARAMETER.
[in] nOutBufferSize
Jumlah byte yang akan dicadangkan untuk buffer output. Untuk diskusi tentang ukuran buffer pipa bernama, lihat bagian Keterangan berikut.
[in] nInBufferSize
Jumlah byte yang akan dicadangkan untuk buffer input. Untuk diskusi tentang ukuran buffer pipa bernama, lihat bagian Keterangan berikut.
[in] nDefaultTimeOut
Nilai batas waktu default, dalam milidetik, jika fungsi WaitNamedPipe menentukan NMPWAIT_USE_DEFAULT_WAIT. Setiap instans pipa bernama harus menentukan nilai yang sama.
Nilai nol akan menghasilkan waktu habis default 50 milidetik.
[in, optional] lpSecurityAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES yang menentukan deskriptor keamanan untuk pipa bernama baru dan menentukan apakah proses anak dapat mewarisi handel yang dikembalikan. Jika lpSecurityAttributes adalah NULL, pipa bernama mendapatkan deskriptor keamanan default dan handel tidak dapat diwariskan. ACL dalam deskriptor keamanan default untuk pipa bernama memberikan kontrol penuh ke akun LocalSystem, administrator, dan pemilik pembuat. Mereka juga memberikan akses baca kepada anggota grup Semua Orang dan akun anonim.
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke akhir server dari instans pipa bernama.
Jika fungsi gagal, nilai yang dikembalikan INVALID_HANDLE_VALUE. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.
Keterangan
Untuk membuat instans pipa bernama dengan menggunakan CreateNamedPipe, 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.
Windows 10, versi 1709: Pipa hanya didukung dalam kontainer aplikasi; yaitu, dari satu proses UWP ke proses UWP lain yang merupakan bagian dari aplikasi yang sama. Selain itu, pipa bernama harus menggunakan sintaks \\.\pipe\LOCAL\ untuk nama pipa.
Contoh
Misalnya, lihat Multithreaded Pipe Server.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk