CreateNamedPipeW function

CreateNamedPipeW enables an enhanced version of the named pipes. Enhanced named pipes provide more control over pipe behavior and security.

For Windows Server 2008 R2 and Windows 7: The default behavior of named pipes changes when the application is compiled with the correct SDK. For more information, see "About Named Pipes". 


HANDLE CreateNamedPipeW(
  LPCWSTR lpName,
  DWORD   dwOpenMode,
  DWORD   dwPipeMode,
  DWORD   nMaxInstances,
  DWORD   nOutBufferSize,
  DWORD   pInBufferSize,
  DWORD   nDefaultTimeout,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Syntax

Parameter Description
lpName

The name of the named pipe. This member can be an arbitrary string of characters. Use the format:

\\.\pipe\pipe-name

If the string does not begin with the specified prefix, the function fails. If lpName is NULL or an empty string, CreateNamedPipeW fails with the error code ERROR_INVALID_NAME.
dwOpenMode

The trasmit mode and access mode of the pipe. This parameter can be a combination of the following values:

  • PIPE_ACCESS_INBOUND: Allows client applications to read from the pipe.
  • PIPE_ACCESS_OUTBOUND: Allows client applications to write to the pipe.
  • PIPE_ACCESS_DUPLEX: Allows client applications to both read from and write to the pipe.
  • FILE_FLAG_FIRST_PIPE_INSTANCE: Indicates that the pipe is the first instance to be created.
  • FILE_FLAG_OVERLAPPED: Indicates that the pipe is opened for overlapped mode.
dwPipeMode

The pipe's transmission mode and read/write modes. This parameter can be a combination of the following values:

  • PIPE_TYPE_BYTE: Data is transmitted through the pipe as a stream of bytes.
  • PIPE_TYPE_MESSAGE: Data is transmitted through the pipe as messages.
  • PIPE_READMODE_BYTE: Data is read from the pipe as a stream of bytes.
  • PIPE_READMODE_MESSAGE: Data is read from the pipe as messages.
  • PIPE_WAIT: Blocking mode is enabled.
  • PIPE_NOWAIT: Nonblocking mode is enabled.
nMaxInstances

The maximum number of instances that can be created for this pipe. The first instance can be named \\.\pipe\pipe-name, the second \\.\pipe\pipe-name1, and so on.

This parameter must be a positive number. The value 2147483647 (MAX_PIPE_SIZE) means that unlimited instances can be created.
nOutBufferSize

The recommended buffer size in bytes for the output buffer of the pipe. If this parameter is zero, the system uses the default buffer size.
nInBufferSize

The recommended buffer size in bytes for the input buffer of the pipe. If this parameter is zero, the system uses the default buffer size.
nDefaultTimeout

The default timeout in milliseconds for calls to the ReadFile and WriteFile functions when they are blocking. A value of 0 indicates that the default timeout should be used. A value of INFINITE indicates that the timeout will not expire.
lpSecurityAttributes

A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the pipe. If this parameter is NULL, the pipe gets a default security descriptor.

Return Value

If the function succeeds, the return value is an open handle to an instance of the named pipe. If the function fails, the return value is INVALID_HANDLE_VALUE. To get error information, call GetLastError.

Return Value Description
INVALID_HANDLE_VALUE An error occurred. Call GetLastError for more information.

Remarks

The CreateNamedPipeW function creates a named pipe server. A named pipe is a communication channel that is created on a network. Named pipes can be used for one-way or two-way communication between processes.

When a named pipe is created, it is assigned a name that is visible to the operating system. Client applications can use this name to connect to the pipe.

Named pipes can be created in either byte mode or message mode. In byte mode, data is transmitted as a stream of bytes. In message mode, data is transmitted as discrete messages.

Named pipes can be created in blocking mode or nonblocking mode. In blocking mode, calls to ReadFile and WriteFile will block until the operation is complete. In nonblocking mode, these calls will return immediately, even if the operation is not yet complete.

The FILE_FLAG_OVERLAPPED flag enables overlapped I/O for the pipe, allowing multiple read and write operations to be in progress simultaneously.

Requirements

Interface Value
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header namedpipeapi.h (include windows.h)
Library Kernel32.lib
DLL Kernel32.dll
Unicode and ANSI Versions CreateNamedPipeW (Unicode) and CreateNamedPipeA (ANSI)

See Also