DosCallNPipe

Makes a procedure call to a duplex message pipe.

Syntax

#define INCL_DOSNMPIPES
#include <os2.h>

PSZ       pszName;   /* The ASCIIZ name of the pipe to be opened. */
PVOID     pInbuf;    /* A pointer to the buffer that is to be written to the pipe. */
ULONG     cbIn;      /* The number of bytes to be written. */
PVOID     pOutbuf;   /* A pointer to the buffer for returned data. */
ULONG     cbOut;     /* The maximum size, in bytes, of returned data. */
PULONG    pcbActual; /* A pointer to the ULONG in which the number of bytes actually read
                        is returned. */
ULONG     msec;      /* The maximum time, in milliseconds, to wait for a pipe instance
                        to become available. */
APIRET    ulrc;      /* Return Code. */

ulrc = DosCallNPipe(pszName, pInbuf, cbIn,
         pOutbuf, cbOut, pcbActual, msec);

Parameters

pszName (PSZ) - input

The ASCIIZ name of the pipe to be opened.

Pipe names must include the prefix \PIPE\ and must conform to file-system naming conventions. When communicating with a remote process, the computer name must also be included, using the format \\ComputerName\PIPE\FileName.

pInbuf (PVOID) - input

A pointer to the buffer that is to be written to the pipe.

cbIn (ULONG) - input

The number of bytes to be written.

pOutbuf (PVOID) - output

A pointer to the buffer for returned data.

cbOut (ULONG) - input

The maximum size, in bytes, of returned data.

pcbActual (PULONG) - output

A pointer to the ULONG in which the number of bytes actually read is returned.

msec (ULONG) - input

The maximum time, in milliseconds, to wait for a pipe instance to become available.

Return Code

ulrc (APIRET) - returns

DosCallNPipe returns one of the following values:

• 0 NO_ERROR
• 2 ERROR_FILE_NOT_FOUND
• 3 ERROR_PATH_NOT_FOUND
• 5 ERROR_ACCESS_DENIED
• 11 ERROR_BAD_FORMAT
• 95 ERROR_INTERRUPT
• 230 ERROR_BAD_PIPE
• 231 ERROR_PIPE_BUSY
• 233 ERROR_PIPE_NOT_CONNECTED
• 234 ERROR_MORE_DATA

On the PowerPC platform, DosCallNPipe fails with error code ERROR_PATH_NOT_FOUND when the pipe name contains more than one \ in the name. For example, the following pipe name would cause DosCallNPipe to fail:

\pipe\\\\\longname.nam

Remarks

DosCallNPipe combines the functions of DosOpen, DosTransactNPipe, and DosClose for a duplex message pipe. If no instances of a pipe are available, DosCallNPipe waits for a specified time interval, and returns ERROR_INTERRUPT if the time interval elapses.

If this function is issued for a pipe that is not a duplex message pipe, ERROR_BAD_FORMAT is returned.

If an invalid pipe name is specified, DosCallNPipe returns ERROR_FILE_NOT_FOUND.

If pOutbuf is too small to contain the response message, ERROR_MORE_DATA is returned.

If the server process has not issued DosConnectNPipe to put the pipe into a listening state, DosCallNPipe returns ERROR_PIPE_BUSY.

Clients of named pipes created with the NP_ACCESS_OUTBOUND or NP_ACCESS_INBOUND access mode cannot use the DosCallNPipe function. If the named pipe's client uses the DosCallNPipe function, the function returns error code ERROR_ACCESS_DENIED.

ERROR_BAD_PIPE is returned if you specify an invalid name or file handle.

Example Code

This example shows how to make a call to an existing named pipe.

Before running this example, compile and run the example code shown in the DosConnectNPipe, DosCreateNPipe, DosDisConnectNPipe, or DosSetNPipeSem functions.

#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     outmsg[256]            = "";         /* Output message buffer */
   CHAR     inmsg[256]             = "";         /* Input 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}};

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

   fflush(NULL);   /* Make above printf show on display */
   gets(outmsg);

   rc = DosCallNPipe("\\PIPE\\EXAMPLE",   /* Name of duplex pipe */
                      outmsg,             /* Output message buffer */
                      strlen(outmsg),     /* Size of output message */
                      inmsg,              /* Input message buffer */
                      sizeof(inmsg),      /* Size of input buffer */
                      &bytes,             /* Number of bytes read */
                      30000L);            /* Wait 30 seconds for pipe */
   if (rc != NO_ERROR) {
      printf("DosCallNPipe error: error code = %u\n", rc);
      return 1;
   } else {
      printf("\nMessage received from PIPEHOST: %s\n\n", inmsg);
   } /* endif */

   return NO_ERROR;
}

Related Functions

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