CreatePipe 函式 (namedpipeapi.h)
建立匿名管道,並將句柄傳回至管道的讀取和寫入結尾。
語法
BOOL CreatePipe(
[out] PHANDLE hReadPipe,
[out] PHANDLE hWritePipe,
[in, optional] LPSECURITY_ATTRIBUTES lpPipeAttributes,
[in] DWORD nSize
);
參數
[out] hReadPipe
接收管道讀取句柄之變數的指標。
[out] hWritePipe
接收管道寫入句柄之變數的指標。
[in, optional] lpPipeAttributes
SECURITY_ATTRIBUTES 結構的指標,決定子進程是否可以繼承傳回的句柄。 如果 lpPipeAttributes 為 NULL,則無法繼承句柄。
結構的 lpSecurityDescriptor 成員會指定新管道的安全性描述元。 如果 lpPipeAttributes 為 NULL,管道會取得預設的安全性描述元。 管道預設安全性描述元中的 ACL 來自建立者的主要或模擬令牌。
[in] nSize
管道的緩衝區大小,以位元組為單位。 大小只是建議;系統會使用 值來計算適當的緩衝機制。 如果此參數為零,系統會使用默認緩衝區大小。
傳回值
如果函式成功,則傳回非零的值。
如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError。
備註
CreatePipe 會建立管道,並將指定的管道大小指派給記憶體緩衝區。 CreatePipe 也會建立句柄,讓進程在後續呼叫 ReadFile 和 WriteFile 函式時,用來讀取和寫入緩衝區。
若要從管道讀取,進程會使用 ReadFile 函式呼叫中的讀取句柄。 當下列其中一項為 true 時,ReadFile 會傳回:寫入作業會在管道的寫入端完成、要求的位元元數目已讀取,或發生錯誤。
當進程使用 WriteFile 寫入匿名管道時,在寫入所有位元組之前都不會完成寫入作業。 如果在寫入所有位元組之前,管道緩衝區已滿, 則 WriteFile 不會傳回,直到另一個進程或線程使用 ReadFile 來提供更多緩衝區空間為止。
匿名管道是使用具有唯一名稱的命名管道來實作。 因此,您通常會將句柄傳遞至匿名管道至需要命名管道句柄的函式。
如果 CreatePipe 失敗,輸出參數的內容會不確定。 在此事件中不應對其內容進行任何假設。
若要釋放管道所使用的資源,當不再需要這些資源時,應用程式應該一律關閉句柄,這可藉由呼叫 CloseHandle 函式或與實例句柄相關聯的進程結束來完成。 請注意,管道的實例可能有一個以上的句柄與其相關聯。 關閉命名管道實例的最後一個句柄時,一律會刪除管道的實例。
範例
如需範例,請參閱 使用重新導向的輸入和輸出建立子進程。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式] |
最低支援的伺服器 | Windows 2000 Server [傳統型應用程式 |UWP 應用程式] |
目標平台 | Windows |
標頭 | namedpipeapi.h |
程式庫 | Kernel32.lib |
DLL | Kernel32.dll |