DosQueryNPHState

Description

Returns information about a named-pipe handle.

Syntax

#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE     hpipe;   /*  The named-pipe handle to query. */
PULONG    pState;  /*  A pointer to the named-pipe handle state. */
APIRET    ulrc;    /*  Return Code. */

ulrc = DosQueryNPHState(hpipe, pState);

Parameters

hpipe (HPIPE) - input

The named-pipe handle to query.

The server handle is returned by DosCreateNPipe; the client handle is returned by DosOpen.

pState (PULONG) - output

A pointer to the named-pipe handle state.

This parameter contains the following bit fields:

Bit        Description 
31-16        Reserved. 

15        Blocking mode. Blocking mode is defined as either "blocking" or "nonblocking," as follows:
 
          0 NP_WAIT (0x0000) 
          Blocking mode: DosRead and DosWrite block if no data is available.

          1 NP_NOWAIT (0x8000)
          Nonblocking mode: DosRead and DosWrite return immediately if no data is available.

          DosRead normally blocks until at least partial data can be returned. 
          DosWrite blocks by default until all of the requested bytes have been written. 
          Nonblocking mode changes this behavior as follows:

          DosRead returns immediately with a value of zero for pcbActual if no data is available.

          DosWrite returns immediately with a value of zero for pcbActual if there is not enough buffer 
          space available in the pipe; otherwise, the entire data area is transferred. 
   
14        Specifies whether the handle is for the server or client end of the pipe, as follows:

            0 NP_END_CLIENT (0x0000)
              The handle is for the client end of the pipe.

            1 NP_END_SERVER (0x4000)
              The handle is for the server end of the pipe. 
   
13-12        Reserved. 

11-10        Type of named pipe. The pipe type is defined as follows:

             00            NP_TYPE_BYTE (0x0000)
                           The pipe is a byte pipe; that is, data is written to the pipe as an undifferentiated stream of bytes. 

             01            NP_TYPE_MESSAGE (0x0400)
                           The pipe is a message pipe; that is, data is written to the pipe as messages. The system records the length of each message in the first two bytes of the message, which are called the message header. 

9-8           Read mode. The read mode is defined as follows:

                00   NP_READMODE_BYTE (0x0000)
                     Byte-read mode: Read the pipe as a byte stream. 

                01   NP_READMODE_MESSAGE (0x0100)
                     Message-read mode: Read the pipe as a message stream.

7-0          Instance count: When the first instance of a named pipe is created, 
             this field specifies how many instances (including the first instance) can be created. 
             Possible values are:

               Value                    Definition 
                 1                    This is the only instance permitted (the pipe is unique). 
                 1 < value < 255      The number of instances is limited to the value specified. 
                 -1                    NP_UNLIMITED_INSTANCES (0x00FF)
                                       The number of instances is unlimited. 
                 0                    Reserved value.

Related Functions

• [[OS2 API:CPI: