DosCreateNPipe
DosCreateNPipe is used to create a named pipe.
Syntax
DosCreateNPipe( pszFileName,
phpipePipeHandle,
ulOpenMode,
ulPipeMode,
ulOutBufSize,
ulInBufSize,
ulTimeOut );
Parameters
- PSZ pszFileName (input)
- The name, in ASCIIZ, of the pipe we are going to open. A valid name includes the prefix \PIPE\ and conforms to the naming conventions of the filesystem.
- PHPIPE phpipePipeHandle (output)
- This is a pointer to a variable that will receive the handle of the created pipe.
- ULONG ulOpenMode (input)
- OpenMode contains the following bits:
- 31-16
- Reserved bits.
- 15
- This is a reserved bit, and MUST be 0.
- 14
- Write-through. A value of 0 equals NP_WRITEBEHIND (0x0000) and allows write-behind to remote pipes. A value of 1 equals NP_NOWRITEBEHIND (0x4000) does not allow write-behind to remote pipes. This bit is only meaningful for a remote pipe. It sometimes happens that data written to a remote byte is buffered and sent later to the pipe. Setting the write-through bit will make sure that the data is sent to the pipe as soon as it is written.
- 13-8
- Reserved.
- 7
- Inheritance flag. A value of 0 equals NP_INHERIT (0x0000) and means that the pipe handle is inherited by a child process. A value of 1 equals NP_NOINHERIT (0x0080) and means that the handle is private to the process, and cannot be inherited. This bit is not inherited itself by child processes.
- 6-3
- Reserved bits, and MUST be 0.
- 2-0
- Access mode. It is defined as:
- 000 - NP_ACCESS_INBOUND (0x0000). Inbound pipe (client to server).
- 001 - NP_ACCESS_OUTBOUND (0x0001). Outbound pipe (server to client).
- 010 - NP_ACCESS_DUPLEX (0x0002). Duplex pipe (server to and from client).
- All other values are invalid.
- ULONG ulPipeMode (input)
- Contains the following bits:
- 31-16
- Reserved.
- 15
- Blockingmode. A value of 0 equals NP_WAIT (0x0000) and means blocking mode. DosRead and DosWrite will block if no data is available. A value of 1 equals NP_NOWAIT (0x8000) and means nonblocking mode. This will force DosRead and DosWrite to return at once if no data is available. In blocking mode DosRead will block until at least a part of the data can be returned. DosWrite will block until all the requested data has been written. In non-blocking mode this changes so that DosRead will return at once with the error ERROR_NO_DATA if no data is available. DosWrite will returns at once with BytesWritten set as 0, if the available buffer space in the pipe is not sufficient for the data being written. Otherwise the entire data is written as normal.
- 14-12
- Reserved.
- 11-10
- Type of named pipe. A value of 00 equals NP_TYPE_BYTE (0x0000). Data written to this pipe will be an undifferentiated stream of bytes. A value of 01 equals NP_TYPE_MESSAGE (0x0400). Data written here is written as messages, and the first two bytes of the message (called the message header) contains the size of the message. A header containing zeroes is reserved, and zero-length messages are not allowed.
- 9-8
- Read mode. A value of 00 equals NP_READMODE_BYTE (0x0000) and means read the pipe as byte stream. A value of 01 equals NP_READMODE_MESSAGE (0x0100) and means read the pipe as a message stream. A pipe defined as a message pipe can be read as both message stream or byte stream, depending on the value of the read mode. If the pipe is a byte stream, it must be read as byte stream.
- 7-0
- Instance count. This defines the number of instances, including the first one, that may be created. A value of 1 means the pipe is unique, only one instance allowed. If the value is between, but not equal to, 1 and 255 this is the number of instances that may be created. A value of -1 equals NP_UNLIMITED_INSTANCES (0x00FF) and means that an unlimited number of instances may be created. A value of 0 is reserved. Allowing multiple instances allows multiple clients to connect to the same pipe at the same time.
- ULONG ulOutBufSize (input)
- This tells the system how many bytes it should allocate for the outbound (server to client) buffer.
- ULONG ulInBufSize (input)
- This tells the system how many bytes it should allocate for the inbound (client to server) buffer.
- ULONG ulTimeOut (input)
- This value may be set once only, when the first instance of the pipe is created. The value is the default value for the TimeOut parameter of DosWaitNPipe, and if the value is 0, a default value of 50 (milliseconds) is used.
Returns
- APIRET rc
The following values can be returned:
0 NO_ERROR 3 ERROR_PATH_NOT_FOUND 8 ERROR_NOT_ENOUGH_MEMORY 84 ERROR_OUT_OF_STRUCTURES 87 ERROR_INVALID_PARAMETER 231 ERROR_PIPE_BUSY
Sample Code
#define INCL_DOSNMPIPES
#include <os2.h>
#include <string.h>
UCHAR FileName[40]; /* The pipe name. */
HPIPE PipeHandle; /* The returned pipehandle will be stored here. */
ULONG OpenMode; /* OpenMode parameters. */
ULONG PipeMode; /* Pipemode parameters. */
ULONG OutBufSize; /* Size of the outbuffer. */
ULONG InBufSize; /* Size of the inbuffer. */
ULONG TimeOut; /* Default value for DosWaitNPipe timeout parameter. */
APIRET rc; /* Just to take care of the return code. */
strcpy(FileName, "\\PIPE\\MYPIPE");
OpenMode = NP_ACCESS_DUPLEX;
/* Duplex access to the pipe, no child process inheritance. */
/* Write-through is of no concern since it only affects */
/* remote pipes. */
PipeMode = 0x01 | NP_RMESG | NP_WMESG;
/* Blocking mode. Message streams for both read and write. */
/* Only one instance allowed at a time. */
InBufSize = 2048; /* The size of the incoming data buffer. */
OutBufSize = 2048; /* The size of the outgoing data buffer. */
TimeOut = 1000; /* Timeout is 1 second (1000 milliseconds). */
rc = DosCreateNPipe( FileName, &PipeHandle, OpenMode, PipeMode,
OutBufSize, InBufSize, TimeOut);
if (rc != 0)
{
/* We have an error we must take care of. */
}