connectNamedPipe 函数 (namedpipeapi.h)
允许命名管道服务器进程等待客户端进程连接到命名管道的实例。 客户端进程通过调用 CreateFile 或 CallNamedPipe 函数进行连接。
语法
BOOL ConnectNamedPipe(
[in] HANDLE hNamedPipe,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
参数
[in] hNamedPipe
命名管道实例的服务器端的句柄。 此句柄由 CreateNamedPipe 函数返回。
[in, out, optional] lpOverlapped
指向 OVERLAPPED 结构的指针。
如果使用 FILE_FLAG_OVERLAPPED 打开 hNamedPipe ，则 lpOverlapped 参数不得为 NULL。 它必须指向有效的 OVERLAPPED 结构。 如果使用 FILE_FLAG_OVERLAPPED 打开 hNamedPipe 并且 lpOverlapped 为 NULL，则该函数可能会错误地报告连接操作已完成。
如果 hNamedPipe 是使用 FILE_FLAG_OVERLAPPED 创建的，并且 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_NO_DATA;如果尚未关闭句柄，则返回ERROR_PIPE_CONNECTED。
ConnectNamedPipe 的行为取决于两个条件：管道句柄的等待模式是设置为阻止还是非阻塞，以及函数是设置为同步执行还是以重叠模式执行。 服务器最初在 CreateNamedPipe 函数中指定管道句柄的等待模式，并且可以使用 SetNamedPipeHandleState 函数对其进行更改。
服务器进程可以使用任何 等待函数 或 SleepEx 来确定何时发出事件对象的状态信号，然后它可以使用 HasOverlappedIoCompleted 宏来确定 ConnectNamedPipe 操作何时完成。
如果指定的管道句柄处于非阻止模式， 则 ConnectNamedPipe 始终会立即返回。 在非阻止模式下， ConnectNamedPipe 在首次为与以前的客户端断开连接的管道实例调用它时返回非零值。 这表示管道现在可以连接到新的客户端进程。 在管道句柄处于非阻止模式的所有其他情况下， ConnectNamedPipe 返回零。 在这些情况下，如果未连接任何客户端， GetLastError 将返回ERROR_PIPE_LISTENING;如果客户端已连接，则ERROR_PIPE_CONNECTED;如果以前的客户端已关闭其管道句柄但服务器未断开连接，则ERROR_NO_DATA。 请注意，客户端和服务器之间的良好连接仅在收到ERROR_PIPE_CONNECTED错误后才存在。
示例
有关示例，请参阅 多线程管道服务器。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 2000 专业版 [桌面应用 |UWP 应用] |
| 最低受支持的服务器 | Windows 2000 Server [桌面应用 |UWP 应用] |
| 目标平台 | Windows |
| 标头 | namedpipeapi.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |