DosCallNPipe: Difference between revisions

Revision as of 16:37, 20 June 2016

Description

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