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 。 您可以指定下列兩個值或兩者。
| 值 | 意義 |
|---|---|
|
管道句柄處於非封鎖模式。 如果未指定此旗標，管道句柄會處於封鎖模式。 |
|
管道句柄處於訊息讀取模式。 如果未指定此旗標，管道句柄會處於位元組讀取模式。 |
[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 |