DosQueryNPHState

Returns information about a named-pipe handle.

Syntax

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:

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:

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.

Return Code

ulrc (APIRET) - returns

DosQueryNPHState returns one of the following values:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 230 ERROR_BAD_PIPE
• 233 ERROR_PIPE_NOT_CONNECTED

Remarks

DosQueryNPHState returns the following information about a 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 the 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 may 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 issued DosOpen. However, they may have been reset with DosSetNPHState.

Example Code

This example handles the client side of a pipe. It opens an existing named pipe, sets and queries the pipe handle state, sends a message to the host, reads the host reply, and finally closes the pipe.

Before running this example, compile and run the example code shown in the DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, or DosSetNPipeSem functions, which handles the host side of the pipe.

#define INCL_DOSFILEMGR       /* DOS File Manager values */
#define INCL_DOSNMPIPES       /* DOS Named Pipes values */
#define INCL_DOSSEMAPHORES    /* DOS Semaphore values */
#define INCL_DOSERRORS        /* DOS Error values */
#include <os2.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(VOID) {
   APIRET   rc                     = NO_ERROR;   /* Return code */
   CHAR     message[256]           = "";         /* Message buffer */
   HFILE    PipeHandle             = NULLHANDLE; /* Pipe handle */
   struct   _AVAILDATA  BytesAvail = {0};
   UCHAR    Buffer[200]            = {0};
   ULONG    bytes                  = 0;
   ULONG    Action                 = 0;
   ULONG    PipeState              = 0;
   ULONG    HandType               = 0;
   ULONG    FlagWord               = 0;
   ULONG    BytesRead              = 0;

   rc = DosOpen("\\PIPE\\EXAMPLE", &PipeHandle, &Action, 0, 0, FILE_OPEN,
                OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE |
                OPEN_FLAGS_FAIL_ON_ERROR, NULL);
   if (rc != NO_ERROR) {
      printf("DosOpen error: error code = %u\n", rc);
      return 1;
   } else printf("Connected to HOST\n");

   rc = DosSetNPHState(PipeHandle, NP_WAIT);
   if (rc != NO_ERROR) {
      printf("DosSetNPHState error: error code = %u\n", rc);
      return 1;
   }

   rc = DosQueryNPHState(PipeHandle, &PipeState);
   if (rc != NO_ERROR) {
      printf("DosQueryNPHState error: error code = %u\n", rc);
      return 1;
   } else {
      printf("Pipe handle state is: %x\n", PipeState);
   }  /* endif */

   printf("Enter message to send to PIPEHOST: ");

   fflush(NULL);  /* Force above printf prompt to display */
   gets(message);

   rc = DosWrite(PipeHandle, message, strlen(message), &bytes);
   if (rc != NO_ERROR) {
      printf("DosWrite error: error code = %u\n", rc);
      return 1;
   }
   rc = DosRead(PipeHandle, message, sizeof(message), &bytes);
   if (rc != NO_ERROR) {
      printf("DosRead error: error code = %u\n", rc);
      return 1;
   }

   printf("\nMessage received from PIPEHOST was: %s\n\n", message);

   rc = DosClose(PipeHandle);
   /* Should check if (RC == NO_ERROR)  here... */

   printf("...Disconnected\n");
   return NO_ERROR;
}

Related Functions

• DosCallNPipe
• DosClose
• DosConnectNPipe
• DosCreateNPipe
• DosDisConnectNPipe
• DosDupHandle
• DosOpen
• DosPeekNPipe
• DosQueryNPipeInfo
• DosQueryNPipeSemState
• DosRead
• DosResetBuffer
• DosSetNPHState
• DosSetNPipeSem
• DosTransactNPipe
• DosWaitNPipe
• DosWrite