How to Use the HTTP Whole Message Filter APIs

The HTTP Whole Message Filter APIs provide an interface for implementing custom encoding and decoding mechanisms for a Web Accelerator. The methods that you implement must optimise HTTP request data (for sending to the network) and decode data received back into HTTP.

To use the HTTP Whole Message Filter APIs you will need to perform the following tasks:

• Implement the MHTTPDataOptimiser Interface

• Register your optimiser

To enable support for Web Acceleration, you must implement your own custom encoding and decoding mechanisms by implementing the functions of the interface MHTTPDataOptimiser. The following code illustrates the MHTTPDataOptimiser interface that consists of the EncodeL() and DecodeL() methods:

class MHTTPDataOptimiser
{

public:

virtual void EncodeL(const TDesC8& aHTTPData, HBufC8*& aEncodedData) = 0;
    
virtual void DecodeL(const TDesC8& aData, HBufC8*& aHTTPData, TBool&    aTransFail) = 0;

};

This method converts HTTP request data (to your selected network optimisation protocol format) before it is sent across the TCP connection. This method has the following parameters:

• aHTTPData: Contains HTTP request data in standard HTTP format.

• aEncodedData: On return contains encoded HTTP request data in a network optimisation protocol format.

Note: It is assumed that you define a custom optimisation mechanism to encode the HTTP request data by implementing the EncodeL() method.

This method converts the HTTP response data in your selected network optimisation protocol format back to the standard HTTP response data format. This method has the following parameters:

• aData: Contains the raw data in a network optimisation protocol format received over the TCP connection.

• aHTTPData: On return of this method the aHTTPData parameter contains the HTTP response data.

• aTransFail: When you set this parameter value to ETrue it sends the KErrHTTPOptimiserFailsTrans event to the mobile browser application.

Note: In a scenario where the HTTP response data is split across various packets (for example, when the network bandwidth is low), the MHTTPDataOptimiser::DecodeL() method is called for every data packet received. In this scenario, to ensure successful parsing of the HTTP response data, the aTransFail parameter must be set to EFalse for every call made to MHTTPDataOptimiser::DecodeL(), until the final transaction is encountered.

You must register your optimiser (MHTTPDataOptimiser) with the HTTP Framework to enable support for Web Acceleration. You can enable the optimiser for a complete session or a particular transaction. Once the optimiser is enabled the HTTP framework calls the EncodeL() and DecodeL() functions automatically when HTTP data is sent and received respectively. The subsequent sections describe how to enable the optimiser for a session or transaction.

You must use the RHTTPSession::SetupHTTPDataOptimiser() function of the RHTTPSession class to enable the MHTTPDataOptimiser implementation for a session. The following code illustrates the RHTTPSession class:

class RHTTPSession 
{
public:
……  

RHTTPSession::SetupHTTPDataOptimiser (MHTTPDataOptimiser& aHTTPOptimiser);

MHTTPDataOptimiser* RHTTPSession::HTTPDataOptimiser ();

};

For a session, if you want to prevent a transaction from using the MHTTPDataOptimiser implementation, see the Overriding the optimiser for a session section.

Note: For more information about how to enable the MHTTPDataOptimiser implementation for a session, see the HTTP Whole Message Filter example section.

Overriding the optimiser for a session

By default, if the MHTTPDataOptimiser implementation is enabled for a session, it applies to all transactions within the session when the MHTTPDataOptimiser implementation is not enabled for individual transactions. In a scenario where you want to prevent a particular transaction (for which MHTTPDataOptimiser implementation is not enabled) of a session from using the MHTTPDataOptimiser implementation of the session, set the EHTTPTransOptimiser property with the value EDisableHTTPTransOptimiser on that transaction.

The following code illustrates how to set the EHTTPTransOptimiser property:

// HTTP session object
RHTTPSession sess; 

// The MHTTPDataOptimiser implementation is enabled for a session.
sess.SetupHttpDataOptimiser(*this); 

