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.

[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.

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

Vedi anche

Funzioni dell'API server HTTP versione 1.0

HTTP_REQUEST

HttpReceiveRequestEntityBody

HttpSendHttpResponse

HttpSendResponseEntityBody