Class CProtocolHandler

class CProtocolHandler : public CActive, public MHTTPFilter;

Description

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).

Derivation

• MHTTPFilterBase - A HTTP Filter

• MHTTPFilter - A HTTP filter

• CBase - Base class for all classes to be instantiated on the heap

• CActive - The core class of the active object abstraction

• CProtocolHandler - An abstract protocol handler

Members

Defined in CProtocolHandler:
CProtocolHandler(), CancelTransactionHook(), ClosedTransactionHook(), Codec(), CompleteSelf(), ConstructL(), CreateCodecL(), CreateProtTransactionL(), DoCancel(), FindTransaction(), GetInterfaceL(), MHFLoad(), MHFRunError(), MHFRunL(), MHFSessionRunError(), MHFSessionRunL(), MHFUnload(), NotifyNewRequestBodyPart(), NumActiveTransactions(), Reserved2(), RunError(), RunL(), ServiceL(), SessionServerCert(), SessionServerCert(), TransactionCompletedL(), TransactionFailed(), TransactionServerCert(), TransactionServerCert(), iCodec, iDummyLoggerNotUsed, iSecurityPolicy, iSession, ~CProtocolHandler()

Inherited from CActive:
Cancel(), Deque(), EPriorityHigh, EPriorityIdle, EPriorityLow, EPriorityStandard, EPriorityUserInput, Extension_(), IsActive(), IsAdded(), Priority(), SetActive(), SetPriority(), TPriority, iStatus

Inherited from CBase:
Delete(), operator new()

Inherited from MHTTPFilter:
ECache, EClient, EClientFilters, ECookies, EProtocolHandler, EStatusCodeHandler, ETidyUp, EUAProf, TPositions

virtual IMPORT_C ~CProtocolHandler();

Description

Intended Usage: Class destructor.

protected: IMPORT_C CProtocolHandler(RHTTPSession aSession);

Description

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.

protected: IMPORT_C void ConstructL(RHTTPSession aSession);

Description

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.

IMPORT_C CHeaderCodec *Codec() const;

Description

Obtain the protocol handler's header codec.

Return value

CHeaderCodec * The header codec owned by this protocol handler, or NULL if one has not yet been created.

See also:

• CHeaderCodec

IMPORT_C const CCertificate *SessionServerCert();

Description

Get the Server Certificate for the current session.

Return value

const CCertificate * The certificate information or NULL if it is not available

IMPORT_C const CCertificate *TransactionServerCert(RHTTPTransaction aTransaction);

Description

Get the Server Certificate for the specified transaction.

Parameters

RHTTPTransaction aTransaction The transaction for which the certificate is requested

Return value

const CCertificate * The certificate information or NULL if it is not available

virtual TInt SessionServerCert(TCertInfo &aServerCert)=0;

Description

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

Parameters

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

Return value

TInt An error code. KErrNone if aServerCert has been completed, otherwise one of the system wide error codes

virtual TInt TransactionServerCert(TCertInfo &aServerCert, RHTTPTransaction aTransaction)=0;

Description

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

Return value

TInt An error code. KErrNone if aServerCert has been completed, otherwise one of the system wide error codes

virtual IMPORT_C void MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent &aEvent);

Description

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.

Parameters

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

Leave codes

Standard Symbian OS error codes. e.g. KErrNoMemory.

See also:

• THTTPEvent
• MHTTPFilterBase

virtual IMPORT_C void MHFSessionRunL(const THTTPSessionEvent &aEvent);

Description

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.

Parameters

const THTTPSessionEvent &aEvent The session event that has occured.

Leave codes

KErrNoMemory if an attempt to allocate memory has failed KErrHttpCantResetRequestBody if the request body needed to be rewound by the client but it doesn't support this

See also:

• MHTTPFilterBase

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

Description

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.

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.

Return value

TInt KErrNone if the error has been cancelled or the code of the continuing error otherwise.

See also:

• MHTTPFilterBase

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

Description

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.

Parameters

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

Return value

TInt KErrNone if the error has been cancelled or the code of the continuing error otherwise.

See also:

• MHTTPFilterBase

virtual IMPORT_C void MHFUnload(RHTTPSession aSession, THTTPFilterHandle aHandle);

Description

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

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.

virtual IMPORT_C void MHFLoad(RHTTPSession aSession, THTTPFilterHandle aHandle);

Description

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

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

protected: IMPORT_C void TransactionCompletedL(RHTTPTransaction aTrans, THTTPEvent aEventStatus);

Description

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.

Parameters

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

Leave codes

THTTPPanic::EInvalidFilterHandle if unable to send event.

protected: IMPORT_C TInt NumActiveTransactions() const;

Description

Obtain the number of currently active transactions

Return value

TInt The number of currently active transactions

protected: IMPORT_C void TransactionFailed(RHTTPTransaction aTrans);

Description

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

protected: IMPORT_C void CompleteSelf();

Description

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

protected: IMPORT_C TInt FindTransaction(RHTTPTransaction aTransaction, const CProtTransaction *&aProtTransaction) const;

Description

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.

Return value

TInt If a CProtTransaction object is found, a positive value is returned that is the index to that object in the array. If no object is found, KErrNotFound is returned.

private: virtual void CreateCodecL()=0;

Description

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.

private: virtual CProtTransaction *CreateProtTransactionL(RHTTPTransaction aTransaction)=0;

Description

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.

Parameters

RHTTPTransaction aTransaction The RHTTPTransaction object associated with this CProtTransaction object.

Return value

CProtTransaction * A pointer to a created CProtTransaction-derived class.

Leave codes

KErrNoMemory if there was not enough memory to create the object. create the object.

See also:

• CRxData
• CTxData

private: virtual TBool ServiceL(CProtTransaction &aTrans)=0;

Description

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.

Return value

TBool A flag that indicates if the transaction can be serviced immediately.

private: virtual void ClosedTransactionHook(CProtTransaction *aTrans)=0;

Description

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.

private: virtual void CancelTransactionHook(CProtTransaction &aTransaction)=0;

Description

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

private: virtual void NotifyNewRequestBodyPart(CProtTransaction &aTransaction)=0;

Description

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

protected: virtual IMPORT_C void RunL();

Description

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

protected: virtual IMPORT_C TInt RunError(TInt aError);

Description

Intended Usage: Do any cleanup required should RunL leave

Parameters

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

Return value

TInt A final error code - KErrNone if the error was handled by this method.

protected: virtual IMPORT_C void DoCancel();

Description

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

protected: inline virtual void GetInterfaceL(TUid aInterfaceId, MProtHandlerInterface *&aInterfacePtr);

Description

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)

inline virtual void Reserved2();

Description

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

protected: RHTTPSession iSession;

Description

The session to which this protocol handler is dedicated

protected: CHeaderCodec * iCodec;

Description

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

protected: TUint8 iDummyLoggerNotUsed;

Description

HTTP logger handle (debug only)

protected: CSecurityPolicy * iSecurityPolicy;

Description

An interface providing the security policy. This may be NULL if there is no security policy plugin