CreateNamedPipe
The CreateNamedPipe
function creates an instance of a named pipe and returns a handle for
subsequent pipe operations. A named pipe server process uses this function
either to create the first instance of a specific named pipe and establish its
basic attributes or to create a new instance of an existing named pipe.
HANDLE CreateNamedPipe(
|
LPCTSTR lpName, |
// pointer to pipe
name |
|
DWORD dwOpenMode, |
// pipe open mode |
|
DWORD dwPipeMode, |
// pipe-specific
modes |
|
DWORD nMaxInstances, |
// maximum number
of instances |
|
DWORD nOutBufferSize, |
// output buffer
size, in bytes |
|
DWORD nInBufferSize, |
// input buffer
size, in bytes |
|
DWORD nDefaultTimeOut, |
// time-out time,
in milliseconds |
|
LPSECURITY_ATTRIBUTES lpSecurityAttributes |
// pointer to
security attributes structure |
|
); |
|
Parameters
lpName
Points to the
null-terminated string that uniquely identifies the pipe. The string must have
the following form:
\\.\pipe\pipename
The pipename part of the name can include any character other
than a backslash, including numbers and special characters. The entire pipe
name string can be up to 256 characters long. Pipe names are not case
sensitive.
dwOpenMode
Specifies the
pipe access mode, the overlapped mode, the write-through mode, and the security
access mode of the pipe handle.
This parameter must specify one of the following pipe access mode
flags. The same mode must be specified for each instance of the pipe:
|
Mode |
Description |
|
PIPE_ACCESS_DUPLEX |
The pipe is
bidirectional; both server and client processes can read from and write to
the pipe. This mode gives the server the equivalent of GENERIC_READ | GENERIC_WRITE
access to the pipe. The client can specify GENERIC_READ or GENERIC_WRITE, or
both, when it connects to the pipe using the CreateFile function. |
|
PIPE_ACCESS_INBOUND |
The flow of
data in the pipe goes from client to server only. This mode gives the server
the equivalent of GENERIC_READ access to the pipe. The client must specify
GENERIC_WRITE access when connecting to the pipe. |
|
PIPE_ACCESS_OUTBOUND |
The flow of
data in the pipe goes from server to client only. This mode gives the server
the equivalent of GENERIC_WRITE access to the pipe. The client must specify
GENERIC_READ access when connecting to the pipe. |
This
parameter can also include either or both of the following flags, which enable
write-through mode and overlapped mode. These modes can be different for
different instances of the same pipe.
|
Mode |
Description |
|
FILE_FLAG_WRITE_THROUGH |
|
|
|
Write-through
mode is enabled. This mode affects only write operations on byte-type pipes
and, then, only when the client and server processes are on different
computers. If this mode is enabled, functions writing to a named pipe do not
return until the data written is transmitted across the network and is in the
pipe s buffer on the remote computer. If this mode is not enabled, the system
enhances the efficiency of network operations by buffering data until a
minimum number of bytes accumulate or until a maximum time elapses. |
|
FILE_FLAG_OVERLAPPED |
|
|
|
Overlapped
mode is enabled. If this mode is enabled, functions performing read, write,
and connect operations that may take a significant time to be completed can
return immediately. This mode enables the thread that started the operation
to perform other operations while the time-consuming operation executes in
the background. For example, in overlapped mode, a thread can handle
simultaneous input and output (I/O) operations on multiple instances of a
pipe or perform simultaneous read and write operations on the same pipe
handle. If overlapped mode is not enabled, functions performing read, write,
and connect operations on the pipe handle do not return until the operation
is finished. The ReadFileEx
and WriteFileEx
functions can only be used with a pipe handle in overlapped mode. The ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe functions can execute
either synchronously or as overlapped operations. |
This parameter can include any combination of the following security
access mode flags. These modes can be different for different instances of the
same pipe. They can be specified without concern for what other dwOpenMode
modes have been specified.
|
Mode |
Description |
|
WRITE_DAC |
The caller
will have write access to the named pipe s discretionary access control list
(ACL). |
|
WRITE_OWNER |
The caller
will have write access to the named pipe s owner. |
|
ACCESS_SYSTEM_SECURITY |
The caller
will have write access to the named pipe s system ACL. |
dwPipeMode
Specifies the
type, read, and wait modes of the pipe handle.
One of the following type mode flags can be specified. The same type
mode must be specified for each instance of the pipe. If you specify zero, the
parameter defaults to byte-type mode.
|
Mode |
Description |
|
PIPE_TYPE_BYTE |
Data is
written to the pipe as a stream of bytes. This mode cannot be used with
PIPE_READMODE_MESSAGE. |
|
PIPE_TYPE_MESSAGE |
Data is
written to the pipe as a stream of messages. This mode can be used with
either PIPE_READMODE_MESSAGE or PIPE_READMODE_BYTE. |
One of the
following read mode flags can be specified. Different instances of the same
pipe can specify different read modes. If you specify zero, the parameter
defaults to byte-read mode.
|
Mode |
Description |
|
PIPE_READMODE_BYTE |
Data is
read from the pipe as a stream of bytes. This mode can be used with either
PIPE_TYPE_MESSAGE or PIPE_TYPE_BYTE. |
|
PIPE_READMODE_MESSAGE |
Data is
read from the pipe as a stream of messages. This mode can be only used if
PIPE_TYPE_MESSAGE is also specified. |
One of the following wait mode flags can be specified. Different
instances of the same pipe can specify different wait modes. If you specify
zero, the parameter defaults to blocking mode.
|
Mode |
Description |
|
PIPE_WAIT |
Blocking
mode is enabled. When the pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, the operations
are not completed until there is data to read, all data is written, or a
client is connected. Use of this mode can mean waiting indefinitely in some
situations for a client process to perform an action. |
|
PIPE_NOWAIT |
Nonblocking
mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe
always return immediately. Note that nonblocking mode is supported for
compatibility with Microsoft LAN Manager version 2.0 and should not be used
to achieve asynchronous I/O with named pipes. |
nMaxInstances
Specifies the
maximum number of instances that can be created for this pipe. The same number
must be specified for all instances. Acceptable values are in the range 1
through PIPE_UNLIMITED_INSTANCES. If this parameter is PIPE_UNLIMITED_INSTANCES,
the number of pipe instances that can be created is limited only by the
availability of system resources.
nOutBufferSize
Specifies the
number of bytes to reserve for the output buffer. For a discussion on sizing
named pipe buffers, see the following Remarks section.
nInBufferSize
Specifies the
number of bytes to reserve for the input buffer. For a discussion on sizing
named pipe buffers, see the following Remarks section.
nDefaultTimeOut
Specifies the
default time-out value, in milliseconds, if the WaitNamedPipe function specifies
NMPWAIT_USE_DEFAULT_WAIT. Each instance of a named pipe must specify the same
value.
lpSecurityAttributes
Pointer to a SECURITY_ATTRIBUTES structure that specifies a
security descriptor for the new named pipe and determines whether child processes
can inherit the returned handle. If lpSecurityAttributes is NULL, the
named pipe gets a default security descriptor and the handle cannot be
inherited.
Return Values
If the
function succeeds, the return value is a handle to the server end of a named
pipe instance.
If the
function fails, the return value is INVALID_HANDLE_VALUE. To get extended error
information, call GetLastError. The return value is ERROR_INVALID_PARAMETER if nMaxInstances
is greater than PIPE_UNLIMITED_INSTANCES.
Remarks
To create an
instance of a named pipe by using CreateNamedPipe, the user must have
FILE_CREATE_PIPE_INSTANCE access to the named pipe object. If a new named pipe
is being created, the access control list (ACL) from the security attributes
parameter defines the discretionary access control for the named pipe.
All instances
of a named pipe must specify the same pipe type (byte-type or message-type),
pipe access (duplex, inbound, or outbound), instance count, and time-out value.
If different values are used, this function fails and GetLastError
returns ERROR_ACCESS_DENIED.
The input and
output buffer sizes are advisory. The actual buffer size reserved for each end
of the named pipe is either the system default, the system minimum or maximum,
or the specified size rounded up to the next allocation boundary.
An instance
of a named pipe is always deleted when the last handle to the instance of the
named pipe is closed.
See Also