Funzione HttpReceiveHttpRequest (http.h)
La funzione HttpReceiveHttpRequest recupera la successiva richiesta HTTP disponibile dalla coda di richieste specificata in modo sincrono o asincrono.
Sintassi
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
);
Parametri
[in] RequestQueueHandle
Handle per la coda di richieste da cui recuperare la richiesta disponibile successiva. Viene creata una coda di richieste e il relativo handle restituito da una chiamata alla funzione HttpCreateRequestQueue .
Windows Server 2003 con SP1 e Windows XP con SP2: L'handle per la coda di richieste viene creato dalla funzione HttpCreateHttpHandle .
[in] RequestId
Nella prima chiamata per recuperare una richiesta, questo parametro deve essere HTTP_NULL_ID. Quindi, se sono necessarie più chiamate per recuperare l'intera richiesta, HttpReceiveHttpRequest o HttpReceiveRequestEntityBody può essere chiamato con RequestID impostato sul valore restituito nel membro RequestId della struttura HTTP_REQUEST a cui punta pRequestBuffer.
[in] Flags
Parametro che può essere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Vengono recuperate solo le intestazioni della richiesta; il corpo dell'entità non viene copiato. |
|
Il corpo dell'entità disponibile viene copiato insieme alle intestazioni della richiesta. Il membro pEntityChunks della struttura HTTP_REQUEST punta al corpo dell'entità. |
|
Tutti i corpi dell'entità vengono copiati insieme alle intestazioni della richiesta. Il membro pEntityChunks della struttura HTTP_REQUEST punta al corpo dell'entità. |
[out] RequestBuffer
Puntatore a un buffer in cui la funzione copia una struttura HTTP_REQUEST e il corpo dell'entità per la richiesta HTTP. HTTP_REQUEST. RequestId contiene l'identificatore per questa richiesta HTTP, che l'applicazione può usare nelle chiamate successive HttpReceiveRequestEntityBody, HttpSendHttpResponse o HttpSendResponseEntityBody.
[in] RequestBufferLength
Dimensioni, in byte, del buffer pRequestBuffer .
[out, optional] BytesReturned
Facoltativa. Puntatore a una variabile che riceve le dimensioni, in byte, del corpo dell'entità o della parte rimanente del corpo dell'entità.
Quando si effettua una chiamata asincrona tramite pOverlapped, impostare pBytesReceived su NULL. In caso contrario, quando pOverlapped è impostato su NULL, pBytesReceived deve contenere un indirizzo di memoria valido e non essere impostato su NULL.
[in, optional] Overlapped
Per le chiamate asincrone, impostare pOverlapped in modo che punti a una struttura OVERLAPPED ; per le chiamate sincrone, impostarlo su NULL.
Una chiamata sincrona si blocca finché una richiesta non è arrivata nella coda specificata e alcune o tutte le chiamate sono state recuperate, mentre una chiamata asincrona restituisce immediatamente ERROR_IO_PENDING e l'applicazione chiamante usa quindi le porte di completamento GetOverlappedResult o I/O per determinare quando l'operazione viene completata. Per altre informazioni sull'uso di strutture OVERLAPPED per la sincronizzazione, vedere
Sincronizzazione e input e output sovrapposti.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.
Se la funzione viene usata in modo asincrono, un valore restituito di ERROR_IO_PENDING indica che la richiesta successiva non è ancora pronta e verrà recuperata in un secondo momento tramite normali meccanismi di completamento di I/O sovrapposti.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.
| Valore | Significato |
|---|---|
|
Uno o più parametri forniti sono in formato inutilizzabile. |
|
Uno o più parametri forniti puntano a un buffer di memoria non valido o non idoneo. Il parametro pRequestBuffer deve puntare a un buffer di memoria valido con un allineamento della memoria uguale o superiore al requisito di allineamento della memoria per una struttura di HTTP_REQUEST . |
|
Il valore di RequestBufferLength è maggiore o uguale alla dimensione dell'intestazione della richiesta ricevuta, ma non è così grande della dimensione combinata della struttura della richiesta e del corpo dell'entità. Le dimensioni del buffer necessarie per leggere la parte rimanente del corpo dell'entità vengono restituite nel parametro pBytesReceived se non è NULL e se la chiamata è sincrona. Chiamare di nuovo la funzione con un buffer sufficientemente grande per recuperare tutti i dati. |
|
La richiesta specificata è già stata recuperata completamente; in questo caso, il valore a cui punta pBytesReceived non è significativo e pRequestBuffer non deve essere esaminato. |
|
Codice di errore di sistema definito in WinError.h. |
Commenti
Per recuperare una determinata richiesta, è possibile richiedere più chiamate. Quando il parametro Flags è impostato su zero, ad esempio HttpReceiveHttpRequest copia solo la struttura dell'intestazione della richiesta nel buffer e non tenta di copiare alcun corpo dell'entità. In questo caso, la funzione HttpReceiveRequestEntityBody può essere usata per recuperare il corpo dell'entità oppure è possibile effettuare una seconda chiamata a HttpReceiveHttpRequest.
In alternativa, il buffer fornito dall'applicazione potrebbe essere insufficiente per ricevere tutto o parte della richiesta. Per assicurarsi di ricevere almeno una parte della richiesta, è consigliabile che un'applicazione fornisca almeno un buffer di 4 KB, che supporta la maggior parte delle richieste HTTP. In alternativa, le intestazioni di autenticazione, analizzate come intestazioni sconosciute, possono aggiungere fino a 12 KB, quindi se viene usata l'autenticazione/autorizzazione, è consigliabile usare una dimensione del buffer di almeno 16 KB.
Se HttpReceiveHttpRequest restituisce ERROR_MORE_DATA, l'applicazione continua a effettuare chiamate aggiuntive, identificando la richiesta in ogni chiamata aggiuntiva passando il HTTP_REQUEST. Valore RequestId restituito dalla prima chiamata fino a quando non viene restituito ERROR_HANDLE_EOF.
Requisiti
| Client minimo supportato | Windows Vista, Windows XP con SP2 [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | http.h |
| Libreria | Httpapi.lib |
| DLL | Httpapi.dll |