DosQueryNPipeInfo

Returns information about a named pipe.

Syntax

DosQueryNPipeInfo(hpipe, infolevel, pBuf, cbBuf)

Parameters

hpipe (HPIPE) - input

The named-pipe handle to query.

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

infolevel (ULONG) - input

Level of the required pipe information.

Only levels 1 and 2 are supported.

pBuf (PVOID) - output

A pointer to the storage area in which the requested level of named-pipe information is returned.

Level 1 File Information - Information about the pipe itself is returned in the form of a PIPEINFO structure.

Level 2 File Information - For LAN Manager, LAN Server, and other LAN-based named pipe handles, the buffer will contain the unique 4-byte identifier of the client. Otherwise, this field returns NULL.

cbBuf (ULONG) - input

The length, in bytes, of pBuf.

Return Code

ulrc (APIRET) - returns

DosQueryNPipeInfo returns one of the following values:

• 0 NO_ERROR
• 111 ERROR_BUFFER_OVERFLOW
• 124 ERROR_INVALID_LEVEL
• 230 ERROR_BAD_PIPE

Remarks

DosQueryNPipeInfo returns all of the level-1 or level-2 information about a named pipe that will fit in the pBuf storage area.

If the length of the pipe name is greater than 255 bytes, then a length of 0 is returned in the namelength field; however, the full ASCIIZ name is still returned in the pipename field.

If there is more information than will fit in pBuf ERROR_BUFFER_OVERFLOW is returned.

Example Code

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

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

   fflush(NULL);   /* Force printf 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: %s\n\n", message);

   rc = DosQueryNPipeInfo(PipeHandle, 1L, &PipeBuffer, sizeof(PIPEINFO)*4);
   if (rc == NO_ERROR) {
     printf("The pipe's name is %s\n", PipeBuffer[0].szName);
   }

   rc = DosClose(PipeHandle);
   /* Should verify that (rc != NO_ERROR) here... */

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

Related Functions

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