[ Home |
Alpha index |
Topic index |
Tutorials |
Download |
Feedback ]
The OS/2 API Project
DosCreateNPipe
[ Syntax |
Params |
Returns |
Include |
Usage |
Structs |
Gotchas |
Code |
Also ]
Syntax
rc = 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 recieve 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 nonblocking 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 bufferspace 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 messagepipe 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 |
Include Info
#define INCL_DOSNMPIPES
#include <os2.h>
Usage Explanation
DosCreateNPipe is used to create a named pipe.
Relevant Structures
Gotchas
Sample Code
#define INCL_DOSNMPIPES
#include
#include
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. */
}
See Also
DosCallNPipe,
DosConnectNPipe,
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 |
DosCreateNPipe |