CreateNamedPipe

HANDLE CreateNamedPipe(lpszPipeName, fdwOpenMode, fdwPipeMode, nMaxInstances, cbOutBuf, cbInBuf, dwTimeout, lpsa)
LPTSTR lpszPipeName;	/* pipe name	*/
DWORD fdwOpenMode;	/* pipe open mode	*/
DWORD fdwPipeMode;	/* pipe-specific modes	*/
DWORD nMaxInstances;	/* maximum number of instances	*/
DWORD cbOutBuf;	/* out buffer size in bytes	*/
DWORD cbInBuf;	/* in buffer size in bytes	*/
DWORD dwTimeout;	/* timeout time in milliseconds	*/
LPSECURITY_ATTRIBUTES lpsa;	/* optional security attributes	*/

The CreateNamedPipe function creates an instance of a named pipe and returns a handle that can be used in subsequent pipe operations.

Parameters

lpszPipeName

Points to the null-terminated string that identifies the pipe. The string must have the following form:

\\.\pipe\pipename

The pipename portion must have the same format as a standard Win32 filename and must be unique. The name may include multiple levels of pseudo-directories separated by backslashes. For example, \\.\pipe\example or \\.\pipe\abc\def\ghi are valid names.

fdwOpenMode

Specifies the modes with which to open the pipe. This parameter is a combination of an access-mode flag, an overlapped flag, and a write-through flag. The same access mode flag must be specified for each instance of the pipe. The possible values are as follows:

Value

Meaning

PIPE_ACCESS_DUPLEX	Pipe is bidirectional. This gives the server the equivalent of GENERIC_READ \| GENERIC_WRITE access to the pipe.
PIPE_ACCESS_INBOUND	Data goes from client to server only. This gives the server the equivalent of GENERIC_READ access to the pipe. The client must open its end of the pipe with GENERIC_WRITE access.
PIPE_ACCESS_OUTBOUND	Data goes from server to client only. This gives the server the equivalent of GENERIC_WRITE access to the pipe. The client must open its end of the pipe with GENERIC_READ access.
FILE_FLAG_WRITE_THROUGH	The redirector is not permitted to delay the transmission of data to the named pipe buffer on the remote server. This disables a performance enhancement for applications that need synchronization with every write operation.
FILE_FLAG_OVERLAPPED	Indicates that the system should initialize the pipe so that overlapped (or asynchronous) operations are enabled. This must be enabled for the ReadFileEx and WriteFileEx functions to be used on the pipe, and for the ReadFile, WriteFile, ConnectNamedPipe and TransactNamedPipe operations to be performed asynchronously by specifying an OVERLAPPED structure. Overlapped I/O allows operations that may take a significant time to return immediately, allowing the application to do other processing. Specifying FILE_FLAG_OVERLAPPED also enables more than one operation to be performed simultaneously with the handle (a simultaneous read and write, for example).

fdwPipeMode

Specifies the pipe-specific modes of the pipe. This parameter is a combination of a read-mode flag, a type flag, and a wait flag. If zero is specified, the pipe defaults to PIPE_WAIT | PIPE_TYPE_BYTE | PIPE_READMODE_BYTE. The same type must be specified for each instance of the pipe, but different instances can have different wait modes and readmodes. The possible values are as follows:

Value

Meaning

PIPE_WAIT	Functions that access the pipe will block until there is data to read, all data has been written, or a client is ready to connect.
PIPE_NOWAIT	Functions that access the pipe will return immediately if there is no data to read, after writing as many bytes as possible, or if no client is waiting to connect.
PIPE_TYPE_BYTE	Pipe is a byte-stream pipe. This flag cannot be used with PIPE_READMODE_MESSAGE.
PIPE_TYPE_MESSAGE	Pipe is a message-stream pipe.
PIPE_READMODE_BYTE	Read pipe as a byte stream.
PIPE_READMODE_MESSAGE	Read pipe as a message stream. This flag can only be used if PIPE_TYPE_MESSAGE is also specified.

nMaxInstances

Gives the maximum number of instances for this pipe. Acceptable values are from 1 to PIPE_UNLIMITED_INSTANCES. If this parameter is PIPE_UNLIMITED_INSTANCES, the number of pipes that can be created is limited only by the availability of system resources.

cbOutBuf

Specifies the number of bytes to reserve for the outgoing buffer. If zero is specified, the buffer is allocated as needed.

cbInBuf

Specifies the number of bytes to reserve for the incoming buffer. If zero is specified, the buffer is allocated as needed.

dwTimeout

Specifies the default time-out value (in milliseconds) that will be used if the WaitNamedPipe function specifies NMPWAIT_USE_DEFAULT_WAIT. Each instance of a named pipe must specify the same value.

lpsa

Points to a SECURITY_ATTRIBUTES data structure that specifies the security attributes for the pipe. The file system must support this parameter for it to have an effect.

The SECURITY_ATTRIBUTES structure has the following format:

typedef struct _SECURITY_ATTRIBUTES { /* sa */

DWORD nLength;

LPVOID lpSecurityDescriptor;

BOOL bInheritHandle;

} SECURITY_ATTRIBUTES;

If lpsa is NULL, the pipe is created without a security descriptor, and the pipe handle is not inherited by child processes.

Return Value

The return value is a handle to the server side of a named pipe if the function is successful. Otherwise, it is (HANDLE)0xFFFFFFFF. Use the GetLastError function to obtain extended error information.

Comments

This function either creates the first instance of a specific named pipe and establishes its basic attributes or creates a new instance of an existing named pipe which inherits the attributes of the first instance of the named pipe. To create an instance of a named pipe the user must have FILE_CREATE_PIPE_INSTANCE access to the named pipe object. If a new named pipe is being created, then 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 use the same pipe type (byte or message mode), pipe access (duplex, inbound, or outbound), instance count and timeout time. If different values are used, this function will fail and the GetLastError function will return ERROR_ACCESS_DENIED.

The in and out buffer sizes are advisory. The actual buffer size that is reserved for each side of the named pipe is either the system default, the system minimum, the system 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.

The CreateNamedPipe function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).