DosQueryNPipeSemState

Returns information about local named pipes that are attached to a semaphore.

Syntax

DosQueryNPipeSemState(hsem, pnpss, cbBuf)

Parameters

hsem (HSEM) - input

The handle of a shared event or muxwait semaphore that was previously attached to one or more named pipes with DosSetNPipeSem.

pnpss (PPIPESEMSTATE) - output

A pointer to a buffer containing a record for each named pipe that is attached to the semaphore.

cbBuf (ULONG) - input

The size, in bytes, of pnpss.

Return Code

ulrc (APIRET) - returns

DosQueryNPipeSemState returns one of the following values:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 111 ERROR_BUFFER_OVERFLOW

Remarks

DosQueryNPipeSemState returns information about the status of local named pipes that are attached to a shared event or multiple-wait (muxwait) semaphore. (Event semaphores are attached to local named pipes by calling DosSetNPipeSem.)

A record is returned for each local named pipe that is attached to the specified semaphore and whose state is either closed or allows blocking-mode input and output to be done. However, there is no guarantee that the records in the buffer refer only to named pipes that were opened by the process making this call. If the same semaphore has been attached to different named pipes by multiple processes, information about named pipes that are not accessible to the caller can be returned. For this reason, communicating processes should have a convention for key values to help identify the named pipes of interest. (A key value is specified when DosSetNPipeSem is called to attach the semaphore to a named pipe.)

If a process wants data in the buffer to refer only to its own named pipes, it must use a private event semaphore.

Example Code

This example handles the client side of a pipe. It opens an existing named pipe and event semaphore, sends a message to the host, displays the state of the pipe semaphore, reads the host reply, and finally closes the event semaphore and 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 */
   HEV      hev                    = NULLHANDLE; /* Event semaphore handle */
   PIPEINFO PipeBuffer[4]          = {{0}};
   struct   _AVAILDATA  BytesAvail = {0};
   UCHAR    Buffer[200]            = {0};
   ULONG    bytes                  = 0;
   ULONG    Action                 = 0;
   int      i                      = 0;
   PIPESEMSTATE infobuf[3]         = {{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 Pipe.\n");

   rc = DosOpenEventSem("\\SEM32\\PIPE\\EXAMPLE", &hev);
   if (rc != NO_ERROR) {
      printf("DosOpenEventSem error: error code = %u\n", rc);
      return 1;
   }

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

   fflush(NULL);  /* Flush printf buffer */
   gets(message);

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

   rc = DosQueryNPipeSemState((HSEM) hev, infobuf, sizeof(PIPESEMSTATE)*3);
   if (rc != NO_ERROR) {
     printf("DosQueryNPipeSemState error: return code = %u\n",rc);
     return 1;
   }

   printf("Status  Flag   Key   Avail\n------ ------ ------ ------\n");
   for (i=0; i<3; i++)
     printf("%6u %6u %6u %6u\n", infobuf[i].fStatus,
            infobuf[i].fFlag, infobuf[i].usKey, infobuf[i].usAvail);

   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: %s\n\n", message);

   rc = DosCloseEventSem(hev);
   /* Should check if (rc != NO_ERROR) here... */

   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
• DosQueryNPHState
• DosQueryNPipeInfo
• DosRead
• DosResetBuffer
• DosSetNPHState
• DosSetNPipeSem
• DosTransactNPipe
• DosWaitNPipe
• DosWrite