ConnectNamedPipe 函式 (namedpipeapi.h)

發行項
02/29/2024

讓命名管道伺服器進程等待客戶端進程連線到命名管道的實例。用戶端進程會藉由呼叫 CreateFile 或 CallNamedPipe 函式來連接。

語法

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

參數

[in] hNamedPipe

具名管道實例之伺服器端的句柄。 CreateNamedPipe 函式會傳回此句柄。

[in, out, optional] lpOverlapped

重疊結構的指標。

如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 開啟， 則 lpOverlapped 參數不得為 NULL。它必須指向有效的重疊結構。如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 開啟，且 lpOverlapped 為 NULL，則函式可能會錯誤地報告連線作業已完成。

如果 hNamedPipe 是以 FILE_FLAG_OVERLAPPED 建立， 且 lpOverlapped 不是 NULL，則 OVERLAPPED 結構應該包含手動重設事件物件的句柄， (伺服器可以使用 CreateEvent 函式) 建立。

如果 hNamedPipe 未以 FILE_FLAG_OVERLAPPED 開啟，則函式不會傳回，直到用戶端連線或發生錯誤為止。如果客戶端在呼叫函式之後連線，成功同步作業會導致函式傳回非零值。

傳回值

如果作業是同步的， 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：管道僅支援在 app-container 內;亦即，從一個 UWP 進程到屬於相同應用程式的另一個 UWP 進程。此外，命名管道必須使用管道名稱的語法『\\.\pipe\LOCAL\』。

範例

如需範例，請參閱多線程管道伺服器。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	namedpipeapi.h
程式庫	Kernel32.lib
DLL	Kernel32.dll