// HTTP transaction object
RHTTPTransaction trans = sess.OpenTransactionL(const TUriC8&, MHTTPTransactionCallback&, RStringF);
THTTPHdrVal disableOptimiser(sess.StringPool().StringF(HTTP::EDisableHTTPTransOptimiser,   RHTTPSession::GetTable()));
trans.PropertySet().SetPropertyL(sess.StringPool().StringF(HTTP::EHTTPTransOptimiser,   RHTTPSession::GetTable()), disableOptimiser);

You must use the RHTTPTransaction::SetupHTTPDataOptimiser() function of the RHTTPTransaction class to enable the MHTTPDataOptimiser implementation for a particular transaction. The following code illustrates the RHTTPTransaction class:

class RHTTPTransaction
{   
public:
……

RHTTPTransaction::SetupHTTPDataOptimiser (MHTTPDataOptimiser& aHTTPOptimiser);

MHTTPDataOptimiser* RHTTPTransaction::HTTPDataOptimiser ();

};

Note: For more information about how to enable the MHTTPDataOptimiser implementation for a transaction, see the HTTP Whole Message Filter example section.

The following diagram illustrates the class relationship between the MHTTPDataOptimiser interface and the RHTTPSession class:

For more information about MHTTPTransactionCallback, see A simple HTTP Client session.

The following code segment illustrates how to define the header file required for implementing the HTTP Whole Message Filter APIs:

#include <http.h>

class CMyHTTPClient: public CBase,
                    public MHTTPTransactionCallback,
                    public MHttpDataOptimiser
{
public: // methods from MHTTPTransactionCallback
    virtual void MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent);
    virtual TInt MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent);
    
public: // methods from MHttpDataOptimiser
    virtual void EncodeL (const TDesC8& aHttpData, HBufC8*& aEncodedData);
    virtual void DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail);
};

The following code segment illustrates how HTTP Whole Message Filter APIs can be used to enable support for Web Acceleration:

#include "CMyHTTPClient.h"

//  CMyHTTPClient.cpp
//
// Copyright ©) Symbian Software Ltd 2007.  All rights reserved.
//
//  defines CMyHTTPClient class: CMyHTTPClient
// Literals used in the file
_LIT8(KHttpAuthenticationUrl,       "http://remix.kwed.org");


void CMyHTTPClient::CreateTransactionL()
    {
    TUriParser8 up;
    up.Parse(KHttpAuthenticationUrl);

    RHTTPSession session;
    RHTTPTransaction trans;
    
    // Open the HTTP session
    session.OpenL();
    CleanupClosePushL(session);

    RStringPool strP = session.StringPool();

  //To enable MHTTPDataOptimiser for transaction

    // Open a GET transaction, specifying this object as the request body data supplier
    trans = session.OpenTransactionL(up, *this, strP.StringF(HTTP::EGET,RHTTPSession::GetTable()));
    CleanupClosePushL(trans);
    trans.SetupHttpDataOptimiser(*this);

 trans.SubmitL();
    CleanupStack::PopAndDestroy(&trans);
    CActiveScheduler::Start();
    
    CleanupStack::PopAndDestroy(&session); //Closes the session

    }

TInt CMyHTTPClient::MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent)
    {
    // Handle Error appropriately
    }

void CMyHTTPClient::MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent)
    {
    // Handle events from the framework.
    switch (aEvent.iStatus)
        {
        case KErrHttpOptimiserFailsTrans:
            {
            INFO_PRINTF1(_L("Cancelling/Failing Transaction\n"));
            aTransaction.Fail(THTTPFilterHandle::EProtocolHandler);
            } break;

        }
    return;
    //The following statement is used to eliminate leavescan errors
    User::Leave(KErrGeneral);
    }

void CMyHTTPClient::EncodeL (const TDesC8& aHttpData, HBufC8* &aEncodedData)
    {
    //Provide your own custom encoding implementation
    }

void CMyHTTPClient::DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail)
    {
    //Provide your own custom decoding implementation
    }

This code enables the MHTTPDataOptimiser for a transaction by using RHTTPTransaction::SetupHTTPDataOptimiser() and also illustrates where custom encoding and decoding mechanisms are implemented.

Note: Alternatively, in this code, you can use the following code segment to enable MHTTPDataOptimiser for a particular session.

session.SetupHttpDataOptimiser(*this);

• Overview of HTTP Whole Message Filter APIs

• Using HTTP Client