Determining Pipe Status

DosQueryNPHState and DosQueryNPipeInfo can be used to obtain information about named pipes.

DosQueryNPHState
A client process can read data from the pipe, write data to the pipe, or both, depending on the access mode specified when the pipe was created. To check the current access mode, the client process can call DosQueryNPHState.

The following code fragment shows how to use DosQueryNPHState to obtain information about a named pipe:

    #define INCL_DOSNMPIPES   /* Named-pipe values */
    #include <os2.h>
    #include <stdio.h>

    HPIPE    hpHandle;            /* Pipe handle       */
    ULONG    ulPipeHandleState;   /* Pipe-handle state */
    APIRET   ulrc;                /* Return code       */

    ulrc = DosQueryNPHState(hpHandle, &ulPipeHandleState);

    if (ulrc != 0) {
        printf("DosQueryNPHState error: return code = %ld",
               ulrc);
        return;
    }

On successful return, PipeHandleState will contain information that describes the nature of the named pipe.

DosQueryNPHState returns the following information about the pipe handle and the attributes of the pipe:

• The end of the pipe that the handle is for (server or client end)

• The pipe type (byte pipe or message pipe)

• The instance count

• The blocking mode (blocking or nonblocking)

• The read mode (byte-read mode or message-read mode)

The values for pipe type and instance count cannot be changed, so they are always the same as those that were specified when the pipe was created with DosCreateNPipe. The information returned for blocking mode and read mode, however, can come from different sources:

• If the handle is for the server end of the pipe, then the blocking mode and the read mode were set with DosCreateNPipe, but could have been reset with DosSetNPHState.

• If the handle is for the client end of the pipe, then the blocking mode and the read mode were set to "blocking" and "byte-read" by the system when the client called DosOpen. However, again, they could have been reset with DosSetNPHState.

The pipe attributes are described in more detail in Creating Named Pipes.

An application can use DosSetNPHState to change the wait mode and the read mode. The pipe cannot be changed to no-wait mode when another thread is blocked on a read or write operation to the same end of the pipe.

DosQueryNPipeInfo More detailed information about a named pipe can be obtained by using DosQueryNPipeInfo. This function returns information in a PIPEINFO data structure that includes the name of the pipe, the current and maximum instance counts (the current number of pipes and the maximum number of times the pipe can be created), the size of the input and output buffers for the pipe, and the pipe identifier of the client process.

The following code fragment shows how to use DosQueryNPipeInfo:

    #define INCL_DOSNMPIPES   /* Named-pipe values */
    #include <os2.h>
    #include <stdio.h>

    HPIPE    hpHandle;          /* Pipe handle                     */
    ULONG    ulInfoLevel;       /* Pipe data required              */
    PIPEINFO pipInfoBuf;        /* Pipe information data structure */
    ULONG    ulInfoBufSize;     /* Pipe data-buffer size           */
    APIRET   ulrc;              /* Return code                     */

    ulInfoLevel = 1;                    /* Ask for standard level of pipe info */

    ulInfoBufSize = sizeof(PIPEINFO);   /* Length of pipe info data structure  */

    ulrc = DosQueryNPipeInfo(hpHandle,
                             ulInfoLevel,
                             &pipInfoBuf,
                             ulInfoBufSize);

    if (ulrc != 0) {
        printf("DosQueryNPipeInfo error: return code = %ld",
               ulrc);
        return;
    }

On successful return, the pipe information data structure contains a set of information describing the nature and the current state of the named pipe.

DosQueryNPipeInfo returns level 1 or level 2 file information for the pipe. Level 1 information includes the following:

• The actual sizes of the in-buffer and out-buffer

• The maximum number of pipe instances permitted

• The current number of pipe instances

• The length of the pipe name

• The ASCIIZ name of the pipe, including \\ComputerName if the pipe is in a remote computer system.

  Level 2 information consists of a unique 2-byte identifier for each of the pipe's client processes.