CreateIoCompletionPort-Funktion (ioapiset.h)
Erstellt einen E/A-Abschlussport und ordnet ihn einem angegebenen Dateihandle zu, oder erstellt einen E/A-Abschlussport, der noch keinem Dateihandle zugeordnet ist und eine spätere Zuordnung gestattet.
Das Zuordnen einer Instanz eines geöffneten Dateihandles zu einem E/A-Abschlussport ermöglicht einem Prozess, eine Benachrichtigung über den Abschluss asynchroner E/A-Vorgänge zu erhalten, die dieses Dateihandle betreffen.
Der hier verwendete Begriff Dateihandle bezieht sich auf eine Systemabstraktion, die einen überlappenden E/A-Endpunkt darstellt, nicht nur eine Datei auf einem Datenträger. Alle Systemobjekte, die überlappende E/A unterstützen , z. B. Netzwerkendpunkte, TCP-Sockets, Named Pipes und E-Mail-Slots, können als Dateihandles verwendet werden. Weitere Informationen finden Sie im Abschnitt „Bemerkungen“.
Syntax
HANDLE CreateIoCompletionPort(
[in] HANDLE FileHandle,
[in, optional] HANDLE ExistingCompletionPort,
[in] ULONG_PTR CompletionKey,
[in] DWORD NumberOfConcurrentThreads
);
Parameter
[in] FileHandle
Ein geöffnetes Dateihandle oder INVALID_HANDLE_VALUE.
Das Handle muss auf ein Objekt verweisen, das überlappende E/A unterstützt.
Wenn ein Handle bereitgestellt wird, muss es für den überlappenden E/A-Abschluss geöffnet worden sein. Beispielsweise müssen Sie das FILE_FLAG_OVERLAPPED-Flag angeben, wenn Sie die CreateFile-Funktion verwenden, um das Handle abzurufen.
Wenn INVALID_HANDLE_VALUE angegeben ist, erstellt die Funktion einen E/A-Abschlussport, ohne ihn einem Dateihandle zuzuordnen. In diesem Fall muss der ExistingCompletionPort-Parameter NULL sein, und der CompletionKey-Parameter wird ignoriert.
[in, optional] ExistingCompletionPort
Ein Handle für einen vorhandenen E/A-Abschlussport oder NULL.
Wenn dieser Parameter einen vorhandenen E/A-Abschlussport angibt, ordnet die Funktion ihn dem durch den FileHandle-Parameter angegebenen Handle zu. Die Funktion gibt bei erfolgreicher Ausführung das Handle des vorhandenen E/A-Abschlussports zurück. Es wird kein neuer E/A-Abschlussport erstellt.
Wenn dieser Parameter NULL ist, erstellt die Funktion einen neuen E/A-Abschlussport und ordnet ihn, wenn der FileHandle-Parameter gültig ist, dem neuen E/A-Abschlussport zu. Andernfalls erfolgt keine Zuordnung des Dateihandles. Die Funktion gibt bei erfolgreicher Ausführung das Handle an den neuen E/A-Abschlussport zurück.
[in] CompletionKey
Der pro Handle benutzerdefinierte Abschlussschlüssel, der in jedem E/A-Abschlusspaket für das angegebene Dateihandle enthalten ist. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.
[in] NumberOfConcurrentThreads
Die maximale Anzahl von Threads, die das Betriebssystem zum gleichzeitigen Verarbeiten von E/A-Abschlusspaketen für den E/A-Abschlussport zulassen kann. Dieser Parameter wird ignoriert, wenn der ExistingCompletionPort-Parameter nicht NULL ist.
Wenn dieser Parameter null (0) ist, lässt das System so viele gleichzeitig ausgeführte Threads zu, wie Prozessoren im System vorhanden sind.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert das Handle für einen E/A-Abschlussport:
- Wenn der ExistingCompletionPort-Parameter NULL war, ist der Rückgabewert ein neues Handle.
- Wenn der ExistingCompletionPort-Parameter ein gültiges E/A-Abschlussporthandle war, entspricht der Rückgabewert demselben Handle.
- Wenn der FileHandle-Parameter ein gültiges Handle war, ist dieses Dateihandle nun dem zurückgegebenen E/A-Abschlussport zugeordnet.
Bemerkungen
Das E/A-System kann angewiesen werden, E/A-Abschlussportbenachrichtigungspakete an E/A-Abschlussports zu senden, wo sie sich in der Warteschlange befinden. Die CreateIoCompletionPort-Funktion stellt diese Funktionalität bereit.
Ein E/A-Abschlussport und sein Handle sind dem Prozess zugeordnet, der ihn erstellt hat, und können nicht von Prozessen gemeinsam genutzt werden. Ein einzelnes Handle kann jedoch von Threads im selben Prozess gemeinsam genutzt werden.
CreateIoCompletionPort kann in drei verschiedenen Modi verwendet werden:
- Ausschließliches Erstellen eines E/A-Abschlussports, ohne ihn einem Dateihandle zuzuordnen.
- Zuordnen eines vorhandenen E/A-Abschlussports zu einem Dateihandle.
- Durchführen sowohl der Erstellung als auch der Zuordnung in einem einzigen Aufruf.
Das im FileHandle-Parameter übergebene Handle kann ein beliebiges Handle sein, das überlappende E/A unterstützt. In der Regel handelt es sich um ein Handle, das von der CreateFile-Funktion mit dem FILE_FLAG_OVERLAPPED-Flag geöffnet wird (z. B. für Dateien, E-Mail-Slots und Pipes). Objekte, die von anderen Funktionen wie socket erstellt werden, können auch einem E/A-Abschlussport zugeordnet werden. Ein Beispiel für die Verwendung von Sockets finden Sie unter AcceptEx. Ein Handle kann nur einem E/A-Abschlussport zugeordnet werden, und nachdem die Zuordnung vorgenommen wurde, bleibt das Handle diesem E/A-Abschlussport zugeordnet, bis es geschlossen wird.
Weitere Informationen zur E/A-Abschlussporttheorie, zur Verwendung und zu den zugehörigen Funktionen finden Sie unter E/A-Abschlussports.
Mehrere Dateihandles können einem einzelnen E/A-Abschlussport zugeordnet werden, indem CreateIoCompletionPort mehrmals mit demselben E/A-Abschlussporthandle im ExistingCompletionPort-Parameter und jedes Mal ein anderes Dateihandle im FileHandle-Parameter aufgerufen wird.
Verwenden Sie den CompletionKey-Parameter, um Ihre Anwendung dabei zu unterstützen, nachzuverfolgen, welche E/A-Vorgänge abgeschlossen wurden. Dieser Wert wird von CreateIoCompletionPort nicht für die Funktionssteuerung verwendet. Stattdessen wird er dem Dateihandle angefügt, das im FileHandle-Parameter zum Zeitpunkt der Zuordnung zu einem E/A-Abschlussport angegeben ist. Dieser Abschlussschlüssel sollte für jedes Dateihandle eindeutig sein und begleitet das Dateihandle während des internen Abschlusswarteschlangenprozesses. Er wird im GetQueuedCompletionStatus-Funktionsaufruf zurückgegeben, wenn ein Abschlusspaket eingeht. Der CompletionKey-Parameter wird auch von der PostQueuedCompletionStatus-Funktion verwendet, um Ihre eigenen speziellen Abschlusspakete in die Warteschlange zu stellen.
Nachdem eine Instanz eines geöffneten Handles einem E/A-Abschlussport zugeordnet wurde, kann sie nicht in der ReadFileEx- oder WriteFileEx-Funktion verwendet werden, da diese Funktionen über eigene asynchrone E/A-Mechanismen verfügen.
Ein Dateihandle, das einem E/A-Abschlussport zugeordnet ist, sollte nicht mittels Handlevererbung oder einen Aufruf der DuplicateHandle-Funktion gemeinsam verwendet werden. Vorgänge, die mit solchen doppelten Handles ausgeführt werden, generieren Abschlussbenachrichtigungen. Eine sorgfältige Abwägung ist ratsam.
Das Handle des E/A-Abschlussports und jedes diesem bestimmten E/A-Abschlussport zugeordnete Dateihandle werden als Verweise auf den E/A-Abschlussport bezeichnet. Der E/A-Abschlussport wird freigegeben, wenn keine Verweise darauf mehr vorhanden sind. Daher müssen alle diese Handles ordnungsgemäß geschlossen werden, um den E/A-Abschlussport und die zugehörigen Systemressourcen freizugeben. Sobald diese Bedingungen erfüllt sind, schließen Sie das Handle des E/A-Abschlussports durch Aufruf der CloseHandle-Funktion.
Unter Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.
| Technologie | Unterstützt |
|---|---|
| SMB 3.0-Protokoll (Server Message Block) | Ja |
| SMB 3.0 Transparent Failover (TFO) | Ja |
| SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) | Ja |
| Dateisystem mit freigegebenen Clustervolumes (CsvFS) | Ja |
| Robustes Dateisystem (Resilient File System, ReFS) | Ja |
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ioapiset.h (Einschließen von Windows.h) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |
Siehe auch
Funktionen
Übersichtsthemen