IHttpResponse::WriteEntityChunks-Methode

Artikel
07/19/2023

Fügt eine oder mehrere HTTP_DATA_CHUNK Strukturen an den Antworttext an.

Syntax

virtual HRESULT WriteEntityChunks(  
   IN HTTP_DATA_CHUNK* pDataChunks,  
   IN DWORD nChunks,  
   IN BOOL fAsync,  
   IN BOOL fMoreData,  
   OUT DWORD* pcbSent,  
   OUT BOOL* pfCompletionExpected = NULL  
) = 0;

Parameter

pDataChunks
[IN] Ein Zeiger auf eine oder HTTP_DATA_CHUNK mehrere Strukturen.

nChunks
[IN] Ein DWORD , der die Anzahl von Blöcken enthält, auf die von verwiesen wird pDataChunks.

fAsync
[IN] true , wenn die Methode asynchron abgeschlossen werden soll; falseandernfalls .

fMoreData
[IN] true , wenn in der Antwort mehr Daten gesendet werden sollen; false , wenn dies die letzten Daten sind.

pcbSent
[OUT] Die Anzahl der Bytes, die an den Client gesendet wurden, wenn der Aufruf synchron abgeschlossen wird.

pfCompletionExpected
[OUT] true , wenn für diesen Aufruf eine asynchrone Vervollständigung aussteht; falseandernfalls .

Rückgabewert

HRESULT. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.

Wert	BESCHREIBUNG
S_OK	Gibt an, dass der Vorgang erfolgreich war.
ERROR_INVALID_PARAMETER	Gibt an, dass der Parameter ungültig ist (z. B. ist der `pDataChunks` Zeiger auf NULL festgelegt).
ERROR_NOT_ENOUGH_MEMORY	Gibt an, dass nicht genügend Arbeitsspeicher zum Ausführen des Vorgangs vorhanden ist.
ERROR_ARITHMETIC_OVERFLOW	Der Antwort wurden mehr als 65535 Blöcke hinzugefügt.

Bemerkungen

Entwickler können die WriteEntityChunks -Methode verwenden, um eine einzelne HTTP_DATA_CHUNK Struktur oder ein Array von HTTP_DATA_CHUNK Strukturen in den Antworttext einzufügen. Wenn der Vorgang synchron abgeschlossen wurde, empfängt der pcbSent Parameter die Anzahl der Bytes, die in die Antwort eingefügt wurden.

Wenn die Pufferung aktiviert ist, erstellt die WriteEntityChunks Methode eine Kopie aller HTTP_DATA_CHUNK Strukturen, wodurch die zugrunde liegenden Daten dupliziert werden, sodass sie nicht beibehalten werden müssen. Wenn die Pufferung deaktiviert ist oder der Grenzwert für den Antwortpuffer erreicht ist, wird die Antwort von der WriteEntityChunks -Methode ebenfalls geleert. Wenn die Pufferung deaktiviert ist und der fAsync Parameter lautet true, muss der Arbeitsspeicher beibehalten werden, bis die Anforderung abgeschlossen ist.

Sie können einen WriteEntityChunks Vorgang so konfigurieren, dass er asynchron abgeschlossen wird, indem Sie den fAsync Parameter auf truefestlegen. In diesem Fall wird die WriteEntityChunks -Methode sofort an den Aufrufer zurückgegeben, und der pcbSent Parameter empfängt nicht die Anzahl der Bytes, die in die Antwort eingefügt wurden. Wenn die Pufferung deaktiviert ist und der fAsync Parameter den Wert aufweist true, muss der Arbeitsspeicher für den pDataChunks Parameter beibehalten werden, bis der asynchrone Aufruf abgeschlossen ist.

Maximal 65535 Blöcke (64 KB minus 1) können in eine Anforderung geschrieben werden.

Beispiel

Im folgenden Beispiel wird veranschaulicht, wie die WriteEntityChunks -Methode verwendet wird, um ein HTTP-Modul zu erstellen, das ein Array von zwei Datenblöcken in die Antwort einfügt. Im Beispiel wird dann die Antwort an einen Webclient zurückgegeben.

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

// 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 an array of data chunks.
        HTTP_DATA_CHUNK dataChunk[2];

        // Buffer for bytes written of data chunk.
        DWORD cbSent;
        
        // Create string buffers.
        PCSTR pszOne = "First chunk data\n";
        PCSTR pszTwo = "Second chunk data\n";

        // Retrieve a pointer to the response.
        IHttpResponse * pHttpResponse = pHttpContext->GetResponse();

        // Test for an error.
        if (pHttpResponse != NULL)
        {
            // Clear the existing response.
            pHttpResponse->Clear();
            // Set the MIME type to plain text.
            pHttpResponse->SetHeader(
                HttpHeaderContentType,"text/plain",
                (USHORT)strlen("text/plain"),TRUE);
            
            // Set the chunk to a chunk in memory.
            dataChunk[0].DataChunkType = HttpDataChunkFromMemory;
            // Set the chunk to the first buffer.
            dataChunk[0].FromMemory.pBuffer =
                (PVOID) pszOne;
            // Set the chunk size to the first buffer size.
            dataChunk[0].FromMemory.BufferLength =
                (USHORT) strlen(pszOne);

            // Set the chunk to a chunk in memory.
            dataChunk[1].DataChunkType = HttpDataChunkFromMemory;
            // Set the chunk to the second buffer.
            dataChunk[1].FromMemory.pBuffer =
                (PVOID) pszTwo;
            // Set the chunk size to the second buffer size.
            dataChunk[1].FromMemory.BufferLength =
                (USHORT) strlen(pszTwo);

            // Insert the data chunks into the response.
            hr = pHttpResponse->WriteEntityChunks(
                dataChunk,2,FALSE,TRUE,&cbSent);

            // Test for an error.
            if (FAILED(hr))
            {
                // Set the error status.
                pProvider->SetErrorStatus( hr );
            }
            // 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
    );
}

Ihr Modul muss die RegisterModule-Funktion exportieren. Sie können diese Funktion exportieren, indem Sie eine Moduldefinitionsdatei (.def) für Ihr Projekt erstellen, oder Sie können das Modul mithilfe des Schalters /EXPORT:RegisterModule kompilieren. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Erstellen eines Request-Level HTTP-Moduls mithilfe von nativem Code.

Sie können den Code optional kompilieren, indem Sie die __stdcall (/Gz) Aufrufkonvention verwenden, anstatt die Aufrufkonvention für jede Funktion explizit zu deklarieren.

Anforderungen

type	BESCHREIBUNG
Client	– IIS 7.0 unter Windows Vista – IIS 7.5 unter Windows 7 – IIS 8.0 unter Windows 8 – IIS 10.0 unter Windows 10
Server	– IIS 7.0 unter Windows Server 2008 – IIS 7.5 unter Windows Server 2008 R2 – IIS 8.0 unter Windows Server 2012 – IIS 8.5 unter Windows Server 2012 R2 – IIS 10.0 unter Windows Server 2016
Produkt	– 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
Header	Httpserv.h

Weitere Informationen

IHttpResponse-Schnittstelle
IHttpResponse::WriteEntityChunkByReference-Methode

Freigeben über