Funzione HttpReceiveRequestEntityBody (http.h)

Articolo
02/26/2024

La funzione HttpReceiveRequestEntityBody riceve dati aggiuntivi del corpo dell'entità per una richiesta HTTP specificata.

Sintassi

HTTPAPI_LINKAGE ULONG HttpReceiveRequestEntityBody(
  [in]            HANDLE          RequestQueueHandle,
  [in]            HTTP_REQUEST_ID RequestId,
  [in]            ULONG           Flags,
  [out]           PVOID           EntityBuffer,
  [in]            ULONG           EntityBufferLength,
  [out, optional] PULONG          BytesReturned,
  [in, optional]  LPOVERLAPPED    Overlapped
);

Parametri

[in] RequestQueueHandle

Handle alla coda della richiesta da cui recuperare i dati del corpo dell'entità specificati. 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 della coda della richiesta viene creato dalla funzione HttpCreateHttpHandle .

[in] RequestId

Identificatore della richiesta HTTP contenente il corpo dell'entità recuperata. Questo valore viene restituito nel membro RequestId della struttura HTTP_REQUEST da una chiamata alla funzione HttpReceiveHttpRequest . Questo valore non può essere HTTP_NULL_ID.

[in] Flags

Questo parametro può essere il valore del flag seguente.

Windows Server 2003 con SP1 e Windows XP con SP2: Questo parametro è riservato e deve essere zero.

Valore	Significato
HTTP_RECEIVE_REQUEST_ENTITY_BODY_FLAG_FILL_BUFFER	Specifica che il buffer verrà riempito con uno o più corpi di entità, a meno che non siano presenti corpi di entità rimanenti da copiare.

[out] EntityBuffer

Puntatore a un buffer che riceve i dati del corpo dell'entità.

[in] EntityBufferLength

Dimensioni, in byte, del buffer a cui punta il parametro pBuffer .

[out, optional] BytesReturned

facoltativo. Puntatore a una variabile che riceve le dimensioni, in byte, dei dati del corpo dell'entità restituiti nel buffer pBuffer .

Quando si esegue una chiamata asincrona usando 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 per puntare a una struttura OVERLAPPED ; per le chiamate sincrone, impostarla su NULL.

Una chiamata sincrona blocca fino a quando non vengono recuperati i dati del corpo dell'entità, 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 output sovrapposti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è 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 viene recuperata in seguito 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
ERROR_INVALID_PARAMETER	Uno o più dei parametri forniti sono in un formato inutilizzabile.
ERROR_HANDLE_EOF	Il corpo dell'entità specificato è già stato recuperato; in questo caso, il valore puntato da pBytesReceived non è significativo e pBuffer non deve essere esaminato.
ERROR_DLL_INIT_FAILED	L'applicazione chiamante non ha chiamato HttpInitialize prima di chiamare questa funzione.
Altri	Codice di errore di sistema definito in WinError.h.

Commenti

Per recuperare un intero corpo di entità, è previsto che un'applicazione chiami HttpReceiveRequestEntityBody, passando nuovi buffer, fino a quando la funzione restituisce ERROR_HANDLE_EOF. Purché venga copiato correttamente un buffer pieno di dati del corpo dell'entità e siano presenti ancora più dati del corpo dell'entità in attesa di essere recuperati, la funzione restituisce NO_ERROR.

Requisiti

Requisito	Valore
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