![[Toc]](../../toc.gif)
![[Index]](/idx.gif)
DosMakeNmPipe
Bindings: C, MASM
This call creates the specified named pipe and returns its handle.
DosMakeNmPipe (PipeName, PipeHandle, OpenMode, PipeMode,
OutBufSize, InBufSize, TimeOut)
PipeName (PSZ) - input
Address of the ASCIIZ name of the pipe to be opened. Pipes are named
\PIPE\PipeName.
PipeHandle (PHPIPE) - output
Address of the handle of the named pipe that is created.
OpenMode (USHORT) - input
The OpenMode parameter contains the following bit fields:
Bit Description
15 Reserved and must be zero.
14 Write-Through flag: The file is opened as follows:
0 = Write-behind to remote pipes is allowed.
1 = Write-behind to remote pipes is not allowed.
Setting the Write-Through flag is meaningful only for a
remote pipe. Occasionally, data written to a remote pipe is
buffered locally and then sent across the network to the
pipe at a later time. Setting the Write-Through bit ensures
that data is sent to the remote pipe as soon as it is
written.
13-8 Reserved and must be zero.
7 Inheritance flag: The file handle is as follows:
0 = Pipe handle is inherited by a spawned process resulting
from a DosExecPgm call.
1 = Pipe handle is private to the current process and cannot
be inherited.
6-2 Reserved and must be zero.
1-0 Access field: The pipe access is assigned as follows:
00 = In-bound pipe (client to server)
01 = Out-bound pipe (server to client)
10 = Duplex pipe (server to/from client)
Any other value is invalid.
PipeMode (USHORT) - input
The PipeMode parameter contains the following bit fields:
Bit Description
15 Blocking flag: The pipe is defined as follows:
0 = Reads/Writes block if no data available.
1 = Reads/Writes return immediately if no data available.
Reads normally block until at least partial data can be
returned. Writes by default block until all bytes requested
have been written. Non-blocking mode (1) changes this
behavior as follows:
DosRead returns immediately with error NO_DATA if no data is
available.
DosWrite returns immediately with BytesWritten = 0 if
insufficient buffer space is available in the pipe or the
entire data area is transferred.
14-11 Reserved and must be zero.
10 Type of named pipe: The pipe is defined as follows:
0 = Pipe is a byte stream pipe.
1 = Pipe is a message stream pipe.
All writes to message stream pipes record the length of the
write along with the written data (see DosWrite). The first
two bytes of each message represents the length of that
message and is called the message header. A header of all
zeros is reserved. Zero length messages are not allowed
(OS/2 no-ops zero-length I/Os).
9 Reserved and must be zero.
8 Read mode: The pipe is defined as follows:
0 = Read pipe as a byte stream.
1 = Read pipe as a message stream.
Message pipes can be read as byte or message streams,
depending on this bit. Byte pipes can only be read as byte
streams (see DosRead)
7-0 ICount field (Instance count): Byte wide (8-bit) count to
control pipe instances. When making the first instance of a
named pipe, ICount specifies how many instances can be
created. Instances are as follows:
Value Definition
1 This can be the only instance (pipe is unique).
1 < value < 255 The number of instances is limited to the value
specified.
-1 The number of instances is unlimited.
0 Reserved value.
Subsequent attempts to make a pipe fails if the maximum
number of allowed instances already exists. The ICount
parameter is ignored when making any other than the first
instance of a pipe. When multiple instances are allowed,
multiple clients can simultaneously issue DosOpen to the
same pipe name and get handles to distinct pipe instances.
OutBufSize (USHORT) - input
An advisory to the system of the number of bytes to allocate for the
outgoing buffer.
InBufSize (USHORT) - input
An advisory to the system of the number of bytes to allocate for the
incoming buffer.
TimeOut (ULONG) - input
Default value for the TimeOut parameter to DosWaitNmPipe. This value
may be set only at the creation of the first instance of the pipe
name. If the value is zero, a system wide default value (50 ms) is
chosen.
rc (USHORT) - return
Return code descriptions are:
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
Remarks
A named pipe provides two-way communication between a server process and
a number of client processes. In addition, the named pipe can have
multiple instances created by multiple server processes.
The server creates the pipe with DosMakeNmPipe. The ICount parameter is
significant only for the first instance created of the named pipe. The
ASCIIZ name string specified for the named pipe must include the prefix
\PIPE\.
After creating the named pipe, the server issues DosConnectNmPipe to wait
for a client to open the pipe with DosOpen. If all instances of a named
pipe are busy, a client process can issue DosWaitNmPipe and wait for an
instance to become available before it reissues DosOpen. A client can
determine whether the pipe is ready to accept a DosOpen by issuing
DosPeekNmPipe to return the pipe's state.
Server and client processes communicate by issuing DosRead,
DosReadAsync, DosWrite, and DosWriteAsync calls. DosBufReset can be
used to to synchronize read and write dialogs. A server process that need
to support a large number of clients for a local named pipe can
coordinate access to the pipe with DosSetNmPipeSem and DosQNmPipeSemState
calls.
Server and client processes can also communicate by means of transaction
and procedure calls. DosTransactNmPipe and DosCallNmPipe are supported
only for duplex message pipes.
Issuing DosClose ends the client's access to the named pipe. To prepare
the pipe for its next client, the server process issues
DosDisConnectNmPipe followed by DosConnectNmPipe.
When all handles to one end of the pipe are closed, the pipe is
considered broken. If the pipe is broken and the server issues DosClose,
the pipe is immediately deallocated.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs