CreateNamedPipeA 函式 (winbase.h)

  • 發行項

建立具名管道的實例，並傳回後續管道作業的句柄。 命名管道伺服器進程會使用此函式來建立特定命名管道的第一個實例，並建立其基本屬性，或建立現有命名管道的新實例。

語法

HANDLE CreateNamedPipeA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 dwOpenMode,
  [in]           DWORD                 dwPipeMode,
  [in]           DWORD                 nMaxInstances,
  [in]           DWORD                 nOutBufferSize,
  [in]           DWORD                 nInBufferSize,
  [in]           DWORD                 nDefaultTimeOut,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

參數

[in] lpName

唯一管道名稱。 這個字串必須具有下列格式：

\\.\pipe\pipe\pipename

名稱的管道名稱部分可以包含反斜杠以外的任何字元，包括數位和特殊字元。 整個管道名稱字串長度最多可達 256 個字元。 管道名稱不區分大小寫。

[in] dwOpenMode

開啟模式。

如果 dwOpenMode 指定 0 以外的任何專案或下表所列的旗標，則此函式會失敗。

此參數必須指定下列其中一種管道存取模式。 每個管道實例都必須指定相同的模式。

模式 意義
PIPE_ACCESS_DUPLEX
0x00000003
 管道是雙向的;伺服器和客戶端進程都可以讀取和寫入管道。 此模式可讓伺服器對 GENERIC_READ 和 GENERIC_WRITE 管道的存取權。 當用戶端使用 CreateFile 函式連接到管道時，可以指定GENERIC_READ或GENERIC_WRITE或兩者。
PIPE_ACCESS_INBOUND
0x00000001
 管道中的數據流程只會從用戶端流向伺服器。 此模式可讓伺服器對 GENERIC_READ 管道的存取權。 用戶端必須在連接到管道時指定 GENERIC_WRITE 存取權。 如果客戶端必須藉由呼叫 GetNamedPipeInfo 或 GetNamedPipeHandleState 函式來讀取管道設定，客戶端必須在連線至管道時指定GENERIC_WRITE和FILE_READ_ATTRIBUTES存取。
PIPE_ACCESS_OUTBOUND
0x00000002
 管道中的數據流程只會從伺服器流向用戶端。 此模式可讓伺服器存取管道 GENERIC_WRITE 對等專案。 客戶端必須在連線至管道時指定 GENERIC_READ 存取權。 如果客戶端必須藉由呼叫 SetNamedPipeHandleState 函式來變更管道設定，客戶端必須在連線至管道時指定GENERIC_READ和FILE_WRITE_ATTRIBUTES存取。
 

此參數也可以包含下列一或多個旗標，以啟用寫入和重疊模式。 對於相同管道的不同實例，這些模式可能不同。

模式 意義
FILE_FLAG_FIRST_PIPE_INSTANCE
0x00080000
 如果您嘗試使用此旗標建立管道的多個實例，則第一個實例的建立會成功，但建立下一個實例會失敗，並出現 ERROR_ACCESS_DENIED。
FILE_FLAG_WRITE_THROUGH
0x80000000
 已啟用寫入模式。 此模式只會影響位元組類型管道上的寫入作業，然後只有在用戶端和伺服器進程位於不同的計算機上時。 如果啟用此模式，寫入命名管道的函式會等到寫入的數據透過網路傳輸，且位於遠端電腦上的管道緩衝區，才會傳回。 如果未啟用此模式，系統會緩衝處理數據，以提升網路作業的效率，直到累積最少的位元組數，或直到經過的時間上限為止。
FILE_FLAG_OVERLAPPED
0x40000000
 已啟用重疊模式。 如果啟用此模式，執行讀取、寫入和連接作業的函式可能需要很長的時間才能立即傳回。 此模式可讓啟動作業的線程在背景執行耗時的作業時執行其他作業。 例如，在重疊模式中，線程可以在多個管道實例上同時處理輸入和輸出 (I/O) 作業，或在相同的管道句柄上執行同時讀取和寫入作業。 如果未啟用重疊模式，在完成作業之前，在管道句柄上執行讀取、寫入和連接作業的函式不會傳回。 ReadFileEx 和 WriteFileEx 函式只能與以重疊模式的管道句柄搭配使用。 ReadFile、WriteFile、ConnectNamedPipe 和 TransactNamedPipe 函式可以同步或重疊的作業來執行。
 

