DosPeekNmPipe

This call reads pipe without removing the read data from the pipe.

Syntax

DosPeekNmPipe (Handle, Buffer, BufferLen, BytesRead, BytesAvail, PipeState)

Parameters

Handle (HPIPE) - input 

Handle of the named pipe, returned by DosMakeNmPipe or DosOpen.

Buffer (PBYTE) - output 

Address of the output buffer.

BufferLen (USHORT) - input 

Number of bytes to be read.

BytesRead (PUSHORT) - output 

Address of the number of bytes read.

BytesAvail (PUSHORT) - output 

Address of the 4-byte buffer where the system returns the number of bytes that were available. The buffer structure is:

Bytes    Bytes buffered in pipe (including message header bytes and bytes peeked).
2 Bytes  Bytes in current message (zero for a byte stream pipe).

PipeState (PUSHORT) - output 

Address of a value representing the state of the named pipe.

Value   Definition
1     Disconnected
2     Listening
3     Connected
4     Closing

The pipe is in a disconnected state immediately after:

• A DosMakeNmPipe but before the first DosConnectNmPipe, or
• A DosDisConnectNmPipe but before the next DosConnectNmPipe. A disconnected pipe has no client end and cannot accept a DosOpen. The serving end must issue DosConnectNmPipe, so an open can be accepted.

The pipe is in a listening state after a DosConnectNmPipe. A listening pipe is ready to accept a DosOpen request. If the pipe is not in a listening state, DosOpen returns ERROR_PIPE_BUSY.

The pipe is in a connected state after a successful DosOpen to the listening pipe. The connected pipe allows the serving and client ends to perform I/O, provided both have valid handles.

The pipe is in a closing state after the last DosClose to the pipe from either the client or server end.

After DosClose has been issued for the client handle and any duplicates, and the serving end has read all buffered data, the serving end is returned ERROR_EOF for reads and ERROR_BROKEN_PIPE for writes. The serving end must acknowledge the closing of the client end by issuing either DosDisConnectNmPipe or DosClose. Issuing DosClose deallocates the pipe.

Return Code

rc (USHORT) - return

Return code descriptions are:

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

Remarks

DosPeekNmPipe is similar to a DosRead, except the bytes read from the pipe are not removed. In addition, a DosPeekNmPipe never blocks, regardless of the blocking mode set. If the pipe cannot be accessed immediately, ERROR_PIPE_BUSY is returned. Because the peek cannot block, it returns only what is currently in the pipe. Thus, a portion of a message may be returned, even though the size of the peek can accommodate the entire message.

The value returned in PipeState can be used by the client or the server end to determine the current state of the pipe and take appropriate action.

Bindings

C

#define INCL_DOSNMPIPES

USHORT  rc = DosPeekNmPipe(Handle, Buffer, BufferLen, BytesRead,
                             BytesAvail, PipeState);

HPIPE            Handle;        /* Pipe handle */
PBYTE            Buffer;        /* Address of user buffer */
USHORT           BufferLen;     /* Buffer length */
PUSHORT          BytesRead;     /* Bytes read (returned) */
PUSHORT          BytesAvail;    /* Bytes available (returned) */
PUSHORT          PipeState;     /* Pipe state (returned) */

USHORT           rc;            /* return code */

MASM

EXTRN  DosPeekNmPipe:FAR
INCL_DOSNMPIPES     EQU 1

PUSH   WORD    Handle        ;Pipe handle
PUSH@  OTHER   Buffer        ;User buffer
PUSH   WORD    BufferLen     ;Buffer length
PUSH@  WORD    BytesRead     ;Bytes read (returned)
PUSH@  DWORD   BytesAvail    ;Bytes available (returned)
PUSH@  WORD    PipeState     ;Pipe state (returned)
CALL   DosPeekNmPipe

Returns WORD