DosPeekNmPipe

Bindings:  C, MASM 

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

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

 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: 

    2 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: 

    o A DosMakeNmPipe but before the first DosConnectNmPipe, or 
    o 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. 

 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.