createIoCompletionPort 函式 (ioapiset.h)

發行項
08/24/2023

建立輸入/輸出 (I/O) 完成埠，並將它與指定的檔案控制代碼產生關聯，或建立尚未與檔案控制代碼相關聯的 I/O 完成埠，以便稍後進行關聯。

將開啟的檔案控制碼實例與 I/O 完成埠建立關聯，可讓進程接收與該檔案控制碼相關的非同步 I/O 作業完成通知。

注意

此處使用的 檔案控制碼 一詞是指代表重迭 I/O 端點的系統抽象概念，而不只是磁片上的檔案。任何支援重迭 I/O 的系統物件，例如網路端點、TCP 通訊端、具名管道和郵件位置，都可以當做檔案控制代碼使用。如需詳細資訊，請參閱一節。

語法

HANDLE CreateIoCompletionPort(
  [in]           HANDLE    FileHandle,
  [in, optional] HANDLE    ExistingCompletionPort,
  [in]           ULONG_PTR CompletionKey,
  [in]           DWORD     NumberOfConcurrentThreads
);

參數

[in] FileHandle

開啟的檔案控制碼或 INVALID_HANDLE_VALUE。

控制碼必須是支援重迭 I/O 的物件。

如果提供控制碼，則必須開啟此控制碼以進行重迭的 I/O 完成。例如，使用CreateFile函式取得控制碼時，您必須指定FILE_FLAG_OVERLAPPED旗標。

如果指定 了INVALID_HANDLE_VALUE ，函式會建立 I/O 完成埠，而不會將它與檔案控制代碼產生關聯。在此情況下， ExistingCompletionPort 參數必須是 Null ，而且 會忽略 CompletionKey 參數。

[in, optional] ExistingCompletionPort

現有 I/O 完成埠或 Null的控制碼。

如果此參數指定現有的 I/O 完成埠，函式會將它與 FileHandle 參數指定的控制碼產生關聯。如果成功，函式會傳回現有 I/O 完成埠的控制碼;它不會建立新的 I/O 完成埠。

如果此參數為 Null，則函式會建立新的 I/O 完成埠，如果 FileHandle 參數有效，請將它與新的 I/O 完成埠產生關聯。否則不會發生任何檔案控制代碼關聯。如果成功，函式會將控制碼傳回至新的 I/O 完成埠。

[in] CompletionKey

每個控制碼使用者定義的完成金鑰，包含在指定之檔案控制代碼的每個 I/O 完成封包中。如需詳細資訊，請參閱＜備註＞一節。

[in] NumberOfConcurrentThreads

作業系統可以允許並行處理 I/O 完成埠的 I/O 完成封包數目上限。如果 ExistingCompletionPort 參數不是 Null，則會忽略此參數。

如果此參數為零，則系統允許與系統中有處理器一樣多同時執行的執行緒。

傳回值

如果函式成功，傳回值就是 I/O 完成埠的控制碼：

如果 ExistingCompletionPort 參數為 Null，則傳回值是新的控制碼。
如果 ExistingCompletionPort 參數是有效的 I/O 完成埠控制碼，傳回值就是相同的控制碼。
如果 FileHandle 參數是有效的控制碼，該檔案控制碼現在會與傳回的 I/O 完成埠相關聯。

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

備註

您可以指示 I/O 系統將 I/O 完成通知封包傳送至已排入佇列的 I/O 完成埠。 CreateIoCompletionPort函式提供這項功能。

I/O 完成埠及其控制碼會與建立它的進程相關聯，而且無法在進程之間共用。不過，在相同進程中的執行緒之間可共用單一控制碼。

CreateIoCompletionPort 可用於三種不同的模式：

只建立 I/O 完成埠，而不將它與檔案控制代碼產生關聯。
將現有的 I/O 完成埠與檔案控制代碼產生關聯。
在單一呼叫中執行建立和關聯。

若要建立 I/O 完成埠而不建立關聯，請將 FileHandle 參數設定為 INVALID_HANDLE_VALUE、 ExistingCompletionPort 參數設定為 Null，並將 CompletionKey 參數設定為零 (在此情況下會忽略) 。將 NumberOfConcurrentThreads 參數設定為新 I/O 完成埠所需的並行值，或將預設 (系統中處理器數目的零) 。

在 FileHandle 參數中傳遞的控制碼可以是任何支援重迭 I/O 的控制碼。最常見的情況是 CreateFile 函式使用 FILE_FLAG_OVERLAPPED 旗標 (開啟的控制碼，例如檔案、郵件位置及管道) 。通訊端等其他函式所建立的物件也可以與 I/O 完成埠相關聯。如需使用通訊端的範例，請參閱 AcceptEx。控制碼只能與一個 I/O 完成埠相關聯，而且在建立關聯之後，控制碼會維持與該 I/O 完成埠的關聯，直到關閉為止。

如需 I/O 完成埠理論、使用方式和相關函式的詳細資訊，請參閱 I/O 完成埠。

多個檔案控制代碼可以與單一 I/O 完成埠相關聯，方法是每次呼叫 CreateIoCompletionPort 多次，並在 ExistingCompletionPort 參數中使用相同的 I/O 完成埠控制碼，以及 FileHandle 參數中的不同檔案控制碼。

使用 CompletionKey 參數來協助應用程式追蹤哪些 I/O 作業已完成。 CreateIoCompletionPort不會使用這個值來進行功能控制;相反地，它會附加至FileHandle參數中指定的檔案控制代碼，與 I/O 完成埠建立關聯時。每個檔案控制代碼的這個完成索引鍵應該是唯一的，而且會伴隨整個內部完成佇列程式的檔案控制碼。當完成封包送達時，它會在 GetQueuedCompletionStatus 函式呼叫中傳回。 PostQueuedCompletionStatus函式也會使用CompletionKey參數，將您自己的特殊用途完成封包排入佇列。

開啟控制碼的實例與 I/O 完成埠相關聯之後，就無法在 ReadFileEx 或 WriteFileEx 函式中使用，因為這些函式有自己的非同步 I/O 機制。

最好不要使用控制碼繼承或對 DuplicateHandle 函式的呼叫，來共用與 I/O 完成埠相關聯的檔案控制碼。使用這類重複控制碼執行的作業會產生完成通知。建議您謹慎考慮。

I/O 完成埠控制碼和與該特定 I/O 完成埠相關聯的每個檔案控制代碼稱為 I/O 完成埠的參考。當不再參考 I/O 完成埠時，就會釋出。因此，所有這些控制碼都必須正確關閉，才能釋放 I/O 完成埠及其相關聯的系統資源。滿足這些條件之後，呼叫 CloseHandle 函式以關閉 I/O 完成埠控制碼。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

技術	支援
伺服器訊息區 (SMB) 3.0 通訊協定	是
SMB 3.0 透明容錯移轉 (TFO)	是
具有向外延展檔案共用的 SMB 3.0 (SO)	是
叢集共用磁片區檔案系統 (CsvFS)	是
彈性檔案系統 (ReFS)	是

需求


最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	ioapiset.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll