HttpReceiveHttpRequest-Funktion (http.h)
Die HttpReceiveHttpRequest-Funktion ruft die nächste verfügbare HTTP-Anforderung entweder synchron oder asynchron aus der angegebenen Anforderungswarteschlange ab.
Syntax
HTTPAPI_LINKAGE ULONG HttpReceiveHttpRequest(
[in] HANDLE RequestQueueHandle,
[in] HTTP_REQUEST_ID RequestId,
[in] ULONG Flags,
[out] PHTTP_REQUEST RequestBuffer,
[in] ULONG RequestBufferLength,
[out, optional] PULONG BytesReturned,
[in, optional] LPOVERLAPPED Overlapped
);
Parameter
[in] RequestQueueHandle
Ein Handle für die Anforderungswarteschlange, aus der die nächste verfügbare Anforderung abgerufen werden soll. Eine Anforderungswarteschlange wird erstellt, und ihr Handle wird durch einen Aufruf der HttpCreateRequestQueue-Funktion zurückgegeben.
Windows Server 2003 mit SP1 und Windows XP mit SP2: Das Handle für die Anforderungswarteschlange wird von der HttpCreateHttpHandle-Funktion erstellt.
[in] RequestId
Beim ersten Aufruf zum Abrufen einer Anforderung sollte dieser Parameter HTTP_NULL_ID werden. Wenn dann mehr als ein Aufruf erforderlich ist, um die gesamte Anforderung abzurufen, können HttpReceiveHttpRequest oder HttpReceiveRequestEntityBody aufgerufen werden, wobei RequestID auf den Wert festgelegt ist, der im RequestId-Member der HTTP_REQUEST Struktur zurückgegeben wird, auf die pRequestBuffer verweist.
[in] Flags
Ein Parameter, der einer der folgenden Werte sein kann.
| Wert | Bedeutung |
|---|---|
|
Es werden nur die Anforderungsheader abgerufen. der Entitätstext wird nicht kopiert. |
|
Der verfügbare Entitätstext wird zusammen mit den Anforderungsheadern kopiert. Das pEntityChunks-Element der HTTP_REQUEST-Struktur zeigt auf den Entitätstext. |
|
Alle Entitätstexte werden zusammen mit den Anforderungsheadern kopiert. Das pEntityChunks-Element der HTTP_REQUEST-Struktur zeigt auf den Entitätstext. |
[out] RequestBuffer
Ein Zeiger auf einen Puffer, in den die Funktion eine HTTP_REQUEST Struktur und Entitätstext für die HTTP-Anforderung kopiert. HTTP_REQUEST. RequestId enthält den Bezeichner für diese HTTP-Anforderung, den die Anwendung in nachfolgenden Aufrufen von HttpReceiveRequestEntityBody, HttpSendHttpResponse oder HttpSendResponseEntityBody verwenden kann.
[in] RequestBufferLength
Größe des pRequestBuffer-Puffers in Bytes.
[out, optional] BytesReturned
Optional. Ein Zeiger auf eine Variable, die die Größe des Entitätstexts oder des verbleibenden Teils des Entitätstexts in Bytes empfängt.
Wenn Sie einen asynchronen Aufruf mithilfe von pOverlapped ausführen, legen Sie pBytesReceived auf NULL fest. Andernfalls muss pBytesReceived eine gültige Speicheradresse enthalten und nicht auf NULL festgelegt werden, wenn pOverlapped auf NULL festgelegt ist.
[in, optional] Overlapped
Legen Sie bei asynchronen Aufrufen pOverlapped so fest, dass er auf eine OVERLAPPED-Struktur verweist. Legen Sie für synchrone Aufrufe auf NULL fest.
Ein synchroner Aufruf blockiert, bis eine Anforderung in der angegebenen Warteschlange eingetroffen ist und ein Teil oder alles abgerufen wurde, während ein asynchroner Aufruf sofort ERROR_IO_PENDING zurückgibt und die aufrufende Anwendung dann GetOverlappedResult - oder E/A-Vervollständigungsports verwendet, um zu bestimmen, wann der Vorgang abgeschlossen ist. Weitere Informationen zur Verwendung von OVERLAPPED-Strukturen für die Synchronisierung finden Sie unter
Synchronisierung und überlappende Eingabe und Ausgabe.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion asynchron verwendet wird, gibt ein Rückgabewert von ERROR_IO_PENDING an, dass die nächste Anforderung noch nicht bereit ist und später über normale überlappende E/A-Vervollständigungsmechanismen abgerufen wird.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Wert | Bedeutung |
|---|---|
|
Mindestens einer der angegebenen Parameter ist in einer nicht verwendbaren Form. |
|
Mindestens ein parameter verweist auf einen ungültigen oder nicht ausgerichteten Speicherpuffer. Der pRequestBuffer-Parameter muss auf einen gültigen Speicherpuffer mit einer Speicherausrichtung verweisen, die der Speicherausrichtungsanforderung für eine HTTP_REQUEST-Struktur entspricht. |
|
Der Wert von RequestBufferLength ist größer oder gleich der Größe des empfangenen Anforderungsheaders, ist aber nicht so groß wie die kombinierte Größe der Anforderungsstruktur und des Entitätstexts. Die zum Lesen des restlichen Teils des Entitätstexts erforderliche Puffergröße wird im pBytesReceived-Parameter zurückgegeben, wenn dieser nicht NULL ist und wenn der Aufruf synchron ist. Rufen Sie die Funktion erneut mit einem ausreichend großen Puffer auf, um alle Daten abzurufen. |
|
Die angegebene Anforderung wurde bereits vollständig abgerufen. in diesem Fall ist der Wert, auf den pBytesReceived verweist, nicht aussagekräftig, und pRequestBuffer sollte nicht untersucht werden. |
|
Ein in WinError.h definierter Systemfehlercode . |
Hinweise
Mehrere Aufrufe können erforderlich sein, um eine bestimmte Anforderung abzurufen. Wenn der Flags-Parameter beispielsweise auf Null festgelegt ist, kopiert HttpReceiveHttpRequest nur die Anforderungsheaderstruktur in den Puffer und versucht nicht, den Entitätstext zu kopieren. In diesem Fall kann die HttpReceiveRequestEntityBody-Funktion verwendet werden, um den Entitätstext abzurufen, oder ein zweiter Aufruf von HttpReceiveHttpRequest.
Alternativ kann der von der Anwendung bereitgestellte Puffer nicht ausreichend groß sein, um die Anforderung ganz oder teilweise zu empfangen. Um sicherzustellen, dass mindestens ein Teil der Anforderung empfangen wird, wird empfohlen, dass eine Anwendung mindestens einen Puffer von 4 KB bereitstellt, der die meisten HTTP-Anforderungen erfüllt. Alternativ können Authentifizierungsheader, die als unbekannte Header analysiert werden, bis zu 12 KB dazu addieren, sodass bei Verwendung der Authentifizierung/Autorisierung eine Puffergröße von mindestens 16 KB empfohlen wird.
Wenn HttpReceiveHttpRequestERROR_MORE_DATA zurückgibt, führt die Anwendung weitere Aufrufe aus, wobei die Anforderung in jedem weiteren Aufruf durch Übergeben des HTTP_REQUEST identifiziert wird. RequestId-Wert , der vom ersten Aufruf zurückgegeben wird, bis ERROR_HANDLE_EOF zurückgegeben wird.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP2 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | http.h |
| Bibliothek | Httpapi.lib |
| DLL | Httpapi.dll |