SetNamedPipeHandleState 函数 (namedpipeapi.h)

项目
03/13/2024

设置指定命名管道的读取模式和阻止模式。如果指定的句柄位于命名管道的客户端端，并且命名管道服务器进程位于远程计算机上，则函数也可用于控制本地缓冲。

语法

BOOL SetNamedPipeHandleState(
  [in]           HANDLE  hNamedPipe,
  [in, optional] LPDWORD lpMode,
  [in, optional] LPDWORD lpMaxCollectionCount,
  [in, optional] LPDWORD lpCollectDataTimeout
);

参数

[in] hNamedPipe

命名管道实例的句柄。此参数可以是由 CreateNamedPipe 函数返回的管道服务器端的句柄，也可以是由 CreateFile 函数返回的管道客户端的句柄。句柄必须具有GENERIC_WRITE对只读或读/写管道的命名管道的访问权限，或者必须对只读管道具有GENERIC_READ和FILE_WRITE_ATTRIBUTES访问权限。

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

[in, optional] lpMode

新的管道模式。该模式是读取模式标志和等待模式标志的组合。如果未设置模式，此参数可以为 NULL 。指定以下模式之一。

模型	含义
PIPE_READMODE_BYTE 0x00000000	数据作为字节流从管道中读取。如果未指定读取模式标志，则此模式为默认值。
PIPE_READMODE_MESSAGE 0x00000002	数据作为消息流从管道中读取。如果为字节类型管道指定了此标志，则函数将失败。

可以指定以下等待模式之一。

模型	含义
PIPE_WAIT 0x00000000	启用阻止模式。如果未指定等待模式标志，则此模式为默认值。在 ReadFile、 WriteFile 或 ConnectNamedPipe 函数中指定阻止模式管道句柄时，操作在有要读取的数据、写入所有数据或连接客户端之前不会完成。在某些情况下，使用此模式意味着无限期等待客户端进程执行操作。
PIPE_NOWAIT 0x00000001	启用非阻止模式。在此模式下， ReadFile、 WriteFile 和 ConnectNamedPipe 始终立即返回。请注意，非阻止模式支持与 Microsoft LAN Manager 版本 2.0 兼容，不应用于使用命名管道实现异步输入和输出 (I/O) 。

[in, optional] lpMaxCollectionCount

传输到服务器之前在客户端计算机上收集的最大字节数。如果指定的管道句柄位于命名管道的服务器端，或者客户端和服务器进程位于同一台计算机上，则此参数必须为 NULL 。如果客户端进程在创建句柄时在 CreateFile 函数中指定FILE_FLAG_WRITE_THROUGH标志，则忽略此参数。如果未设置集合计数，此参数可以为 NULL 。

[in, optional] lpCollectDataTimeout

远程命名管道通过网络传输信息之前可能经过的最长时间（以毫秒为单位）。如果指定的管道句柄位于命名管道的服务器端，或者客户端和服务器进程位于同一台计算机上，则此参数必须为 NULL 。如果客户端进程在创建句柄时在 CreateFile 函数中指定了 FILE_FLAG_WRITE_THROUGH 标志，则忽略此参数。如果未设置集合计数，此参数可以为 NULL 。

返回值

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

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

注解

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

示例

有关示例，请参阅命名管道客户端。

要求

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