GetNamedPipeHandleStateA 函数 (winbase.h)

  • 项目

检索有关指定命名管道的信息。 在命名管道实例的生存期内，返回的信息可能会有所不同。

语法

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

参数

[in] hNamedPipe

需要其信息的命名管道的句柄。 句柄必须对只读管道或读/写管道具有GENERIC_READ访问权限，或者必须对只读管道具有GENERIC_WRITE和FILE_READ_ATTRIBUTES访问权限。

此参数也可以是匿名管道的句柄，由 CreatePipe 函数返回。

[out, optional] lpState

指向变量的指针，该变量指示句柄的当前状态。 如果不需要此信息，此参数可以为 NULL 。 可以指定以下值之一或两个值。

值 含义
PIPE_NOWAIT
0x00000001
 管道句柄处于非阻塞模式。 如果未指定此标志，则管道句柄处于阻止模式。
PIPE_READMODE_MESSAGE
0x00000002
 管道句柄处于消息读取模式。 如果未指定此标志，则管道句柄处于字节读取模式。

[out, optional] lpCurInstances

指向接收当前管道实例数的变量的指针。 如果不需要此信息，此参数可以为 NULL 。

[out, optional] lpMaxCollectionCount

指向变量的指针，该变量接收在传输到服务器之前客户端计算机上要收集的最大字节数。 如果指定的管道句柄位于命名管道的服务器端，或者客户端和服务器进程位于同一台计算机上，则此参数必须为 NULL 。 如果不需要此信息，此参数可以为 NULL 。

[out, optional] lpCollectDataTimeout

指向变量的指针，该变量接收远程命名管道通过网络传输信息之前可以传递的最长时间（以毫秒为单位）。 如果指定的管道句柄位于命名管道的服务器端，或者客户端和服务器进程位于同一台计算机上，则此参数必须为 NULL 。 如果不需要此信息，此参数可以为 NULL 。

[out, optional] lpUserName

指向接收与客户端应用程序关联的用户名字符串的缓冲区的指针。 仅当客户端使用SECURITY_IMPERSONATION访问权限打开管道时，服务器才能检索此信息。

如果指定的管道句柄位于命名管道的客户端端，则此参数必须为 NULL 。 如果不需要此信息，此参数可以为 NULL 。

[in] nMaxUserNameSize

lpUserName 参数指定的缓冲区的大小（以 TCHAR 为单位）。 如果 lpUserName 为 NULL，则忽略此参数。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

注解

即使传递给它的所有指针均为 NULL，GetNamedPipeHandleState 函数也会成功返回。

若要设置管道句柄状态，请使用 SetNamedPipeHandleState 函数。

Windows 10版本 1709：管道仅在应用容器中受支持;即，从一个 UWP 进程到属于同一应用的另一个 UWP 进程。 此外，命名管道必须为管道名称使用 语法 \\.\pipe\LOCAL\ 。

要求

要求 值
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 winbase.h (包括 Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

管道函数

管道概述

SetNamedPipeHandleState