ConnectNamedPipe 函数（namedpipeapi.h）

项目
11/20/2024

使命名管道服务器进程能够等待客户端进程连接到命名管道的实例。客户端进程通过调用 CreateFile 或 CallNamedPipe 函数进行连接。

语法

BOOL ConnectNamedPipe(
  [in]                HANDLE       hNamedPipe,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

参数

[in] hNamedPipe

命名管道实例的服务器端的句柄。此句柄由 CreateNamedPipe 函数返回。

[in, out, optional] lpOverlapped

指向重叠结构的指针。

如果使用 FILE_FLAG_OVERLAPPED 打开了 hNamedPipe，则 lpOverlapped 参数不得 NULL。它必须指向有效的重叠结构。如果使用 FILE_FLAG_OVERLAPPED 打开了 hNamedPipe，并且 lpOverlappedNULL，则该函数可能会错误地报告连接操作已完成。

如果使用 FILE_FLAG_OVERLAPPED 创建了 hNamedPipe，并且 lpOverlapped 未 NULL，则 OVERLAPPED 结构应包含手动重置事件对象的句柄（服务器可以使用 CreateEvent 函数创建）。

如果未使用 FILE_FLAG_OVERLAPPED 打开 hNamedPipe，则在客户端连接或发生错误之前，该函数不会返回。如果客户端在调用函数后连接，则成功同步操作会导致函数返回非零值。

返回值

如果操作是同步的，ConnectNamedPipe 在操作完成之前不会返回。如果函数成功，则返回值为非零。如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

如果操作是异步的，ConnectNamedPipe 会立即返回。如果操作仍在挂起，则返回值为零，GetLastError 返回ERROR_IO_PENDING。（可以使用 HasOverlappedIoCompleted 宏来确定操作完成的时间。如果函数失败，则返回值为零，GetLastError 返回除ERROR_IO_PENDING或ERROR_PIPE_CONNECTED以外的值。

如果在调用函数之前客户端连接，该函数将返回零，GetLastError 返回ERROR_PIPE_CONNECTED。如果客户端在 CreateNamedPipe 的调用与 ConnectNamedPipe的调用之间进行连接，则可能会发生这种情况。在这种情况下，客户端和服务器之间存在良好的连接，即使该函数返回零。

言论

命名管道服务器进程可以将 ConnectNamedPipe 与新创建的管道实例配合使用。它还可与以前连接到另一个客户端进程的实例一起使用;在这种情况下，服务器进程必须首先调用 DisconnectNamedPipe 函数，才能将句柄与上一个客户端断开连接，然后才能将句柄重新连接到新客户端。否则，ConnectNamedPipe 返回零，GetLastError 如果上一个客户端已关闭其句柄或ERROR_PIPE_CONNECTED（如果尚未关闭其句柄）则返回ERROR_NO_DATA。

ConnectNamedPipe 的行为取决于两个条件：管道句柄的等待模式是设置为阻止还是非阻止，以及函数是设置为同步执行还是处于重叠模式。服务器最初在 createNamedPipe 函数指定管道句柄的等待模式，并且可以使用 SetNamedPipeHandleState 函数对其进行更改。

服务器进程可以使用任何等待函数或 SleepEx— 以确定事件对象的状态何时发出信号，然后可以使用 HasOverlappedIoCompleted 宏来确定 ConnectNamedPipe 操作何时完成。

如果指定的管道句柄处于非阻止模式，ConnectNamedPipe 始终会立即返回。在非阻止模式下，ConnectNamedPipe 首次为与上一个客户端断开连接的管道实例调用它时返回非零值。这表示管道现在可用于连接到新的客户端进程。在管道句柄处于非阻止模式的所有其他情况下，ConnectNamedPipe 返回零。在这些情况下，GetLastError 在未连接客户端时返回ERROR_PIPE_LISTENING，如果客户端已连接，则ERROR_PIPE_CONNECTED，如果上一个客户端已关闭其管道句柄，但服务器未断开连接，ERROR_NO_DATA。请注意，客户端和服务器之间的良好连接仅在收到ERROR_PIPE_CONNECTED错误后存在。

注释非阻止模式支持与 Microsoft LAN Manager 版本 2.0 兼容，并且不应用于使用命名管道实现异步输入和输出（I/O）。

Windows 10 版本 1709 及更高版本：管道不能用于在应用容器之间通信;例如，从一个 UWP 进程到另一个不属于同一应用的 UWP 进程。此外，应用容器中的命名管道必须使用管道名称的语法“\\.\pipe\LOCAL\”。

例子

有关示例，请参阅多线程管道服务器。

要求

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