DosCreateNPipe - 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.

pHpipe (PHPIPE) - output

A pointer to the variable in which the system returns the handle of the pipe that is created.

openmode (ULONG) - input

A set of flags defining the mode in which to open the pipe.

This parameter contains the following bit fields:

Bit

Description
31-16
Reserved.
15
Reserved and must be 0.
14
Write-through bit. Possible values are shown in the following list:
• NP_WRITEBEHIND (0x0000) Write-behind to remote pipes is allowed.

• NP_NOWRITEBEHIND (0x4000)
  Write-behind to remote pipes is not allowed.

  This bit 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.
7
Inheritance flag. Possible values are shown in the following list:
• NP_INHERIT (0x0000)
  The pipe handle is inherited by a child process.

• NP_NOINHERIT (0x0080)
  The pipe handle is private to the current process and cannot be inherited.

  This bit is not inherited by child processes.

6-3
Reserved and must be 0.
2-0
Access mode. The pipe access is defined as shown in the following list:

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).
Any other value is invalid.

pipemode (ULONG) - input

A set of flags defining the mode of the pipe.

This parameter contains the following bit fields:

Bit

Description
31-16
Reserved.
15
Blocking mode. Blocking mode is defined as either "blocking" or "nonblocking," as follows:
• NP_WAIT (0x0000) Blocking mode: DosRead and DosWrite block if no data is available.

• NP_NOWAIT = NP_NBLK (0x8000)
  Nonblocking mode: DosRead and DosWrite return immediately if no data is available.

  DosRead normally blocks until at least partial data can be returned. DosWrite blocks by default until all of the requested bytes have been written. Nonblocking mode changes this behavior as following:

  DosRead returns immediately with ERROR_NO_DATA if no data is available.

  DosWrite returns immediately with a value of 0 for pcbActual if there is not enough buffer space available in the pipe; otherwise, the entire data area is transferred.

14-12
Reserved.
11-10
Type of named pipe. The pipe type is defined as follows:

00

NP_TYPE_BYTE (0x0000)
The pipe is a byte pipe; that is, data is written to the pipe as an undifferentiated stream of bytes.
01
NP_TYPE_MESSAGE = NP_WMESG (0x0400)
The pipe is a message pipe; that is, data is written to the pipe as messages. The system records the length of each message in the first two bytes of the message, which are called the message header. A header of all zeroes is reserved, and zero-length messages are not allowed.
9-8
Read mode. The read mode is defined as follows:

00

NP_READMODE_BYTE (0x0000)
Byte-read mode: Read the pipe as a byte stream.
01
NP_READMODE_MESSAGE = NP_RMESG (0x0100)
Message-read mode: Read the pipe as a message stream.
Message pipes can be read as either byte streams or message streams, depending on the value of this bit. Byte pipes can be read only as byte streams.
7-0
ICount (Instance count). When the first instance of a named pipe is created, ICount specifies how many instances (including the first instance) may be created. Possible values are shown in the following list:
• This is the only instance permitted (the pipe is unique).

• < value < 255
  The number of instances is limited to the value specified.
  -1
  NP_UNLIMITED_INSTANCES (0x00FF)
  The number of instances is unlimited.
  0
  Reserved value.
  ICount is ignored when specifying any instance of a pipe other than the first one. Subsequent attempts to create a pipe instance fail if the maximum number of allowed instances already exists. When multiple instances are allowed, multiple clients can simultaneously open the same pipe name; they will receive handles to distinct pipe instances.

cbOutbuf (ULONG) - input

The number of bytes to allocate for the outbound (server to client) buffer.

cbInbuf (ULONG) - input

The number of bytes to allocate for the inbound (client to server) buffer.

msec (ULONG) - input

The maximum time, in milliseconds, to wait for a named-pipe instance to become available.

This is the default value for the msec parameter of DosWaitNPipe.

This value may be set only when the first instance of the pipe name is being created. If the value is 0, a system-wide default value (50 ms) is chosen.

ulrc (APIRET) - returns

Return Code.

DosCreateNPipe returns one of the following values:

• 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
  On the PowerPC platform, DosCreateNPipe 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 DosCreateNPipe to fail:

    \pipe\\\\\longname.nam

  For a full list of error codes, see Errors.

---

[Back: DosCreateNPipe Return Value - ulrc]
[Next: DosCreateNPipe - Related Functions]