此參數可包含下列安全性存取模式的任何組合。 對於相同管道的不同實例，這些模式可能不同。

模式 意義
WRITE_DAC
0x00040000L
 呼叫端將具有具名管道任意訪問控制清單的寫入許可權， (ACL) 。
WRITE_OWNER
0x00080000L
 呼叫端將擁有具名管道擁有者的寫入許可權。
ACCESS_SYSTEM_SECURITY
0x01000000L
 呼叫端將具有具名管道 SACL 的寫入許可權。 如需詳細資訊，請參閱訪問控制 清單 (ACL) 和 SACL 訪問許可權。

[in] dwPipeMode

管道模式。

如果 dwPipeMode 指定 0 以外的任何專案或下表所列的旗標，則此函式會失敗。

您可以指定下列其中一種類型模式。 每個管道實例都必須指定相同的類型模式。

模式 意義
PIPE_TYPE_BYTE
0x00000000
 數據會以位元組數據流的形式寫入管道。 此模式無法與PIPE_READMODE_MESSAGE搭配使用。 管道不會區分在不同寫入作業期間寫入的位元組。
PIPE_TYPE_MESSAGE
0x00000004
 數據會以訊息數據流的形式寫入管道。 管道會將每個寫入作業期間寫入的位元組視為訊息單位。 GetLastError 函式會在未完全讀取訊息時傳回ERROR_MORE_DATA。 此模式可以搭配 PIPE_READMODE_MESSAGE 或 PIPE_READMODE_BYTE使用。
 

您可以指定下列其中一種讀取模式。 相同管道的不同實例可以指定不同的讀取模式。

模式 意義
PIPE_READMODE_BYTE
0x00000000
 數據會以位元組數據流的形式從管道讀取。 此模式可以與 PIPE_TYPE_MESSAGE 或 PIPE_TYPE_BYTE搭配使用。
PIPE_READMODE_MESSAGE
0x00000002
 數據會從管道讀取為訊息數據流。 只有在同時指定 PIPE_TYPE_MESSAGE 時，才能使用此模式。
 

您可以指定下列其中一種等候模式。 相同管道的不同實例可以指定不同的等候模式。

模式 意義
PIPE_WAIT
0x00000000
 已啟用封鎖模式。 在 ReadFile、 WriteFile 或 ConnectNamedPipe 函式中指定管道句柄時，除非有要讀取的數據、寫入所有數據或用戶端連線，否則不會完成作業。 使用此模式可能表示在某些情況下，客戶端進程會無限期地等候執行動作。
PIPE_NOWAIT
0x00000001
 啟用非封鎖模式。 在此模式中， ReadFile、 WriteFile 和 ConnectNamedPipe 一律會立即傳回。

請注意，不支援非封鎖模式，以便與 Microsoft LAN Manager 2.0 版相容，且不應該用來使用命名管道達成異步 I/O。 如需異步管道 I/O 的詳細資訊，請參閱 同步和重疊的輸入和輸出。
 

您可以指定下列其中一種遠端用戶端模式。 相同管道的不同實例可以指定不同的遠端用戶端模式。

模式 意義
PIPE_ACCEPT_REMOTE_CLIENTS
0x00000000
 您可以從遠端用戶端接受和檢查遠端用戶端 Connections 管道的安全性描述項。
PIPE_REJECT_REMOTE_CLIENTS
0x00000008
 遠端用戶端 Connections 會自動遭到拒絕。

[in] nMaxInstances

可為此管道建立的實例數目上限。 管道的第一個實例可以指定此值;管道的其他實例必須指定相同的數位。 可接受的值為範圍 1 到 PIPE_UNLIMITED_INSTANCES (255) 。

如果此參數 PIPE_UNLIMITED_INSTANCES，可以建立的管道實例數目只會受限於系統資源的可用性。 如果 nMaxInstances 大於 PIPE_UNLIMITED_INSTANCES，則會 INVALID_HANDLE_VALUE 傳回值，而 GetLastError 會 傳回 ERROR_INVALID_PARAMETER。

[in] nOutBufferSize

要保留給輸出緩衝區的位元組數目。 如需調整命名管道緩衝區大小的討論，請參閱下列一節。

[in] nInBufferSize

