Symbian^3 Application Developer Library >

CProtocolHandler Class Reference

class CProtocolHandler : public CActive

An abstract protocol handler. Protocol handlers are required to act as the bridge between abstract representations of sessions, transactions and headers (the client side of the HTTP architecture) and specific comms transports (the network side of the architecture).

Each instance of a concrete subclass of CProtocolHandler is associated with a specific client session, and hence with a particular choice of proxy type, and by implication, transport type. It is designed to appear like a filter in order to be placed at the end of a session's filter queue. This allows it to receive transaction-related events in the same way that any other filter (or indeed, the client) does. An active object, it may implement a queuing system for submitted transactions, according to the chosen internal service model.

In order to divide the abstract functionality associated with handling the HTTP protocol handler from the specifics needed for a particular choice of transport, this class defines a number of pure virtual methods which allow it to defer transport-specific choices or mechamisms. These are mainly concerned with the service model (ie. allocation of transactions to objects that can handle them), the codec model (ie. on-demand encoding/decoding of HTTP header data) and general housekeeping (eg. instantiation and cleanup of objects at particular points in a transaction lifecycle).

Inherits from

Public Member Functions
~CProtocolHandler ()
IMPORT_C CHeaderCodec * Codec ()
IMPORT_C void MHFLoad ( RHTTPSession , THTTPFilterHandle )
IMPORT_C TInt MHFRunError ( TInt , RHTTPTransaction , const THTTPEvent &)
IMPORT_C void MHFRunL ( RHTTPTransaction , const THTTPEvent &)
IMPORT_C TInt MHFSessionRunError ( TInt , const THTTPSessionEvent &)
IMPORT_C void MHFSessionRunL (const THTTPSessionEvent &)
IMPORT_C void MHFUnload ( RHTTPSession , THTTPFilterHandle )
CProtocolHandler * NewL (const TDesC8 &, RHTTPSession )
void Reserved2 ()
IMPORT_C const CCertificate * SessionServerCert ()
TInt SessionServerCert ( TCertInfo &)
IMPORT_C const CCertificate * TransactionServerCert ( RHTTPTransaction )
TInt TransactionServerCert ( TCertInfo &, RHTTPTransaction )
Protected Member Functions
CProtocolHandler ( RHTTPSession )
IMPORT_C void CompleteSelf ()
IMPORT_C void ConstructL ( RHTTPSession )
IMPORT_C void DoCancel ()
IMPORT_C CProtTransaction * FindProtocolTransaction ( RHTTPTransaction )
IMPORT_C TInt FindTransaction ( RHTTPTransaction , const CProtTransaction *&)
void GetInterfaceL ( TUid , MProtHandlerInterface *&)
IMPORT_C TInt NumActiveTransactions ()
IMPORT_C TInt RunError ( TInt )
IMPORT_C void RunL ()
IMPORT_C TInt TransactionCompleted ( RHTTPTransaction , THTTPEvent )
IMPORT_C void TransactionCompletedL ( RHTTPTransaction , THTTPEvent )
IMPORT_C void TransactionFailed ( RHTTPTransaction )
Private Member Functions
void CancelTransactionHook ( CProtTransaction &)
void ClosedTransactionHook ( CProtTransaction *)
void CreateCodecL ()
CProtTransaction * CreateProtTransactionL ( RHTTPTransaction )
TInt FindTransaction ( RHTTPTransaction )
void HandleCancelTransaction ( RHTTPTransaction )
void HandleClosedTransaction ( RHTTPTransaction )
void NotifyNewRequestBodyPart ( CProtTransaction &)
TBool ServiceL ( CProtTransaction &)
void SubmitTransactionL ( RHTTPTransaction )
Inherited Functions
CActive::CActive(TInt)
CActive::Cancel()
CActive::Deque()
CActive::Extension_(TUint,TAny *&,TAny *)
CActive::IsActive()const
CActive::IsAdded()const
CActive::Priority()const
CActive::SetActive()
CActive::SetPriority(TInt)
CActive::~CActive()
CBase::CBase()
CBase::Delete(CBase *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Inherited Enumerations
CActive:TPriority
Protected Attributes
CHeaderCodec * iCodec
__DECLARE_LOG CSecurityPolicy * iSecurityPolicy
RHTTPSession iSession
Private Attributes
RHTTPTransaction iCurrentTransaction
TUid iDtor_ID_Key
RPointerArray < CProtTransaction > iTransactions
Inherited Attributes
CActive::iStatus

Constructor & Destructor Documentation

CProtocolHandler(RHTTPSession)

IMPORT_C CProtocolHandler ( RHTTPSession aSession ) [protected]

Constructs a protocol handler associated with the supplied HTTP client session.

Parameters

RHTTPSession aSession (in) The session on which the new protocol handler will be installed.

~CProtocolHandler()

IMPORT_C ~CProtocolHandler ( ) [virtual]

Intended Usage: Class destructor.

Member Functions Documentation

CancelTransactionHook(CProtTransaction &)

void CancelTransactionHook ( CProtTransaction & aTransaction ) [private, pure virtual]

Intended Usage: Called when the RHTTPTransaction object corresponding to aTrans has been cancelled by the client or an intermediate filter. This allows the concrete protocol handler to do any cleanup and to perform the necessary actions for cancellation on its transport layer.

This must be implemented by a concrete protocol handler sub-class.

Parameters

CProtTransaction & aTransaction

ClosedTransactionHook(CProtTransaction *)

void ClosedTransactionHook ( CProtTransaction * aTrans ) [private, pure virtual]

Intended Usage: Called when the RHTTPTransaction object corresponding to aTrans has been closed by the client. This allows the concrete protocol handler to do any cleanup required for this particular transaction.

Ownership of the CProtTransaction object is transferred back to the concrete protocol handler, which then has deletion responsibility for it. By the time this function has been called, the base protocol handler will have dequeued the transaction.

The client's RHTTPTransaction will be closed when this function returns, so it is not possible to send events to the client during the function's execution.

This must be implemented by a concrete protocol handler sub-class.

Parameters

CProtTransaction * aTrans (in) A pointer to the transaction about to be closed.

Codec()

IMPORT_C CHeaderCodec * Codec ( ) const

Obtain the protocol handler's header codec. CHeaderCodec

CompleteSelf()

IMPORT_C void CompleteSelf ( ) [protected]

Completes this active object - allows the protocol handler to reevaluate the queue of pending transactions and service new ones if possible.

ConstructL(RHTTPSession)

IMPORT_C void ConstructL ( RHTTPSession aSession ) [protected]

Second phase construction in which any necessary allocation is done Implementations of this interface may leave with KErrNoMemory

Parameters

RHTTPSession aSession The HTTP session on which this protocol handler will be installed.

CreateCodecL()

void CreateCodecL ( ) [private, pure virtual]

Intended usage: Creates the specific type of codec required for a specific type of protocol handler.

This must be implemented by a concrete protocol handler sub-class.

CreateProtTransactionL(RHTTPTransaction)

CProtTransaction * CreateProtTransactionL ( RHTTPTransaction aTransaction ) [private, pure virtual]

Intended Usage: Creates a representation of a client transaction to be used in the protocol handler. Since the protocol handler deals with the low- level data for a transaction as sent over a particular transport, an appropriate CProtTransaction-derived class is used that owns a CRxData and a CTxData to handle the low-level data.

This must be implemented by a concrete protocol handler sub-class.
leave
KErrNoMemory if there was not enough memory to create the object. create the object.
CRxData CTxData

Parameters

RHTTPTransaction aTransaction The RHTTPTransaction object associated with this CProtTransaction object.

DoCancel()

IMPORT_C void DoCancel ( ) [protected, virtual]

Intended Usage: Cancel outstanding asynchronous requests that this object has made

FindProtocolTransaction(RHTTPTransaction)

IMPORT_C CProtTransaction * FindProtocolTransaction ( RHTTPTransaction aTransaction ) const [protected]

Parameters

RHTTPTransaction aTransaction

FindTransaction(RHTTPTransaction, const CProtTransaction *&)

IMPORT_C TInt FindTransaction ( RHTTPTransaction aTransaction,
const CProtTransaction *& aProtTransaction
) const [protected]

Searches the array of CProtTransaction objects to if the aTransaction object is wrapped by one of them. If one is found aProtTransaction is set to it

Parameters

RHTTPTransaction aTransaction The transaction to search for.
const CProtTransaction *& aProtTransaction Reference to a CProtTransaction which will be set to the CProtTransaction which wraps the RHTTPTransaction.

FindTransaction(RHTTPTransaction)

TInt FindTransaction ( RHTTPTransaction aTransaction ) const [private]

Searches the array of CProtTransaction objects to if the aTransaction object is wrapped by one of them.

Parameters

RHTTPTransaction aTransaction The transaction to search for.

GetInterfaceL(TUid, MProtHandlerInterface *&)

void GetInterfaceL ( TUid aInterfaceId,
MProtHandlerInterface *& aInterfacePtr
) [protected, inline, virtual]

Intended Usage: This is a mechanism for allowing future change to CProtocolHandler API without breaking BC.

Parameters

TUid aInterfaceId the UID of the API function being called.
MProtHandlerInterface *& aInterfacePtr reference to pointer to actual function implementation (in the derived class)

HandleCancelTransaction(RHTTPTransaction)

void HandleCancelTransaction ( RHTTPTransaction aTrans ) [private]
Sets the state of the CProtTransaction object for this transaction to ECancelled, and resets the object. This object can be reused if the transaction is resubmitted.
Pre-condition
A CProtTransaction object exists for this transaction.
Post-condition
The state of the CProtTransaction object is set to ECancelled and it has been reset.

Parameters

RHTTPTransaction aTrans

HandleClosedTransaction(RHTTPTransaction)

void HandleClosedTransaction ( RHTTPTransaction aTrans ) [private]
Removes the CProtTransaction object for the transaction from the queue of CProtTransaction objects.
Pre-condition
A CProtTransaction object exists for this transaction.
Post-condition
The CProtTransaction object has been removed from the queue.

Parameters

RHTTPTransaction aTrans

MHFLoad(RHTTPSession, THTTPFilterHandle)

IMPORT_C void MHFLoad ( RHTTPSession aSession,
THTTPFilterHandle aHandle
) [virtual]

Intended Usage: Called when the filter is being added to the session's filter queue. MHTTFilter

Parameters

RHTTPSession aSession The session it's being added to.
THTTPFilterHandle aHandle The filter handle. Complex filters may need to keep track of this, for instance if generating events in response to external stimuli

MHFRunError(TInt, RHTTPTransaction, const THTTPEvent &)

IMPORT_C TInt MHFRunError ( TInt aError,
RHTTPTransaction aTransaction,
const THTTPEvent & aEvent
) [virtual]

Intended Usage: Called when RunL leaves from a transaction event. This works in the same way as CActve::RunError; return KErrNone if you have handled the error. If you don't completely handle the error, a panic will occur. MHTTPFilterBase

Parameters

TInt aError The leave code that RunL left with.
RHTTPTransaction aTransaction The transaction that was being processed.
const THTTPEvent & aEvent The Event that was being processed.

MHFRunL(RHTTPTransaction, const THTTPEvent &)

IMPORT_C void MHFRunL ( RHTTPTransaction aTransaction,
const THTTPEvent & aEvent
) [virtual]
Intended Usage: Called when the filter's registration conditions are satisfied for events that occur on a transaction. Any Leaves must be handled by the appropriate MHFRunError. Note that this function is not allowed to leave if called with certain events. THTTPEvent
leave
Standard Symbian OS error codes. e.g. KErrNoMemory.
MHTTPFilterBase

Parameters

RHTTPTransaction aTransaction The transaction that the event has occurred on.
const THTTPEvent & aEvent aEvent The event that has occurred.

MHFSessionRunError(TInt, const THTTPSessionEvent &)

IMPORT_C TInt MHFSessionRunError ( TInt aError,
const THTTPSessionEvent & aEvent
) [virtual]

Intended Usage: Called when MHFRunL leaves from a session event. This works in the same way as CActve::RunError. If you don't completely handle the error, a panic will occur. MHTTPFilterBase

Parameters

TInt aError The leave code that RunL left with.
const THTTPSessionEvent & aEvent The Event that was being processed.

MHFSessionRunL(const THTTPSessionEvent &)

IMPORT_C void MHFSessionRunL ( const THTTPSessionEvent & aEvent ) [virtual]
Intended Usage: Called when the filters registration conditions are satisfied for events that occur on the session. Any leaves must be handled by the appropriate MHFRunError.
leave
KErrNoMemory if an attempt to allocate memory has failed
leave
KErrHttpCantResetRequestBody if the request body needed to be rewound by the client but it doesn't support this
MHTTPFilterBase

Parameters

const THTTPSessionEvent & aEvent The session event that has occured.

MHFUnload(RHTTPSession, THTTPFilterHandle)

IMPORT_C void MHFUnload ( RHTTPSession aSession,
THTTPFilterHandle aHandle
) [virtual]

Intended Usage: Called when the filter is being removed from a session's filter queue. MHTTFilter

Parameters

RHTTPSession aSession The session it's being removed from
THTTPFilterHandle aHandle The filter handle. Complex filters may need to refer to this to keep track of which particular registration is being unloaded.

NewL(const TDesC8 &, RHTTPSession)

CProtocolHandler * NewL ( const TDesC8 & aProtocol,
RHTTPSession aSession
) [static]
Standard factory constructor. This is the ECOM interface class from which concrete protocol handlers are derived. The method queries ECOM for the protocol handler plugin that matches the protocol description passed in.
leave
KErrNoMemory if there was not enough memory to create the object.
Implementation of CProtocolHandler class *****************************************************

Parameters

const TDesC8 & aProtocol (in) The name of the protocol required.
RHTTPSession aSession (in) The HTTP session on which this protocol handler will be installed.

NotifyNewRequestBodyPart(CProtTransaction &)

void NotifyNewRequestBodyPart ( CProtTransaction & aTransaction ) [private, pure virtual]

Intended Usage: Called to notify the concrete protocol handler that new request body data is available for transmission.

This must be implemented by a concrete protocol handler sub-class.

Parameters

CProtTransaction & aTransaction

NumActiveTransactions()

IMPORT_C TInt NumActiveTransactions ( ) const [protected]

Obtain the number of currently active transactions

Reserved2()

void Reserved2 ( ) [inline, virtual]

Intended Usage: Reserve a slot in the v-table to preserve future BC

RunError(TInt)

IMPORT_C TInt RunError ( TInt aError ) [protected, virtual]

Intended Usage: Do any cleanup required should RunL leave

Parameters

TInt aError (in) The error code that RunL left with

RunL()

IMPORT_C void RunL ( ) [protected, virtual]

Intended Usage: Do some processing when a previous asynchronous request made by this object has completed.

ServiceL(CProtTransaction &)

TBool ServiceL ( CProtTransaction & aTrans ) [private, pure virtual]

Intended Usage: Attempt to service the transaction. This implies that the concrete protocol handler will allocate some transport resources to the transaction - which could fail if the protocol handler has hit an internal limit of resources or bandwidth. Implementations of this interface may leave with any of KErrHttpInvalidUri, KErrGeneral, KErrNoMemory

This must be implemented by a concrete protocol handler sub-class.

Parameters

CProtTransaction & aTrans The pending protocol transaction object which is to be serviced.

SessionServerCert()

IMPORT_C const CCertificate * SessionServerCert ( )

Get the Server Certificate for the current session.

SessionServerCert(TCertInfo &)

TInt SessionServerCert ( TCertInfo & aServerCert ) [pure virtual]

Intended Usage: Get the Server Certificate for the current session.

Parameters

TCertInfo & aServerCert A TCertInfo which will be filled with the certificate information

SubmitTransactionL(RHTTPTransaction)

void SubmitTransactionL ( RHTTPTransaction aTransaction ) [private]
Called after a client RHTTPTransaction::SubmitL() , this method enqueues the supplied client transaction. It checks to see if there already exists a CProtTransaction for this transaction. If there is and its state is ECancelled, then the associated request data is reset and the state changed to EPending. A CompleteSelf() is issued. In the case of an existing CProtTransaction that has not been cancelled, the submit event is ignored. If no CProtTransaction object existed, then one is created for the transaction and a CompleteSelf() is issued.
leave
KErrHttpCantResetRequestBody if the request body data cannot be reset. KErrNoMemory if a new CProtTransaction cannot be created or added to the transaction queue.
Pre-condition
None
Post-condition
If there is a new pending CProtTransaction object the protocol handler will have been self-completed (i.e. the RunL will be called).

Parameters

RHTTPTransaction aTransaction The submitted transaction.

TransactionCompleted(RHTTPTransaction, THTTPEvent)

IMPORT_C TInt TransactionCompleted ( RHTTPTransaction aTrans,
THTTPEvent aEventStatus
) [protected]

Parameters

RHTTPTransaction aTrans
THTTPEvent aEventStatus

TransactionCompletedL(RHTTPTransaction, THTTPEvent)

IMPORT_C void TransactionCompletedL ( RHTTPTransaction aTrans,
THTTPEvent aEventStatus
) [protected]
Callback method for concrete protocol handler sub-classes to inform the base protocol handler that a transaction has completed. The concrete protocol handler must call this method in order to supply a completion event that will be sent to the client. In addition, the method allows the base protocol handler to do some queue management.
leave
THTTPPanic::EInvalidFilterHandle if unable to send event.

Parameters

RHTTPTransaction aTrans (in) the completed transaction
THTTPEvent aEventStatus (in) an event to be sent back to the client along the filter queue

TransactionFailed(RHTTPTransaction)

IMPORT_C void TransactionFailed ( RHTTPTransaction aTrans ) [protected]

Callback method for concrete protocol handler sub-classes to inform the base protocol handler that a transaction has failed utterly. (i.e. the sub-class used aTrans.Fail().) The base protocol handler sets the transaction state to be cancelled.

Parameters

RHTTPTransaction aTrans (in) the completed transaction

TransactionServerCert(RHTTPTransaction)

IMPORT_C const CCertificate * TransactionServerCert ( RHTTPTransaction aTransaction )

Get the Server Certificate for the specified transaction.

Parameters

RHTTPTransaction aTransaction The transaction for which the certificate is requested

TransactionServerCert(TCertInfo &, RHTTPTransaction)

TInt TransactionServerCert ( TCertInfo & aServerCert,
RHTTPTransaction aTransaction
) [pure virtual]

Intended Usage: Get the Server Certificate for the specified transaction.

Parameters

TCertInfo & aServerCert A TCertInfo which will be filled with the certificate information
RHTTPTransaction aTransaction The transaction for which the certificate is requested

Member Data Documentation

CHeaderCodec * iCodec

CHeaderCodec * iCodec [protected]

The codec used for this protocol handler (to be specialised in subclasses)

RHTTPTransaction iCurrentTransaction

RHTTPTransaction iCurrentTransaction [private]

The transaction which is currently being serviced - used in RunError so we know which transaction caused RunL to leave.

TUid iDtor_ID_Key

TUid iDtor_ID_Key [private]

The destructor key UID indentification required by ECom

__DECLARE_LOG CSecurityPolicy * iSecurityPolicy

__DECLARE_LOG CSecurityPolicy * iSecurityPolicy [protected]

HTTP logger handle (debug only) An interface providing the security policy. This may be NULL if there is no security policy plugin

RHTTPSession iSession

RHTTPSession iSession [protected]

The session to which this protocol handler is dedicated

RPointerArray< CProtTransaction > iTransactions

RPointerArray < CProtTransaction > iTransactions [private]

A list of transactions. Each transaction has a list state, e.g. pending, active, etc.

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.