GetNamedPipeHandleStateA 函式 (winbase.h)

擷取指定命名管道的相關信息。 傳回的資訊在具名管道實例的存留期內可能會有所不同。

語法

BOOL GetNamedPipeHandleStateA(
  [in]            HANDLE  hNamedPipe,
  [out, optional] LPDWORD lpState,
  [out, optional] LPDWORD lpCurInstances,
  [out, optional] LPDWORD lpMaxCollectionCount,
  [out, optional] LPDWORD lpCollectDataTimeout,
  [out, optional] LPSTR   lpUserName,
  [in]            DWORD   nMaxUserNameSize
);

參數

[in] hNamedPipe

所要資訊之命名管道的句柄。 句柄必須具有唯讀或讀取/寫入管道的GENERIC_READ存取權，或者必須具有只讀管道的GENERIC_WRITE和FILE_READ_ATTRIBUTES存取權。

此參數也可以是匿名管道的句柄，如 CreatePipe 函式所傳回。

[out, optional] lpState

指出句柄目前狀態之變數的指標。 如果不需要這項資訊，此參數可以是 NULL 。 您可以指定下列兩個值或兩者。

值	意義
PIPE_NOWAIT 0x00000001	管道句柄處於非封鎖模式。 如果未指定此旗標，管道句柄會處於封鎖模式。
PIPE_READMODE_MESSAGE 0x00000002	管道句柄處於訊息讀取模式。 如果未指定此旗標，管道句柄會處於位元組讀取模式。

[out, optional] lpCurInstances

接收目前管道實例數目之變數的指標。 如果不需要這項資訊，此參數可以是 NULL 。

[out, optional] lpMaxCollectionCount

變數的指標，它會在傳送至伺服器之前，接收用戶端計算機上要收集的最大位元元組數目。 如果指定的管道句柄位於命名管道的伺服器端，或者客戶端和伺服器進程位於同一部計算機上，這個參數必須是 NULL 。 如果不需要這項資訊，此參數可以是 NULL 。

[out, optional] lpCollectDataTimeout

變數的指標，可接收最大時間，以毫秒為單位，在遠端命名管道透過網路傳輸資訊之前傳遞。 如果指定的管道句柄位於命名管道的伺服器端，或者客戶端和伺服器進程位於同一部計算機上，這個參數必須是 NULL 。 如果不需要這項資訊，此參數可以是 NULL 。

[out, optional] lpUserName

緩衝區的指標，接收與用戶端應用程式相關聯的用戶名稱字串。 如果用戶端以SECURITY_IMPERSONATION存取方式開啟管道，則伺服器只能擷取這項資訊。

如果指定的管道句柄位於命名管道的用戶端端，這個參數必須是 NULL 。 如果不需要這項資訊，此參數可以是 NULL 。

[in] nMaxUserNameSize

TCHAR 中 lpUserName 參數所指定的緩衝區大小。 如果 lpUserName 為 NULL，則會忽略此參數。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

即使傳遞至 GetNamedPipeHandleState 的所有指標都是 NULL，GetNamedPipeHandleState 函式仍會成功傳回。

若要設定管道句柄狀態，請使用 SetNamedPipeHandleState 函式。

Windows 10 版本 1709：管道僅在應用程式容器內受到支援;亦即，從一個 UWP 進程到另一個屬於相同應用程式的 UWP 進程。 此外，命名管道必須使用管道名稱的語法 \\.\pipe\LOCAL\ 。

規格需求

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

另請參閱

管道函式

管道概觀

SetNamedPipeHandleState