GetNamedPipeHandleStateW function (namedpipeapi.h)

Retrieves information about a specified named pipe. The information returned can vary during the lifetime of an instance of the named pipe.

Syntax

BOOL GetNamedPipeHandleStateW(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPDWORD lpState,
  [out, optional] LPDWORD lpCurInstances,
  [out, optional] LPDWORD lpMaxCollectionCount,
  [out, optional] LPDWORD lpCollectDataTimeout,
  [out, optional] LPWSTR  lpUserName,
  [in]            DWORD   nMaxUserNameSize
);

Parameters

[in] hNamedPipe

A handle to the named pipe for which information is wanted. The handle must have GENERIC_READ access for a read-only or read/write pipe, or it must have GENERIC_WRITE and FILE_READ_ATTRIBUTES access for a write-only pipe.

This parameter can also be a handle to an anonymous pipe, as returned by the CreatePipe function.

[out, optional] lpState

A pointer to a variable that indicates the current state of the handle. This parameter can be NULL if this information is not needed. Either or both of the following values can be specified.

Value Meaning
PIPE_NOWAIT
0x00000001
The pipe handle is in nonblocking mode. If this flag is not specified, the pipe handle is in blocking mode.
PIPE_READMODE_MESSAGE
0x00000002
The pipe handle is in message-read mode. If this flag is not specified, the pipe handle is in byte-read mode.

[out, optional] lpCurInstances

A pointer to a variable that receives the number of current pipe instances. This parameter can be NULL if this information is not required.

[out, optional] lpMaxCollectionCount

A pointer to a variable that receives the maximum number of bytes to be collected on the client's computer before transmission to the server. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

[out, optional] lpCollectDataTimeout

A pointer to a variable that receives the maximum time, in milliseconds, that can pass before a remote named pipe transfers information over the network. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

[out, optional] lpUserName

A pointer to a buffer that receives the user name string associated with the client application. The server can only retrieve this information if the client opened the pipe with SECURITY_IMPERSONATION access.

This parameter must be NULL if the specified pipe handle is to the client end of a named pipe. This parameter can be NULL if this information is not required.

[in] nMaxUserNameSize

The size of the buffer specified by the lpUserName parameter, in TCHARs. This parameter is ignored if lpUserName is NULL.

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.

Remarks

The GetNamedPipeHandleState function returns successfully even if all of the pointers passed to it are NULL.

To set the pipe handle state, use the SetNamedPipeHandleState function.

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.

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 namedpipeapi.h
Library Kernel32.lib
DLL Kernel32.dll

See also

Pipe Functions
Pipes Overview
SetNamedPipeHandleState