CallNamedPipeA function (winbase.h)

Article
02/02/2023

Connects to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and then closes the pipe.

Syntax

BOOL CallNamedPipeA(
  [in]  LPCSTR  lpNamedPipeName,
  [in]  LPVOID  lpInBuffer,
  [in]  DWORD   nInBufferSize,
  [out] LPVOID  lpOutBuffer,
  [in]  DWORD   nOutBufferSize,
  [out] LPDWORD lpBytesRead,
  [in]  DWORD   nTimeOut
);

Parameters

[in] lpNamedPipeName

The pipe name.

[in] lpInBuffer

The data to be written to the pipe.

[in] nInBufferSize

The size of the write buffer, in bytes.

[out] lpOutBuffer

A pointer to the buffer that receives the data read from the pipe.

[in] nOutBufferSize

The size of the read buffer, in bytes.

[out] lpBytesRead

A pointer to a variable that receives the number of bytes read from the pipe.

[in] nTimeOut

The number of milliseconds to wait for the named pipe to be available. In addition to numeric values, the following special values can be specified.

Value	Meaning
NMPWAIT_NOWAIT 0x00000001	Does not wait for the named pipe. If the named pipe is not available, the function returns an error.
NMPWAIT_WAIT_FOREVER 0xffffffff	Waits indefinitely.
NMPWAIT_USE_DEFAULT_WAIT 0x00000000	Uses the default time-out specified in a call to the CreateNamedPipe function.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If the message written to the pipe by the server process is longer than nOutBufferSize, CallNamedPipe returns FALSE, and GetLastError returns ERROR_MORE_DATA. The remainder of the message is discarded, because CallNamedPipe closes the handle to the pipe before returning.

Remarks

Calling CallNamedPipe is equivalent to calling the CreateFile (or WaitNamedPipe, if CreateFile cannot open the pipe immediately), TransactNamedPipe, and CloseHandle functions. CreateFile is called with an access flag of GENERIC_READ | GENERIC_WRITE, and an inherit handle flag of FALSE.

CallNamedPipe fails if the pipe is a byte-type pipe.

Windows 10, version 1709: Pipes are only supported within an app-container; ie, from one UWP process to another UWP process that's part of the same app. Also, named pipes must use the syntax \\.\pipe\LOCAL\ for the pipe name.

Examples

For an example, see Transactions on Named Pipes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	winbase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll