Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: cprotocolhandler.h
Link against: http.lib

This item is not part of the S60 3rd Edition SDK for Symbian OS, Feature Pack 2.

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

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


Construction and destruction


~CProtocolHandler()

virtual IMPORT_C ~CProtocolHandler();

Description

Intended Usage: Class destructor.


CProtocolHandler()

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.


ConstructL()

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.

[Top]


Member functions


Codec()

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:


SessionServerCert()

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


TransactionServerCert()

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


SessionServerCert()

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


TransactionServerCert()

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


MHFRunL()

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:


MHFSessionRunL()

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:


MHFRunError()

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:


MHFSessionRunError()

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:


MHFUnload()

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.


MHFLoad()

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


TransactionCompletedL()

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.


NumActiveTransactions()

protected: IMPORT_C TInt NumActiveTransactions() const;

Description

Obtain the number of currently active transactions

Return value

TInt

The number of currently active transactions


TransactionFailed()

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


CompleteSelf()

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.


FindTransaction()

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.


CreateCodecL()

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.


CreateProtTransactionL()

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:


ServiceL()

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.


ClosedTransactionHook()

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.


CancelTransactionHook()

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


NotifyNewRequestBodyPart()

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


RunL()

protected: virtual IMPORT_C void RunL();

Description

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


RunError()

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.


DoCancel()

protected: virtual IMPORT_C void DoCancel();

Description

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


GetInterfaceL()

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)


Reserved2()

inline virtual void Reserved2();

Description

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

[Top]


Member data


iSession

protected: RHTTPSession iSession;

Description

The session to which this protocol handler is dedicated


iCodec

protected: CHeaderCodec * iCodec;

Description

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


iDummyLoggerNotUsed

protected: TUint8 iDummyLoggerNotUsed;

Description

HTTP logger handle (debug only)


iSecurityPolicy

protected: CSecurityPolicy * iSecurityPolicy;

Description

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