DosCallNPipe
Makes a procedure call to a duplex message pipe.
Syntax
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; }