IHttpRequest::ReadEntityBody, méthode

Article
07/19/2023

Retourne le corps de l’entité de requête HTTP.

Syntaxe

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

Paramètres

pvBuffer
[OUT] Pointeur vers une mémoire tampon qui reçoit le corps de la requête.

cbBuffer
[IN] Taille, en octets, de la mémoire tampon pointée vers pvBuffer.

fAsync
[IN] true pour terminer l’opération de manière asynchrone ; sinon, false.

pcbBytesReceived
[OUT] Pointeur vers une DWORD mémoire tampon qui reçoit le nombre d’octets effectivement lus si l’appel de méthode se termine de manière synchrone.

pfCompletionPending
[OUT] Pointeur vers une mémoire tampon booléenne qui reçoit une valeur qui spécifie si une complétion asynchrone est en attente.

Valeur renvoyée

Élément HRESULT. Les valeurs possibles sont notamment celles figurant dans le tableau suivant.

Valeur	Description
S_OK	Indique que l’opération a réussi.
ERROR_CONNECTION_INVALID	Indique que le nombre d’octets de la requête actuelle est incorrect.
ERROR_HANDLE_EOF	Indique qu’il n’y a pas de données restantes à lire.
ERROR_INVALID_PARAMETER	Indique qu’une valeur non valide a été passée dans l’un des paramètres.
ERROR_NOT_ENOUGH_MEMORY	Indique que la mémoire est insuffisante pour effectuer l’opération.

Remarques

La ReadEntityBody méthode prend en charge les appels synchrones et asynchrones.

Notes

Si vous appelez la ReadEntityBody méthode de manière asynchrone, votre module doit revenir immédiatement après l’appel.

Une fois la ReadEntityBody méthode appelée, la pvBuffer mémoire tampon contient le corps de la requête et la pcbBytesReceived mémoire tampon contient la taille, en octets, du corps de la requête qui a été retourné dans la pvBuffer mémoire tampon si l’appel de méthode s’est terminé de manière synchrone.

En outre, la pfCompletionPending mémoire tampon contient une valeur booléenne qui spécifie si une exécution asynchrone est en attente.

Exemple

L’exemple de code suivant montre comment utiliser la ReadEntityBody méthode pour créer un module HTTP qui récupère une section de mémoire tampon de 1 Ko à partir de la requête actuelle.

#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
    );
}

Votre module doit exporter la fonction RegisterModule . Vous pouvez exporter cette fonction en créant un fichier de définition de module (.def) pour votre projet, ou vous pouvez compiler le module à l’aide du /EXPORT:RegisterModule commutateur. Pour plus d’informations, consultez Procédure pas à pas : création d’un module HTTP Request-Level à l’aide de code natif.

Vous pouvez éventuellement compiler le code à l’aide de la __stdcall (/Gz) convention d’appel au lieu de déclarer explicitement la convention d’appel pour chaque fonction.

Spécifications

Type	Description
Client	- IIS 7.0 sur Windows Vista - IIS 7.5 sur Windows 7 - IIS 8.0 sur Windows 8 - IIS 10.0 sur Windows 10
Serveur	- IIS 7.0 sur Windows Server 2008 - IIS 7.5 sur Windows Server 2008 R2 - IIS 8.0 sur Windows Server 2012 - IIS 8.5 sur Windows Server 2012 R2 - IIS 10.0 sur Windows Server 2016
Produit	- 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
En-tête	Httpserv.h

Voir aussi

IHttpRequest, interface
IHttpRequest::GetRemainingEntityBytes, méthode
IHttpRequest::InsertEntityBody, méthode

Partager via