HTTP-Vervollständigungsroutinen
Anwendungen haben mehrere Optionen zum Empfangen von Vervollständigungshinweisen und bieten Entwicklern eine gewisse Flexibilität. Die Optionen sind das Blockieren während des Wartens auf den Abschluss eines API-Aufrufs oder die Verwendung von Vervollständigungsroutinen für asynchrone Vorgänge. Der Vorteil der Verwendung asynchroner Vorgänge ist eine höhere Reaktionsfähigkeit der Anwendung.
Blockierte E/A
Anwendungen können blockieren, während auf den Abschluss des API-Aufrufs gewartet wird, indem die OVERLAPPED-Struktur auf NULL festgelegt wird. Dadurch werden alle Vorgänge im Thread blockiert. Bei Aufrufen von HttpWaitForDisconnectwird der Aufruf beispielsweise blockiert, bis die Verbindung unterbrochen wird.
Asynchrone E/A
Anwendungen, die nicht blockieren möchten, können die OVERLAPPED-Struktur verwenden, um die Abschlussergebnisse zu erhalten. Die Anwendung stellt einen Zeiger auf eine OVERLAPPED-Struktur bereit, die mit einem Ereignisobjekt oder einem Abschlussport verwendet wird. Bei einem E/A-Abschlussport wird ein HTTP-Handle als Dateihandle in einem asynchronen Datei-E/A-Vorgang verwendet. In der folgenden Tabelle sind die vervollständigungsoptionen zusammengefasst, die den Anwendungen zur Verfügung stehen.
| Überlappende Struktur | Ereignisobjekt | Abschlussport | Completion |
|---|---|---|---|
| NULL | Nicht zutreffend | Wird ignoriert. | Der Vorgang wird synchron abgeschlossen. |
| Ungleich NULL | Ungleich NULL | NULL | Der Vorgang wird asynchron abgeschlossen. Überlappende Benachrichtigungen werden ausgeführt, indem ein Ereignisobjekt signalisiert wird. |
| Ungleich NULL | Wird ignoriert. | Ungleich NULL | Der Vorgang wird asynchron abgeschlossen. Überlappende Benachrichtigungen werden ausgeführt, indem eine Abschlussroutine geplant wird. |
Zurückgeben der Anzahl gelesener Bytes
Einige der Funktionen, die die OVERLAPPED-Struktur für die asynchrone Vervollständigung verwenden, geben einen pBytesReceived-Parameter (oder pBytesSent oder pBytesRead) zurück, der die Anzahl der synchron übertragenen Bytes angibt. Bei asynchronen Aufrufen sollte dieser Parameter auf NULL festgelegt werden. Bei synchronen Aufrufen ist der pBytesReceived-Parameter optional und kann entweder NULL oder ungleich NULL sein.
Wenn das Ereignisobjekt für die asynchrone Vervollständigung verwendet wird, wird die GetOverlappedResult-Funktion aufgerufen, um die Anzahl der gelesenen Bytes zu bestimmen. Wenn der Abschlussport verwendet wird (der hFile-Parameter ist einem E/A-Abschlussport zugeordnet), ruft die Anwendung die GetQueuedCompletionStatus-Funktion auf, um die Anzahl der gelesenen Bytes zu bestimmen. Wenn die asynchronen Vorgänge nicht abgeschlossen wurden, können Anwendungen die GetLastError-Funktion aufrufen, um erweiterte Fehlerinformationen abzurufen.
In der folgenden Tabelle wird das Vervollständigungsverhalten für die synchrone und asynchrone Vervollständigung in Funktionen wie HttpReceiveHttpRequest zusammengefasst, die den pBytesReceived-Parameter verwenden.
| pBytesReceived* | pOverlapped | Beschreibung |
|---|---|---|
| NULL | NULL | Die Anwendung empfängt keine Informationen zur Anzahl der zurückgegebenen Bytes. |
| NULL | Ungleich NULL | Der asynchrone Vorgang pBytesReceived ist bedeutungslos. |
| Ungleich NULL | NULL | Synchroner Vorgang, Anzahl der in pBytesReceived zurückgegebenen Bytes. |
| Ungleich NULL | Ungleich NULL | Der asynchrone Vorgang pBytesReceived wird ignoriert, obwohl er nicht NULL ist.** |
Hinweis
*Dieser Parameter kann auch pBytesSent oder pBytesRead sein.
Hinweis
**Es wird empfohlen, dass Anwendungen einen NULL-Wert in pBytesReceived für asynchrone Vorgänge übergeben und die Anzahl der Bytes abrufen, die von GetOverlappedResult oder GetQueuedCompletionStatusempfangen werden.
Rückgabecodes
Die HTTP-Server-API gibt drei Klassen von Codes für asynchrone Funktionsaufrufe zurück.
- KEIN _ FEHLER
- FEHLER _ _ E/A AUSSTEHEND
- Jeder andere Systemfehlercode.
Wenn ERROR _ IO _ PENDING oder NO _ ERROR vom asynchronen Funktionsaufruf zurückgegeben wird, sollten Benutzer erwarten, dass die Ereignis- oder Abschlussroutine signalisiert wird. Durch Aufrufen der GetOverlappedResult-Funktion für das Ereignis oder der GetQueuedCompletionStatus-Funktion für den Abschlussport wird der Abschlussstatus zurückgegeben. Wenn NO ERROR zurückgegeben wird, können Anwendungen außerdem _ die Nachverarbeitung für denselben Thread durchführen, der den API-Aufruf ausgeführt hat.
Wenn die HTTP-Server-API vom asynchronen Funktionsaufruf etwas anderes als ERROR _ IO _ PENDING oder NO ERROR zurückgibt, _ wird die Abschlussroutine nicht signalisiert, und der Fehler wird direkt von der API zurückgegeben.