createIoCompletionPort 函式 (ioapiset.h)
建立輸入/輸出 (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 完成埠相關聯。
備註
您可以指示 I/O 系統將 I/O 完成通知封包傳送至已排入佇列的 I/O 完成埠。 CreateIoCompletionPort函式提供這項功能。
I/O 完成埠及其控制碼會與建立它的進程相關聯，而且無法在進程之間共用。 不過，在相同進程中的執行緒之間可共用單一控制碼。
CreateIoCompletionPort 可用於三種不同的模式：
- 只建立 I/O 完成埠，而不將它與檔案控制代碼產生關聯。
- 將現有的 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 |
另請參閱
函式
概觀主題