要保留給輸入緩衝區的位元組數目。 如需調整命名管道緩衝區大小的討論，請參閱下列一節。

[in] nDefaultTimeOut

如果 WaitNamedPipe 函式指定 NMPWAIT_USE_DEFAULT_WAIT，則預設逾時值會以毫秒為單位。 命名管道的每個實例都必須指定相同的值。

值為零會導致預設逾時 50 毫秒。

[in, optional] lpSecurityAttributes

SECURITY_ATTRIBUTES 結構的指標，指定新命名管道的安全性描述項，並判斷子進程是否可以繼承傳回的句柄。 如果 lpSecurityAttributes 為 NULL，命名管道會取得預設的安全性描述元，而且無法繼承句柄。 具名管道的預設安全性描述元中的 ACL 會將完全控制權授與 LocalSystem 帳戶、系統管理員和建立者擁有者。 他們也會授與所有人群組成員和匿名帳戶的讀取許可權。

傳回值

如果函式成功，則傳回值是具名管道實例伺服器端的句柄。

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

備註

若要使用 CreateNamedPipe 建立命名管道的實例，用戶必須具有命名管道物件的 FILE_CREATE_PIPE_INSTANCE 存取權。 如果要建立新的命名管道，則從安全性屬性參數 (ACL) 存取控制清單會定義命名管道的任意存取控制。

具名管道的所有實例都必須指定相同的管道類型 (位元組類型或訊息類型) 、管道存取 (雙工、輸入或輸出) 、實例計數和逾時值。 如果使用不同的值，此函式會失敗，而且 GetLastError 會 傳回ERROR_ACCESS_DENIED。

客戶端進程會使用 CreateFile 或 CallNamedPipe 函式連接到命名管道。 具名管道的用戶端會以位元組模式啟動，即使伺服器端處於訊息模式也一樣。 若要避免接收數據時發生問題，也請將用戶端設定為訊息模式。 若要變更管道的模式，管道客戶端必須開啟具有 GENERIC_READ 和 FILE_WRITE_ATTRIBUTES存取的 只讀管道。

管道伺服器不應該執行封鎖讀取作業，直到管道客戶端啟動為止。 否則，可能會發生競爭狀況。 這通常會發生在初始化程序代碼，例如 C 運行時間時，需要鎖定並檢查繼承的句柄時。

每次建立命名管道時，系統會使用非分頁集區建立輸入和輸出緩衝區，這是核心所使用的物理記憶體。 管線實例數目 (以及線程和進程等物件，) 您可以建立的管線實例數目受限於可用的非分頁集區。 每個讀取或寫入要求都需要緩衝區中讀取或寫入數據的空間，再加上內部數據結構的額外空間。

輸入和輸出緩衝區大小是諮詢。 保留給命名管道每一端的實際緩衝區大小是系統預設值、系統最小值或最大值，或指定的大小四捨五入到下一個配置界限。 指定的緩衝區大小應該夠小，您的進程不會用盡非分頁集區，但足以容納一般要求。

每當發生管道寫入作業時，系統會先嘗試對管道寫入配額收取記憶體費用。 如果剩餘的管道寫入配額足以滿足要求，則寫入作業會立即完成。 如果剩餘的管道寫入配額太小而無法滿足要求，系統會嘗試擴充緩衝區，以使用保留給進程的非分頁集區來容納數據。 寫入作業會封鎖，直到從管道讀取數據，以便釋放額外的緩衝區配額。 因此，如果您的指定緩衝區大小太小，系統會視需要增加緩衝區，但缺點是作業會封鎖。 如果作業重疊，則會封鎖系統線程;否則，會封鎖應用程式線程。

若要釋放命名管道所使用的資源，當不再需要這些資源時，應用程式應該一律關閉句柄，這可藉由呼叫 CloseHandle 函式或與實例句柄相關聯的進程結束時完成。 請注意，具名管道的實例可能有一個以上的句柄與其相關聯。 關閉命名管道實例的最後一個句柄時，一律會刪除具名管道的實例。

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

範例

如需範例，請參閱 多線程管道伺服器。

規格需求

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

另請參閱

ConnectNamedPipe

CreateFile

管道函式

管道概觀

ReadFile

ReadFileEx

SECURITY_ATTRIBUTES

TransactNamedPipe

WaitNamedPipe

WriteFile

WriteFileEx