Fungsi SetNamedPipeHandleState (namedpipeapi.h)

Artikel
02/29/2024

Mengatur mode baca dan mode pemblokiran dari pipa bernama yang ditentukan. Jika handel yang ditentukan adalah ke akhir klien dari pipa bernama dan jika proses server pipa bernama ada di komputer jarak jauh, fungsi juga dapat digunakan untuk mengontrol buffering lokal.

Sintaks

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

Parameter

[in] hNamedPipe

Handel ke instans pipa bernama. Parameter ini dapat menjadi handel ke ujung server pipa, seperti yang dikembalikan oleh fungsi CreateNamedPipe , atau ke akhir klien pipa, seperti yang dikembalikan oleh fungsi CreateFile . Handel harus memiliki akses GENERIC_WRITE ke pipa bernama untuk pipa tulis-saja atau baca/tulis, atau harus memiliki akses GENERIC_READ dan FILE_WRITE_ATTRIBUTES untuk pipa baca-saja.

Parameter ini juga dapat menjadi handel ke pipa anonim, seperti yang dikembalikan oleh fungsi CreatePipe .

[in, optional] lpMode

Mode pipa baru. Mode ini adalah kombinasi dari bendera mode baca dan bendera mode tunggu. Parameter ini bisa NULL jika mode tidak diatur. Tentukan salah satu mode berikut.

Mode	Makna
PIPE_READMODE_BYTE 0x00000000	Data dibaca dari pipa sebagai aliran byte. Mode ini adalah default jika tidak ada bendera mode baca yang ditentukan.
PIPE_READMODE_MESSAGE 0x00000002	Data dibaca dari pipa sebagai aliran pesan. Fungsi gagal jika bendera ini ditentukan untuk pipa jenis byte.

Salah satu mode tunggu berikut dapat ditentukan.

Mode	Makna
PIPE_WAIT 0x00000000	Mode pemblokiran diaktifkan. Mode ini adalah default jika tidak ada bendera mode tunggu yang ditentukan. Ketika handel pipa mode pemblokiran 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.
PIPE_NOWAIT 0x00000001	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 input dan output asinkron (I/O) dengan pipa bernama.

Mode

Makna

PIPE_WAIT
0x00000000

Mode pemblokiran diaktifkan. Mode ini adalah default jika tidak ada bendera mode tunggu yang ditentukan. Ketika handel pipa mode pemblokiran 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.

PIPE_NOWAIT
0x00000001

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 input dan output asinkron (I/O) dengan pipa bernama.

[in, optional] lpMaxCollectionCount

Jumlah maksimum byte yang dikumpulkan pada komputer klien sebelum transmisi ke server. Parameter ini harus NULL jika handel pipa yang ditentukan adalah ke akhir server dari pipa bernama atau jika proses klien dan server berada di komputer yang sama. Parameter ini diabaikan jika proses klien menentukan bendera FILE_FLAG_WRITE_THROUGH dalam fungsi CreateFile saat handel dibuat. Parameter ini bisa NULL jika jumlah koleksi tidak diatur.

[in, optional] lpCollectDataTimeout

Waktu maksimum, dalam milidetik, yang dapat berlalu sebelum pipa bernama jarak jauh mentransfer informasi melalui jaringan. Parameter ini harus NULL jika handel pipa yang ditentukan adalah ke akhir server dari pipa bernama atau jika proses klien dan server berada di komputer yang sama. Parameter ini diabaikan jika proses klien menentukan bendera FILE_FLAG_WRITE_THROUGH dalam fungsi CreateFile saat handel dibuat. Parameter ini bisa NULL jika jumlah koleksi tidak diatur.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

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 Klien Pipa Bernama.

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	namedpipeapi.h
Pustaka	Kernel32.lib
DLL	Kernel32.dll