DosPeekNPipe examines the current contents of a named pipe.
Named pipes created with the NP_ACCESS_INBOUND access mode cannot use the DosPeekNPipe function. If the named pipe's client uses the DosPeekNPipe function, the function returns error code 5 (ERROR_ACCESS_DENIED).
It is similar to DosRead, except that DosPeekNPipe does not remove data from the pipe. In addition, DosPeekNPipe never blocks, even if the pipe is in blocking mode; if the pipe cannot be accessed immediately, ERROR_PIPE_BUSY is returned.
Because DosPeekNPipe does not block, it returns only what is currently in the pipe. Thus, if a message pipe is being examined, only a portion of a message might be returned, even though the specified buffer length could accommodate the entire message.
DosPeekNPipe also returns the state of the pipe. A named pipe can be in any of the following states: Connected, Disconnected, Listening, Closing.
The following code fragment shows how to use DosPeekNPipe:
#define INCL_DOSNMPIPES /* Named-pipe values */
#include <os2.h>
#include <stdio.h>
HPIPE hpHandle; /* Pipe handle */
UCHAR ucBuffer[200]; /* Address of user buffer */
ULONG ulBufferLen; /* Buffer length */
ULONG ulBytesRead; /* Bytes read (returned) */
struct _AVAILDATA BytesAvail; /* Bytes available (returned) */
ULONG ulPipeState; /* Pipe state (returned) */
APIRET ulrc; /* Return code */
ulBufferLen = 200; /* Length of the read buffer */
ulrc = DosPeekNPipe(hpHandle,
ucBuffer,
ulBufferLen,
&ulBytesRead,
&BytesAvail,
&ulPipeState);
if (ulrc != 0) {
printf("DosPeekNPipe error: return code = %ld",
ulrc);
return;
}
On successful return, the input buffer Buffer will contain up to the first 200 bytes from the named pipe, BytesRead will contain the number of bytes read into Buffer, BytesAvail will contain the total number of bytes that were available in the pipe, and PipeState will contain a value indicating the state of the named pipe.