Fungsi PeekNamedPipe (namedpipeapi.h)

Artikel
03/08/2023

Menyalin data dari pipa bernama atau anonim ke dalam buffer tanpa menghapusnya dari pipa. Ini juga mengembalikan informasi tentang data dalam pipa.

Sintaks

BOOL PeekNamedPipe(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPVOID  lpBuffer,
  [in]            DWORD   nBufferSize,
  [out, optional] LPDWORD lpBytesRead,
  [out, optional] LPDWORD lpTotalBytesAvail,
  [out, optional] LPDWORD lpBytesLeftThisMessage
);

Parameter

[in] hNamedPipe

Handel ke pipa. Parameter ini dapat menjadi handel ke instans pipa bernama, seperti yang dikembalikan oleh fungsi CreateNamedPipe atau CreateFile , atau dapat menjadi handel ke akhir baca pipa anonim, seperti yang dikembalikan oleh fungsi CreatePipe . Handel harus memiliki akses GENERIC_READ ke pipa.

[out, optional] lpBuffer

Penunjuk ke buffer yang menerima data yang dibaca dari pipa. Parameter ini bisa NULL jika tidak ada data yang akan dibaca.

[in] nBufferSize

Ukuran buffer yang ditentukan oleh parameter lpBuffer , dalam byte. Parameter ini diabaikan jika lpBuffer adalah NULL.

[out, optional] lpBytesRead

Pointer ke variabel yang menerima jumlah byte yang dibaca dari pipa. Parameter ini bisa NULL jika tidak ada data yang akan dibaca.

[out, optional] lpTotalBytesAvail

Penunjuk ke variabel yang menerima jumlah total byte yang tersedia untuk dibaca dari pipa. Parameter ini bisa NULL jika tidak ada data yang akan dibaca.

[out, optional] lpBytesLeftThisMessage

Penunjuk ke variabel yang menerima jumlah byte yang tersisa dalam pesan ini. Parameter ini akan menjadi nol untuk pipa bernama jenis byte atau untuk pipa anonim. Parameter ini bisa NULL jika tidak ada data yang akan dibaca.

Nilai kembali

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

Fungsi PeekNamedPipe mirip dengan fungsi ReadFile dengan pengecualian berikut:

Data dibaca dalam mode yang ditentukan dengan CreateNamedPipe. Misalnya, buat pipa dengan PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE. Jika Anda mengubah mode menjadi PIPE_READMODE_BYTE dengan SetNamedPipeHandleState, ReadFile akan membaca dalam mode byte, tetapi PeekNamedPipe akan terus membaca dalam mode pesan.
Data yang dibaca dari pipa tidak dihapus dari buffer pipa.
Fungsi ini dapat mengembalikan informasi tambahan tentang konten pipa.
Fungsi ini selalu segera kembali dalam aplikasi utas tunggal, bahkan jika tidak ada data dalam pipa. Mode tunggu dari handel pipa bernama (pemblokiran atau pemblokiran) tidak berpengaruh pada fungsi.

Catatan Fungsi PeekNamedPipe dapat memblokir eksekusi utas dengan cara yang sama seperti fungsi I/O apa pun saat dipanggil pada handel sinkron dalam aplikasi multi-utas. Untuk menghindari kondisi ini, gunakan handel pipa yang dibuat untuk I/O asinkron.

Jika handel yang ditentukan adalah handel pipa bernama dalam mode byte-read, fungsi membaca semua byte yang tersedia hingga ukuran yang ditentukan dalam nBufferSize. Untuk handel pipa bernama dalam mode baca pesan, fungsi membaca pesan berikutnya dalam pipa. Jika pesan lebih besar dari nBufferSize, fungsi mengembalikan TRUE setelah membaca jumlah byte yang ditentukan. Dalam situasi ini, lpBytesLeftThisMessage akan menerima jumlah byte yang tersisa dalam pesan.

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.

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