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.

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.