A simple HTTP client session

This page describes each of the stages needed to use HTTP for a single, simple transaction. The code fragments are taken from HTTPEXAMPLECLIENT.

A new HTTP Client session is started by declaring an RHTTPSession object, which must remain in scope for the duration of the session, and invoking the RHTTPSession::OpenL() method. Usually, the RHTTPSession handle is a data member of a client class:

From the example header file httpexampleclient.h:

class CHttpClient : public CBase, ...
    {
    ...
private:
    RHTTPSession iSess;
    ...
    };

From the example implementation file httpexampleclient.cpp:

void CHttpClient::ConstructL()
    {
    ...
    iSession.OpenL();
    ...
    }

To create a new transaction within the session, the client must specify a URI, an HTTP method, and a callback object that is used to receive events that arise during the transaction. The callback object must implement the MHTTPTransactionCallback interface.

The RHTTPTransaction handle returned by the session uniquely identifies the new transaction. It may be stored in a class data member, but this is not mandatory.

void CHttpClient::InvokeHttpMethodL(const TDesC8& aUri, RStringF aMethod)
    {
    ...
    TUriParser8 uri; 
    uri.Parse(aUri);  
    iTrans = iSess.OpenTransactionL(uri, *iTransObs, aMethod);
    ...
    };

The second parameter to RHTTPSession::OpenTransactionL() provides the transaction callback. The class which implements the callback is separate in HTTPEXAMPLECLIENT. From the header file httpexampleclient.h:

class CHttpEventHandler : public CBase, public MHTTPTransactionCallback
    {
public:
 ...
    //
    // methods from MHTTPTransactionCallback
    //
    virtual void MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent);
    virtual TInt MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent);
 ...
 };

The two callback methods are inherited from MHTTPFilterBase: hence the MHF prefix to their names. This is an interesting feature of the HTTP Client design where the client code is treated as a filter. The use of these methods is described subsequently.

After opening the transaction, the client may set request headers, if required. Note that the use of request headers is optional for very simple transactions, as the few headers that RFC 2616 describes as mandatory for HTTP/1.1 are automatically generated.

To access the headers associated with a transaction's request or response, the RHTTPHeaders class is used. The handle is obtained from either the RHTTPRequest or RHTTPResponse objects associated with the transaction.

From the implementation file httpexampleclient.cpp:

RHTTPHeaders hdr = iTrans.Request().GetHeaderCollection();
    // Add headers appropriate to all methods
    SetHeaderL(hdr, HTTP::EUserAgent, KUserAgent);
    SetHeaderL(hdr, HTTP::EAccept, KAccept);
...

void CHttpClient::SetHeaderL(RHTTPHeaders aHeaders, TInt aHdrField, const TDesC8& aHdrValue)
    {
    RStringF valStr = iSess.StringPool().OpenFStringL(aHdrValue);
    CleanupClosePushL(valStr);
    THTTPHdrVal val(valStr); 
    aHeaders.SetFieldL(iSess.StringPool().StringF(aHdrField,RHTTPSession::GetTable()), val);
    CleanupStack::PopAndDestroy(&valStr);
    }

Note that the header field types are specified using enumerations from the HTTP namespace, e.g. HTTP::EUserAgent. The class used to hold the header field value, THTTPHdrVal, is like a C++ union, that is, it can hold different data types. In this example, it holds an RStringF value which is initialized using the session's string-pool from the supplied descriptor. These must be 8-bit strings, as the RFC 2616 assumes a 7-bit encoding for all transmissions.

When headers have been set, a simple transaction with no request body can be started immediately. This is the case for HTTP methods such as GET, HEAD, and TRACE. Some other HTTP methods include a body in the request, for example, POST. The data supplier that the client uses to supply request body data must be associated with the transaction before the transaction is started.

In HTTPEXAMPLECLIENT, the CHttpClient class also acts as its own data supplier when the POST method is chosen in the menu. See Handling request body data for examples of code that provides a request body.

When the transaction ready to start, the client calls RHTTPTransaction::SubmitL() to indicate that the request should be submitted. From the implementation file httpexampleclient.cpp:

...
    // submit the transaction
    iTrans.SubmitL();
    // Start the scheduler, once the transaction completes or is cancelled on an error the scheduler will be
    // stopped in the event handler
    CActiveScheduler::Start();

The HTTPEXAMPLECLIENT application is implemented as a synchronous client, hence the local CActiveScheduler. When CActiveScheduler::Stop() is called after completion of the transaction, execution continues from this point. More complex applications will have an active scheduler elsewhere that should already be running.

The transaction is now processed by HTTP. All processing by the internal HTTP core and protocol and transport handlers is done in the client's thread. As data is received from the HTTP server, events are generated internally and passed back to the client using the session filters. When an event reaches the client, HTTP invokes the transaction callback.

From the implementation file httpexampleclient.cpp:

void CHttpEventHandler::MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent)
    {
    switch (aEvent.iStatus)
        {
        case THTTPEvent::EGotResponseHeaders:
            {
            ...
            } 
            break;
        case THTTPEvent::EGotResponseBodyData:
            {
            ...
            } 
            break;
        case THTTPEvent::EResponseComplete:
            {
            ...
            } 
            break;
        case THTTPEvent::ESucceeded:
            {
            ...
            } 
            break;
        case THTTPEvent::EFailed:
            {
            ...
            } 
            break;
  case THTTPEvent::ERedirectedPermanently:
            {
            ...
            } 
            break;
  case THTTPEvent::ERedirectedTemporarily:
            {
            ...
            } 
            break;
        default:
            {
            ...
            } 
            break;
        }
    }

Events are processed in turn by the client. They arrive in the order shown in the preceding example code. The following list describes the events:

• THTTPEvent::EGotResponseHeaders indicates that the response status is known, and that the headers from the response are ready for access by the client. This event will always be the first received, unless an error condition has arisen.

• THTTPEvent::EGotResponseBodyData indicates that some body data is ready for processing. Response bodies are generally large enough to require splitting into smaller pieces (due to the use of fixed-size internal buffers), so the event will arrive as many times as there are pieces, until the whole body has been retrieved.

• THTTPEvent::EResponseComplete indicates that the transaction's response has been completely received. The client can now expect to be told whether the transaction was successful or not.

• THTTPEvent::ESucceeded is one of two possible final messages: it indicates success of the transaction.

• THTTPEvent::EFailed is the second of the two possible final messages: it indicates failure of the transaction.

• THTTPEvent::ERedirectedPermanently indicates that the transaction has been redirected and the HTTP origin server indicated that it was a permanent redirection. The URI for the transaction is now the redirected location.

• THTTPEvent::ERedirectedTemporarily indicates that the transaction has been redirected and the HTTP origin server indicated that it was a temporary redirection.

• default: an unrecognised event. Negative values indicate an error propogated from filters or lower comms layers. If not understood by the client, error values may be safely ignored as a THTTPEvent::EFailed event is guaranteed to follow. Positive values are used for warning conditions.

To obtain the response status code and text description, the transaction response is used:

