DosPeekNPipe

DosPeekNPipe will examine the content and status of the pipe, without changing the pipe in any way (contents and state remain).

Syntax

DosPeekNPipe(hpipeHandle, pBuffer, ulBufferLen, pBytesRead, pBytesAvail, pPipeState)

Parameters

HPIPE hpipeHandle (input)

Handle of the named pipe to examine. It is returned by DosCreateNPipe (for the server) or DosOpen (for the client).

PVOID pBuffer (output)

This is a pointer to a output buffer.

ULONG ulBufferLen (input)

The number of bytes to read.

PULONG pBytesRead (output)

A pointer to a variable that will contain the number of bytes actually read.

PAVAILDATA pBytesAvail (output)

This is a pointer to a 4-byte buffer. Upon return the bits will be structured as:

• 32-16 The number of bytes that were in the pipe. This includes message-header bytes and bytes that have been examined.
• 15-0 The number of bytes in the current message. This will be 0 for a byte-stream pipe.

PULONG pPipeState (input)

This is a pointer to a value, representing the state of the named pipe.

• A value of 1 (NP_STATE_DISCONNECTED) means disconnected.
• A value of 2 (NP_STATE_LISTENING) means listening.
• A value of 3 (NP_STATE_CONNECTED) means connected.
• A value of 4 (NP_STATE_CLOSING) means closing.

A pipe is in disconnected state immediately after DosCreateNPipe or DosDisConnectNPipe. A pipe that is disconnected can not be opened using DosOpen.

A pipe is in the listening state after the server has called DosConnectNPipe. DosOpen may be called on a pipe that is listening.

A pipe is connected when a client has used DosOpen on it. This will allow, providing they have valid handles, the client and the server to read and write data to the pipe.

A pipe is closing when all client ends have been closed, using DosClose. The server end should then acknowledge this (the pipe is now in closing state) by issuing DosDisConnectNPipe or DosClose.

Returns

APIRET rc

The following values can be returned:

• 0 NO_ERROR
• 230 ERROR_BAD_PIPE
• 231 ERROR_PIPE_BUSY
• 233 ERROR_PIPE_NOT_CONNECTED

Usage Explanation

DosPeekNPipe will never block. If DosPeekNPipe can't get access to the pipe at once, it will return ERROR_PIPE_BUSY. Because of this it will return what's currently in the buffer, even though this might not be a complete message.

Sample Code

#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE Handle;       /* The pipe handle. */
UCHAR Buffer[800];  /* The user buffer. */
ULONG BufferLen;    /* The length of the buffer. */
ULONG BytesRead;    /* The actual number of bytes read. */

struct _AVAILDATA BytesAvail; /* Bytes available. */

ULONG PipeState; /* The returned pipestate. */
APIRET rc;       /* Just to take care of the return code. */
Bufferlen = 800; /* Length of the buffer we read into. */

rc = DosPeekNPipe( Handle, Buffer, BufferLen, &BytesRead,
         &BytesAvail, &PipeState);

if (rc != 0)
{
   /* We have an error we must take care of. */
}

See Also

• DosConnectNPipe
• DosCreateNPipe
• DosDisConnectNPipe
• DosCallNPipe
• DosQueryNPHState
• DosQueryNPipeInfo
• DosQueryNPipeSemState
• DosSetNPHState
• DosSetNPipeSem
• DosTransactNPipe
• DosWaitNPipe
• DosClose
• DosDupHandle
• DosOpen
• DosRead
• DosResetBuffer
• DosWrite