DosQueryNPipeInfo

From EDM2
Jump to: navigation, search

Returns information about a named pipe.

Syntax

#define INCL_DOSNMPIPES
#include <os2.h>

HPIPE     hpipe;      /*  The named-pipe handle to query. */
ULONG     infolevel;  /*  Level of the required pipe information. */
PVOID     pBuf;       /*  A pointer to the storage area in which the requested level
                          of named-pipe information is returned. */
ULONG     cbBuf;      /*  The length, in bytes, of pBuf. */
APIRET    ulrc;       /*  Return Code. */

ulrc = 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