Export (0) Print
Expand All

IHttpResponse::Flush Method

IIS 7.0

Sends the existing content in the response buffer to the client.

virtual HRESULT Flush(
   IN BOOL fAsync,
   IN BOOL fMoreData,
   OUT DWORD* pcbSent,
   OUT BOOL* pfCompletionExpected = NULL
) = 0;

fAsync

[IN] true to complete the operation asynchronously; otherwise, false.

fMoreData

[IN] true to send more data in this response; otherwise, false.

pcbSent

[OUT] A pointer to a DWORD that receives the number of bytes sent to the client.

pfCompletionExpected

[OUT] A pointer to a Boolean value that receives whether an asynchronous completion is pending for this call.

An HRESULT. Possible values include, but are not limited to, those in the following table.

Value

Description

S_OK

Indicates that the operation was successful.

ERROR_INVALID_DATA

Indicates that the data is not valid.

ERROR_NOT_ENOUGH_MEMORY

Indicates that there is insufficient memory to perform the operation.

The Flush method sends the currently available response to the client. At a minimum, the response includes the status headers, but it will also include any response buffer that exists when you call the method.

Set the fMoreData parameter to true if more data will be returned after you call the Flush method, or set fMoreData to false if there is no data remaining.

The Flush method supports synchronous and asynchronous operation. Specify the mode of operation by setting the fAsync parameter to true if the operation is asynchronous, or set fAsync to false if the operation is synchronous.

NoteNote:

If you are calling this method asynchronously, you must return immediately after the call.

The following code example demonstrates how to use the Flush method to send the current response to the client. Because the Flush method has sent the response headers to the client, the subsequent call to the Clear method will have no effect.

#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;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;

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

        // Test for an error.
        if (pHttpResponse != NULL)
        {
            // Flush the response to the client.
            hr = pHttpResponse->Flush(false,true,&cbSent,&fCompletionExpected);
            // Test for an error.
            if (FAILED(hr))
            {
                // Set the error status.
                pProvider->SetErrorStatus( hr );
                // End additional processing.
                return RQ_NOTIFICATION_FINISH_REQUEST;
            }
            // Clear the response.
            pHttpResponse->Clear();
        }

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


Your module must export the RegisterModule function. You can export this function by creating a module definition (.def) file for your project, or you can compile the module by using the /EXPORT:RegisterModule switch. For more information, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Type

Description

Client

  • IIS 7.0 on Windows Vista

  • IIS 7.5 on Windows 7

  • IIS Express 7.5 on Windows XP, Windows Vista, Windows 7

  • IIS 8.0 on Windows 8 Client

Server

  • IIS 7.0 on Windows Server 2008

  • IIS 7.5 on Windows Server 2008 R2

  • IIS Express 7.5 on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2

  • IIS 8.0 on Windows Server 2012

Product

IIS 7.0, IIS 7.5, IIS Express 7.5, IIS 8.0

Header

Httpserv.h

Community Additions

ADD
Show:
© 2015 Microsoft