SetNamedPipeHandleState 函式 (namedpipeapi.h)

發行項
03/05/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
程式庫	Kernel32.lib
DLL	Kernel32.dll