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

另請參閱

管道函式

管道概觀

ReadFile

SECURITY_ATTRIBUTES

WriteFile