[ Home | Alpha index | Topic index | Tutorials | Download | Feedback ]

The OS/2 API Project

DosCallNPipe

[ Syntax | Params | Returns | Include | Usage | Structs | Gotchas | Code | Also ]

Syntax

 rc = DosCallNPipe( pszFileName, pInBuffer, ulInBufferLen, pOutBuffer, ulOutBufferLen, pBytesOut, ulTimeOut );

Parameters
PSZ pszFileName (input)
This is the name, in ASCIIZ, of the pipe we are going to open. A valid pipe name must include the prefix \PIPE\, and must conform to the normal naming conventions of the filesystem. If you are going to use the pipe to communicate to a remote process you must also include the computername, using \\computername\PIPE\filename.

PVOID pInBuffer (input)
This is a pointer the buffer we are going to use to write to the pipe.

ULONG ulInBufferLen (input)
The number of bytes we are going to write to the pipe.

PVOID pOutBuffer (output)
This is a pointer to a buffer in which to store returned data.

ULONG ulOutBufferLen (input)
This is the maximum size, given in bytes, of the returned data.

PULONG pBytesOut (output)
A pointer to a longword, which upon return will contain the size of returned data, in bytes. This is included since the maximum size of data we can recieve usually is different from the size actually recieved.

ULONG ulTimeOut (input)
The maximum time, given in milliseconds, to wait for a pipe to become available.

Returns
APIRET rc
The following values can be returned
0NO_ERROR
2ERROR_FILE_NOT_FOUND
11ERROR_BAD_FORMAT
95ERROR_INTERRUPT
230ERROR_BAD_PIPE
231ERROR_PIPE_BUSY
233ERROR_PIPE_NOT_CONNECTED
234ERROR_MORE_DATA

Include Info

 #define INCL_DOSNMPIPES
#include <os2.h>

Usage Explanation

 DosCallNPipe is used for a duplex message pipe, and combines DosOpen, DosTransactNPipe and DosClose into a single function.

If you use this function on a pipe that is not a duplex message pipe, the system will return ERROR_BAD_FORMAT.

If no instances of a pipe is available, DosCallNPipe will wait for a specified time, and if the time elapses will return ERROR_INTERRUPT.

DosCallNPipe will return ERROR_FILE_NOT_FOUND if an invalid pipe name is specified.

ERROR_MORE_DATA will be returned if the outbuffer is too small to contain the returned data.

If DosConnectNPipe has not been issued by the server to set the pipe listening, DosCallNPipe will return ERROR_PIPE_BUSY.

Relevant Structures

Gotchas

Sample Code

 #define INCL_DOSNMPIPES #include <os2.h> #include <stdio.h> UCHAR FileName[40]; /* Will contain the pipe name */ UCHAR InBuffer[800]; /* The input buffer. */ ULONG InBufferLen; /* Will contain the size of the input-buffer. */ UCHAR OutBuffer[800]; /* The output buffer. There is nothing that says */ /* it has to have the same size as the input buffer, */ /* this is just for our example. */ ULONG OutBufferLen; /* Will contain the length of the output buffer */ ULONG BytesOut; /* Will, upon return, hold the actual number of bytes read. */ ULONG TimeOut; /* The specified maximum wait time. */ APIRET rc; /* Just to take care of the return code. */ strcpy(FileName,"\\PIPE\\MYPIPE"); strcpy(InBuffer,"Command: Start email-program"); /* We copy to the input buffer the data we want to send. */ /* It should of course be something the reciever can make */ /* sense of, and the above is just an example. */ InBufferLen = strlen(InBuffer); /* We have the system calculate the number of bytes to send. */ /* This will not be 800 bytes as we specified when we */ /* created the inbuffer. Instead it will be the length */ /* of the data we are sending. */ OutBufferLen = 800; /* We can recieve 800 bytes though. */ TimeOut = 1000; /* We wait for 1 second (1000 milliseconds). */ rc = DosCallNPipe(FileName, InBuffer, InBufferLen, OutBuffer, OutBufferLen, &BytesOut, TimeOut); if (rc != 0) { /* We have an error we must take care of. */ }

See Also

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

Author

Stefan Mars - mars@lysator.liu.se

Additions

Last modified March 17/1996
Please send all errors, comments, and suggestions to: timur@vnet.ibm.com

The OS/2 API Project

DosCallNPipe