Metodo IHttpRequest::ReadEntityBody

Restituisce il corpo dell'entità richiesta HTTP.

Sintassi

virtual HRESULT ReadEntityBody(  
   OUT VOID* pvBuffer,  
   IN DWORD cbBuffer,  
   IN BOOL fAsync,  
   OUT DWORD* pcbBytesReceived,  
   OUT BOOL* pfCompletionPending = NULL  
) = 0;  

Parametri

pvBuffer
[OUT] Puntatore a un buffer che riceve il corpo della richiesta.

cbBuffer
[IN] Dimensioni, in byte, del buffer a cui punta pvBuffer.

fAsync
[IN] true per completare l'operazione in modo asincrono; in caso contrario, false.

pcbBytesReceived
[OUT] Puntatore a un DWORD buffer che riceve il numero di byte effettivamente letto se la chiamata al metodo completa in modo sincrono.

pfCompletionPending
[OUT] Puntatore a un buffer booleano che riceve un valore che specifica se un completamento asincrono è in sospeso.

Valore restituito

Oggetto HRESULT. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente.

Valore	Descrizione
S_OK	Indica che l'operazione ha avuto esito positivo.
ERROR_CONNECTION_INVALID	Indica che il numero di byte per la richiesta corrente non è corretto.
ERROR_HANDLE_EOF	Indica che non sono presenti dati rimanenti da leggere.
ERROR_INVALID_PARAMETER	Indica che un valore non valido è stato passato in uno dei parametri.
ERROR_NOT_ENOUGH_MEMORY	Indica che la memoria non è sufficiente per eseguire l'operazione.

Commenti

Il ReadEntityBody metodo supporta sia chiamate sincrone che asincrone.

Nota

Se si chiama il metodo in modo asincrono, il ReadEntityBody modulo deve restituire immediatamente dopo la chiamata.

Dopo aver chiamato il ReadEntityBody metodo, il pvBuffer buffer conterrà il corpo della richiesta e il pcbBytesReceived buffer conterrà le dimensioni, in byte, del corpo della richiesta restituito nel pvBuffer buffer se la chiamata al metodo è stata completata in modo sincrono.

Inoltre, il pfCompletionPending buffer conterrà un valore booleano che specifica se un completamento asincrono è in sospeso.

Esempio

Nell'esempio di codice seguente viene illustrato come usare il ReadEntityBody metodo per creare un modulo HTTP che recupera una sezione buffer di 1 KB dalla richiesta corrente.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>

// NOTE - Data needs to be passed to this module, e.g. a POST request, or it will not appear to return anything.

// Create the module class.
class MyHttpModule : public CHttpModule
{
public:
    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );

        // Create an HRESULT to receive return values from methods.
        HRESULT hr;

        // Create a data chunk.
        HTTP_DATA_CHUNK dataChunk;
        // Set the chunk to a chunk in memory.
        dataChunk.DataChunkType = HttpDataChunkFromMemory;

        // Clear the existing response.
        pHttpContext->GetResponse()->Clear();
        // Set the MIME type to plain text.
        pHttpContext->GetResponse()->SetHeader(
            HttpHeaderContentType,"text/plain",
            (USHORT)strlen("text/plain"),TRUE);

        // Allocate a 1K buffer.
        DWORD cbBytesReceived = 1024;
        void * pvRequestBody = pHttpContext->AllocateRequestMemory(cbBytesReceived);
        
        // Test for an error.
        if (NULL == pvRequestBody)
        {
            // Set the error status.
            hr = HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
            pProvider->SetErrorStatus( hr );
            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }

        if (pHttpContext->GetRequest()->GetRemainingEntityBytes() > 0)
        {
            // Loop through the request entity.
            while (pHttpContext->GetRequest()->GetRemainingEntityBytes() != 0)
            {

                // Retrieve the request body.
                hr = pHttpContext->GetRequest()->ReadEntityBody(
                    pvRequestBody,cbBytesReceived,false,&cbBytesReceived,NULL);
                // Test for an error.
                if (FAILED(hr))
                {
                    // End of data is okay.
                    if (ERROR_HANDLE_EOF != (hr  & 0x0000FFFF))
                    {
                        // Set the error status.
                        pProvider->SetErrorStatus( hr );
                        // End additional processing.
                        return RQ_NOTIFICATION_FINISH_REQUEST;
                    }
                }
                dataChunk.FromMemory.pBuffer = pvRequestBody;
                dataChunk.FromMemory.BufferLength = cbBytesReceived;
                
                hr = pHttpContext->GetResponse()->WriteEntityChunks(
                    &dataChunk,1,FALSE,TRUE,NULL);
                if (FAILED(hr))
                {
                    // Set the error status.
                    pProvider->SetErrorStatus( hr );
                    // End additional processing.
                    return RQ_NOTIFICATION_FINISH_REQUEST;
                }
            }
            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
};

// Create the module's class factory.
class MyHttpModuleFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        MyHttpModule * pModule = new MyHttpModule;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if the factory cannot create the instance.
            return HRESULT_FROM_WIN32( ERROR_NOT_ENOUGH_MEMORY );
        }
        else
        {
            // Return a pointer to the module.
            *ppModule = pModule;
            pModule = NULL;
            // Return a success status.
            return S_OK;
        }            
    }

    void Terminate()
    {
        // Remove the class from memory.
        delete this;
    }
};

// Create the module's exported registration function.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo * pModuleInfo,
    IHttpServer * pGlobalInfo
)
{
    UNREFERENCED_PARAMETER( dwServerVersion );
    UNREFERENCED_PARAMETER( pGlobalInfo );

    // Set the request notifications and exit.
    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST,
        0
    );
}

Il modulo deve esportare la funzione RegisterModule . È possibile esportare questa funzione creando un file di definizione del modulo (con estensione def) per il progetto oppure è possibile compilare il modulo usando l'opzione /EXPORT:RegisterModule . Per altre informazioni, vedere Procedura dettagliata: Creazione di un modulo HTTP Request-Level tramite codice nativo.

Facoltativamente, è possibile compilare il codice usando la __stdcall (/Gz) convenzione chiamante anziché dichiarare esplicitamente la convenzione chiamante per ogni funzione.

Requisiti

Tipo	Descrizione
Client	- IIS 7.0 in Windows Vista - IIS 7.5 in Windows 7 - IIS 8.0 in Windows 8 - IIS 10.0 in Windows 10
Server	- IIS 7.0 in Windows Server 2008 - IIS 7.5 in Windows Server 2008 R2 - IIS 8.0 in Windows Server 2012 - IIS 8.5 in Windows Server 2012 R2 - IIS 10.0 in Windows Server 2016
Prodotto	- IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7,5, IIS Express 8.0, IIS Express 10.0
Intestazione	Httpserv.h

Vedere anche

Interfaccia IHttpRequest
Metodo IHttpRequest::GetRemainingEntityBytes
Metodo IHttpRequest::InsertEntityBody