connectNamedPipe 函数 (namedpipeapi.h)

项目
08/25/2023

允许命名管道服务器进程等待客户端进程连接到命名管道的实例。客户端进程通过调用 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错误后才存在。

注意支持非阻止模式以与 Microsoft LAN Manager 版本 2.0 兼容，并且不应将其用于通过命名管道实现异步输入和输出 (I/O) 。

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

示例

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

要求

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