PeekNamedPipe
The PeekNamedPipe
function copies data from a named or anonymous pipe into a buffer without
removing it from the pipe. It also returns information about data in the pipe.
BOOL PeekNamedPipe(
|
HANDLE hNamedPipe, |
// handle to pipe
to copy from |
|
LPVOID lpBuffer, |
// pointer to data
buffer |
|
DWORD nBufferSize, |
// size, in bytes,
of data buffer |
|
LPDWORD lpBytesRead, |
// pointer to
number of bytes read |
|
LPDWORD lpTotalBytesAvail, |
// pointer to total
number of bytes available |
|
LPDWORD lpBytesLeftThisMessage |
// pointer to
unread bytes in this message |
|
); |
|
Parameters
hNamedPipe
Identifies
the pipe. This parameter can be a handle to a named pipe instance, as returned
by the CreateNamedPipe
or CreateFile
function, or it can be a handle to the read end of an anonymous pipe, as
returned by the CreatePipe
function. The handle must have GENERIC_READ access to the pipe.
lpBuffer
Points to a
buffer that receives data read from the pipe. This parameter can be NULL if no
data is to be read.
nBufferSize
Specifies the
size, in bytes, of the buffer specified by the lpBuffer parameter. This
parameter is ignored if lpBuffer is NULL.
lpBytesRead
Points to a
32-bit variable that receives the number of bytes read from the pipe. This
parameter can be NULL if no data is to be read.
lpTotalBytesAvail
Points to a
32-bit variable that receives the total number of bytes available to be read
from the pipe. This parameter can be NULL if no data is to be read.
lpBytesLeftThisMessage
Points to a
32-bit variable that receives the number of bytes remaining in this message.
This parameter will be zero for byte-type named pipes or for anonymous pipes.
This parameter can be NULL if no data is to be read.
Return Values
If the function
succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
PeekNamedPipe is similar to the ReadFile function with the following
exceptions:
The data read from the pipe is
not removed from the pipe s buffer.
The function always returns
immediately, even if there is no data in the pipe. The wait mode of a named
pipe handle (blocking or nonblocking) has no effect on the function.
The function can return
additional information about the contents of the pipe.
If the
specified handle is a named pipe handle in byte-read mode, the function reads
all available bytes up to the size specified in nBufferSize. For a named
pipe handle in message-read mode, the function reads the next message in the
pipe. If the message is larger than nBufferSize, the function returns
TRUE after reading the specified number of bytes. In this situation, lpBytesLeftThisMessage
will receive the number of bytes remaining in the message.
See Also