DosQueryNPipeInfo
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;
}
