NtCreateNamedPipeFile 函式

建立並開啟特定具名管道之第一個實例的伺服器端控制碼，或現有具名管道的另一個實例。 函式會傳回可用來存取管道的控制碼。

語法

NTSTATUS NtCreateNamedPipeFile(
  [out]          PHANDLE            FileHandle,
  [in]           ULONG              DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in]           ULONG              NamedPipeType,
  [in]           ULONG              ReadMode,
  [in]           ULONG              CompletionMode,
  [in]           ULONG              MaximumInstances,
  [in]           ULONG              InboundQuota,
  [in]           ULONG              OutboundQuota,
  [in, optional] PLARGE_INTEGER     DefaultTimeout
);

參數

FileHandle [out]

如果呼叫成功，接收檔案控制碼的變數指標。

DesiredAccess [in]

旗標的位元遮罩，指定呼叫端所需的檔案或目錄存取類型。 這個系統定義的 DesiredAccess 旗標會決定下列檔案物件的特定存取權限。

或者，對於任何不代表目錄的檔案物件，您可以指定下列一或多個泛型 ACCESS_MASK 旗標。 STANDARD_RIGHTS_XXX旗標是預先定義的系統值，用來在系統物件上強制執行安全性。 您也可以將這些泛型旗標與上表中的其他旗標結合。

針對 (FILE_DIRECTORY_FILECreateOptions旗標設定) 目錄，您可以指定下列一或多個ACCESS_MASK旗標，也可以與先前所述的任何相容旗標結合。

FILE_READ_DATA、 FILE_WRITE_DATA 、 FILE_EXECUTE 和 FILE_APPEND_DATADesiredAccess旗標與建立或開啟目錄檔案不相容。

ObjectAttributes [in]

OBJECT_ATTRIBUTES 已由 InitializeObjectAttributes常式初始化之結構的指標。 如果呼叫端是在系統進程內容中執行，這個參數可以是 NULL 。 否則，呼叫端必須在呼叫InitializeObjectAttributes中設定 OBJ_KERNEL_HANDLE 屬性。

檔案物件的這個結構成員包括下列專案：

IoStatusBlock [out]

型 IO_STATUS_BLOCK 別變數的指標，可接收最終完成狀態和所要求作業的相關資訊。 從 NtCreateNamedPipeFile傳回時，變數的 Information 成員包含下列其中一個值：

• FILE_CREATED
• FILE_OPENED
• FILE_OVERWRITTEN
• FILE_SUPERSEDED
• FILE_EXISTS
• FILE_DOES_NOT_EXIST

ShareAccess [in]

指定呼叫端想要的檔案共用存取類型，做為零或一，或下列旗標的組合。 若要要求獨佔存取權，請將此參數設定為零。 若要協助您避免共用違規錯誤，請指定下列所有共用存取旗標。

設備磁碟機和中繼驅動程式通常會將 ShareAccess 設定為零，這可讓呼叫端獨佔存取開啟的檔案。

CreateDisposition [in]

值，決定檔案已經存在時應如何處理檔案。 CreateDisposition 可以是下列其中一項：

CreateOptions [in]

指定建立或開啟檔案時要套用的選項，做為下列旗標的相容組合。

NamedPipeType [in]

建立 (位元組類型或訊息類型) 的具名管道類型。

ReadMode [in]

讀取管道 (位元組類型或訊息類型) 的模式。

CompletionMode [in]

指定作業完成的方式。

MaximumInstances [in]

具名管道同時實例的數目上限。

InboundQuota [in]

指定保留給寫入具名管道輸入端的集區配額。

OutboundQuota [in]

指定保留給寫入具名管道輸入端的集區配額。

DefaultTimeout [in， optional]

當等候具名管道的實例時，如果未指定逾時值，則為逾時值的選擇性指標。

傳回

函式值是建立/開啟作業的最終狀態。

備註

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

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

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

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

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

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

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

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

規格需求