Función HttpReceiveHttpRequest (http.h)
La función HttpReceiveHttpRequest recupera la siguiente solicitud HTTP disponible de la cola de solicitudes especificada de forma sincrónica o asincrónica.
Sintaxis
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
);
Parámetros
[in] RequestQueueHandle
Identificador de la cola de solicitudes desde la que recuperar la siguiente solicitud disponible. Se crea una cola de solicitudes y su identificador devuelto por una llamada a la función HttpCreateRequestQueue .
Windows Server 2003 con SP1 y Windows XP con SP2: El identificador de la cola de solicitudes se crea mediante la función HttpCreateHttpHandle .
[in] RequestId
En la primera llamada para recuperar una solicitud, este parámetro debe ser HTTP_NULL_ID. A continuación, si se requiere más de una llamada para recuperar toda la solicitud, se puede llamar a HttpReceiveHttpRequest o HttpReceiveRequestEntityBody con RequestID establecido en el valor devuelto en el miembro RequestId de la estructura de HTTP_REQUEST a la que apunta pRequestBuffer.
[in] Flags
Parámetro que puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
|
Solo se recuperan los encabezados de solicitud; el cuerpo de la entidad no se copia. |
|
El cuerpo de la entidad disponible se copia junto con los encabezados de solicitud. El miembro pEntityChunks de la estructura HTTP_REQUEST apunta al cuerpo de la entidad. |
|
Todos los cuerpos de entidad se copian junto con los encabezados de solicitud. El miembro pEntityChunks de la estructura HTTP_REQUEST apunta al cuerpo de la entidad. |
[out] RequestBuffer
Puntero a un búfer en el que la función copia una estructura de HTTP_REQUEST y un cuerpo de entidad para la solicitud HTTP. HTTP_REQUEST. RequestId contiene el identificador de esta solicitud HTTP, que la aplicación puede usar en llamadas posteriores HttpReceiveRequestEntityBody, HttpSendHttpResponse o HttpSendResponseEntityBody.
[in] RequestBufferLength
Tamaño, en bytes, del búfer pRequestBuffer .
[out, optional] BytesReturned
Opcional. Puntero a una variable que recibe el tamaño, en bytes, del cuerpo de la entidad o de la parte restante del cuerpo de la entidad.
Al realizar una llamada asincrónica mediante pOverlapped, establezca pBytesReceived enNULL. De lo contrario, cuando pOverlapped se establece en NULL, pBytesReceived debe contener una dirección de memoria válida y no establecerse en NULL.
[in, optional] Overlapped
Para las llamadas asincrónicas, establezca pOverlapped para que apunte a una estructura SUPERPUESTA ; para llamadas sincrónicas, establéztelo en NULL.
Una llamada sincrónica se bloquea hasta que una solicitud ha llegado a la cola especificada y algunos o todos ellos se han recuperado, mientras que una llamada asincrónica devuelve inmediatamente ERROR_IO_PENDING y la aplicación que realiza la llamada, a continuación, usa puertos de finalización de E/S o GetOverlappedResult para determinar cuándo se completa la operación. Para obtener más información sobre el uso de estructuras SUPERPUESTAs para la sincronización, consulte
Sincronización y entrada y salida superpuestas.
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.
Si la función se usa de forma asincrónica, un valor devuelto de ERROR_IO_PENDING indica que la siguiente solicitud aún no está lista y se recuperará más adelante a través de mecanismos de finalización de E/S superpuestos normales.
Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error.
| Valor | Significado |
|---|---|
|
Uno o varios de los parámetros proporcionados están en un formato inutilizable. |
|
Uno o varios de los parámetros proporcionados apuntan a un búfer de memoria no válido o no asignado. El parámetro pRequestBuffer debe apuntar a un búfer de memoria válido con una alineación de memoria igual o mayor al requisito de alineación de memoria para una estructura de HTTP_REQUEST . |
|
El valor de RequestBufferLength es mayor o igual que el tamaño del encabezado de solicitud recibido, pero no es tan grande como el tamaño combinado de la estructura de solicitud y el cuerpo de la entidad. El tamaño del búfer necesario para leer la parte restante del cuerpo de la entidad se devuelve en el parámetro pBytesReceived si no es NULL y si la llamada es sincrónica. Vuelva a llamar a la función con un búfer lo suficientemente grande como para recuperar todos los datos. |
|
La solicitud especificada ya se ha recuperado completamente; en este caso, el valor al que apunta pBytesReceived no es significativo y pRequestBuffer no debe examinarse. |
|
Código de error del sistema definido en WinError.h. |
Comentarios
Se puede requerir más de una llamada para recuperar una solicitud determinada. Cuando el parámetro Flags se establece en cero, por ejemplo, HttpReceiveHttpRequest solo copia la estructura del encabezado de solicitud en el búfer y no intenta copiar ninguno del cuerpo de la entidad. En este caso, la función HttpReceiveRequestEntityBody se puede usar para recuperar el cuerpo de la entidad o se puede realizar una segunda llamada a HttpReceiveHttpRequest.
Como alternativa, el búfer proporcionado por la aplicación puede ser insuficientemente grande para recibir toda o parte de la solicitud. Para asegurarse de recibir al menos parte de la solicitud, se recomienda que una aplicación proporcione al menos un búfer de 4 KB, que admite la mayoría de las solicitudes HTTP. Como alternativa, los encabezados de autenticación, analizados como encabezados desconocidos, pueden agregar hasta 12 KB, por lo que, si se usa la autenticación o autorización, se recomienda un tamaño de búfer de al menos 16 KB.
Si HttpReceiveHttpRequest devuelve ERROR_MORE_DATA, la aplicación continúa realizando llamadas adicionales, identificando la solicitud en cada llamada adicional pasando el HTTP_REQUEST. Valor RequestId devuelto por la primera llamada hasta que se devuelve ERROR_HANDLE_EOF .
Requisitos
| Cliente mínimo compatible | Windows Vista, Windows XP con SP2 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | http.h |
| Library | Httpapi.lib |
| Archivo DLL | Httpapi.dll |