DosQNmPHandState

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:
Remarks:	This page list the older version of the function for reference.

This call returns information for a named pipe's specific handle state.

Syntax

DosQNmPHandState (Handle, PipeHandleState)

Parameters

Handle (HPIPE) - input

Handle of the named pipe returned by DosMakeNmPipe or DosOpen.

PipeHandleState (PUSHORT) - output

Address of the named pipe handle state:

Bit        Description
15        Blocking; pipe is defined as follows:
       0 = Reads/Writes block if no data available.
       1 = Reads/Writes return immediately if no data available.

Reads normally block until at least partial data can be returned. Writes, by default, block until all bytes requested have been written. Non-blocking mode (value is 1) changes this behavior as follows:

• DosRead returns immediately with BytesRead = 0 (as defined in DosRead) if no data is available.
• DosWrite returns immediately with BytesWritten = 0 (as defined in DosWrite) if insufficient buffer space is available in the pipe, or the entire data area is transferred.

14     Server or requester end; end-point of named pipe shown as follows:
       0 = Handle is the client end of a named pipe.
       1 = Handle is the server (requester) end of a named pipe. 
13-12        Reserved.
11-10  Type of named pipe:
            00 = Pipe is a byte stream pipe.
            01 = Pipe is a message stream pipe. 
   
9-8        Read mode:
       00 = Read pipe as a byte stream.
       01 = Read pipe as a message stream. 
   
7-0        Instance count; 8-bit count to control pipe instances. When making the first instance of a named pipe, this field specifies how many instances can be created. Instances are as follows: 

Value Definition

1        This can be the only instance (pipe is unique). 
-1       The number of instances is unlimited. 
0        Reserved value.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 230 ERROR_BAD_PIPE
• 233 ERROR_PIPE_NOT_CONNECTED

Remarks

At the serving end, the values returned by DosQNmPHandState are those originally established by DosMakeNmPipe or a subsequent DosSetNmPHandState. The values returned by the client end are those originally established by DosOpen or a subsequent DosSetNmPHandState.

Example Code

C Binding

#define INCL_DOSNMPIPES

USHORT  rc = DosQNmPHandState(Handle, PipeHandleState);

HPIPE            Handle;          /* Pipe handle */
PUSHORT          PipeHandleState; /* Pipe handle state */

USHORT           rc;              /* return code */

MASM Binding

EXTRN  DosQNmPHandState:FAR
INCL_DOSNMPIPES     EQU 1

PUSH   WORD    Handle          ;Pipe handle
PUSH@  WORD    PipeHandleState ;Pipe handle state (returned)
CALL   DosQNmPHandState

Returns WORD