case THTTPEvent::EGotResponseHeaders:
    {
    RHTTPResponse resp = aTransaction.Response();
    TInt status = resp.StatusCode();
    RStringF statusStr = resp.StatusText();

The response headers can be iterated using the THTTPHdrFieldIter class. Individual header fields can be queried as shown in the following example:

RHTTPResponse resp = aTrans.Response();
    RStringPool strP = aTrans.Session().StringPool();
    RHTTPHeaders hdr = resp.GetHeaderCollection();
    THTTPHdrFieldIter it = hdr.Fields();

    TBuf<KMaxHeaderNameLen>  fieldName16;
    TBuf<KMaxHeaderValueLen> fieldVal16;

    while (it.AtEnd() == EFalse)
    {
    // Get the name of the next header field
    RStringTokenF fieldName = it();
    RStringF fieldNameStr = strP.StringF(fieldName);

    // Check it does indeed exist
    THTTPHdrVal fieldVal;
    if (hdr.GetField(fieldNameStr,0,fieldVal) == KErrNone)
        {
        ...
        // Display realm for WWW-Authenticate header
        RStringF wwwAuth = strP.StringF(HTTP::EWWWAuthenticate,RHTTPSession::GetTable());
        if (fieldNameStr == wwwAuth)
            {
            // check the auth scheme is 'basic'
            RStringF basic = strP.StringF(HTTP::EBasic,RHTTPSession::GetTable());
            RStringF realm = strP.StringF(HTTP::ERealm,RHTTPSession::GetTable());
            THTTPHdrVal realmVal;
            if ((fieldVal.StrF() == basic) && 
            // check the header has a 'realm' parameter 
            (!hdr.GetParam(wwwAuth, realm, realmVal)))
                {
                RStringF realmValStr = strP.StringF(realmVal.StrF());
                fieldVal16.Copy(realmValStr.DesC());
                iUtils.Test().Printf(_L("Realm is: %S\n"), &fieldVal16);
                realmValStr.Close();
                }
            }
            basic.Close();
            realm.Close();
        }
        // Advance the iterator
        ++it;
        // Close all RStrings
        fieldName.Close();
        fieldNameStr.Close();
        wwwAuth.Close();
    }
    resp.Close();
    strP.Close();
    hdr.Close();

To access the response body, the data supplier contained in the transaction response must be used. When the client has finished processing each piece of body data, the data must be released:

case THTTPEvent::EGotResponseBodyData:
    {
    // Get the body data supplier
    iRespBody = aTransaction.Response().Body();

    // Some (more) body data has been received (in the HTTP response)
    if (iVerbose)
            DumpRespBody(aTransaction);
    else
            iUtils.Test().Printf(_L("*"));
    // Append to the output file if we're saving responses
    if (iSavingResponseBody)
            {
            TPtrC8 bodyData;
            TBool lastChunk = iRespBody->GetNextDataPart(bodyData);
            iRespBodyFile.Write(bodyData);
            if (lastChunk)
                iRespBodyFile.Close();
            }
 // Done with that bit of body data
    iRespBody->ReleaseData();
    } break;

The MHTTPDataSupplier::OverallDataSize() method can be used to find out how large the entire body is before processing the body data. The value returned is based on the HTTP response Content-Length header. However, not all responses will include this header. For example, when the HTTP server is using the 'chunked' transfer encoding. In that case, the overall data size will be returned as KErrNotFound.

Regardless of that, the final piece of body data will always cause MHTTPDataSupplier::GetNextDataPart() to return ETrue.

In HTTPEXAMPLECLIENT, the final completion of the transaction (indicated with a success or failure message) stops the local active scheduler. The EResponseComplete code is not used for anything here. Since each transaction is guaranteed to send either an ESucceeded event or an EFailed event, they can be used as a signal to finish.

case THTTPEvent::EResponseComplete:
            {
            // The transaction's response is complete
            iUtils.Test().Printf(_L("\nTransaction Complete\n"));
            } break;
        case THTTPEvent::ESucceeded:
            {
            iUtils.Test().Printf(_L("Transaction Successful\n"));
            aTransaction.Close();
            CActiveScheduler::Stop();
            } break;
        case THTTPEvent::EFailed:
            {
            iUtils.Test().Printf(_L("Transaction Failed\n"));
            aTransaction.Close();
            CActiveScheduler::Stop();
            } break;
        case THTTPEvent::ERedirectedPermanently:
            {
            iUtils.Test().Printf(_L("Permanent Redirection\n"));
            } break;
        case THTTPEvent::ERedirectedTemporarily:
            {
            iUtils.Test().Printf(_L("Temporary Redirection\n"));
            } break;

The transaction is closed using RHTTPTransaction::Close(). This internally frees the resources associated with that transaction. The transaction should not be used again.

When the client is ready to terminate, the session is closed:

CHttpClient::~CHttpClient()
    {
    iSess.Close();
    ...
    }

When the session is closed, all resources are returned to the system. Transactions that were not complete are immediately cancelled.