[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosPeekNPipe

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 rc = 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 immediatedly 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
0NO_ERROR
230ERROR_BAD_PIPE
231ERROR_PIPE_BUSY
233ERROR_PIPE_NOT_CONNECTED

Include Info

 #define INCL_DOSNMPIPES
#include <os2.h>

Usage Explanation

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

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.

Relevant Structures

typedef struct _AVAILDATA { USHORT cbpipe; /* bytes left in pipe. */ USHORT cbmessage; /* bytes left in current message. */ } AVAILDATA;

Gotchas

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

Author

Stefan Mars - mars@lysator.liu.se

Additions

Last modified March 17/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosPeekNPipe