CProtocolHandler Class Reference

#include <mw/http/framework/cprotocolhandler.h>

class CProtocolHandler : public CActive, public MHTTPFilter

Inherits from

CProtocolHandler
- CActive
  - CBase
- MHTTPFilter
  - MHTTPFilterBase

Protected Attributes
CHeaderCodec *	iCodec
__DECLARE_LOG CSecurityPolicy *	iSecurityPolicy
RHTTPSession	iSession

Public Member Functions
virtual	~CProtocolHandler()
IMPORT_C CHeaderCodec *	Codec()
virtual IMPORT_C void	MHFLoad(RHTTPSession, THTTPFilterHandle)
virtual IMPORT_C TInt	MHFRunError(TInt, RHTTPTransaction, const THTTPEvent &)
virtual IMPORT_C void	MHFRunL(RHTTPTransaction, const THTTPEvent &)
virtual IMPORT_C TInt	MHFSessionRunError(TInt, const THTTPSessionEvent &)
virtual IMPORT_C void	MHFSessionRunL(const THTTPSessionEvent &)
virtual IMPORT_C void	MHFUnload(RHTTPSession, THTTPFilterHandle)
CProtocolHandler *	NewL(const TDesC8 &, RHTTPSession)
virtual void	Reserved2()
IMPORT_C const CCertificate *	SessionServerCert()
pure virtual TInt	SessionServerCert(TCertInfo &)
IMPORT_C const CCertificate *	TransactionServerCert(RHTTPTransaction)
pure virtual TInt	TransactionServerCert(TCertInfo &, RHTTPTransaction)

Protected Member Functions
	CProtocolHandler(RHTTPSession)
IMPORT_C void	CompleteSelf()
IMPORT_C void	ConstructL(RHTTPSession)
virtual IMPORT_C void	DoCancel()
IMPORT_C CProtTransaction *	FindProtocolTransaction(RHTTPTransaction)
IMPORT_C TInt	FindTransaction(RHTTPTransaction, const CProtTransaction *&)
virtual void	GetInterfaceL(TUid, MProtHandlerInterface *&)
IMPORT_C TInt	NumActiveTransactions()
virtual IMPORT_C TInt	RunError(TInt)
virtual IMPORT_C void	RunL()
IMPORT_C TInt	TransactionCompleted(RHTTPTransaction, THTTPEvent)
IMPORT_C void	TransactionCompletedL(RHTTPTransaction, THTTPEvent)
IMPORT_C void	TransactionFailed(RHTTPTransaction)

Inherited Attributes
	CActive::iStatus

Inherited Enumerations
	CActive:TPriority
	MHTTPFilter:TPositions

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

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

Member Attribute Documentation

iCodec

CHeaderCodec *

iCodec

[protected]

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

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

iSession

RHTTPSession

iSession

[protected]

The session to which this protocol handler is dedicated

Constructor & Destructor Documentation

CProtocolHandler ( RHTTPSession )

IMPORT_C

CProtocolHandler

(

RHTTPSession

aSession

)

[protected]

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

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

~CProtocolHandler ( )

IMPORT_C

~CProtocolHandler

(

)

[virtual]

Intended Usage: Class destructor.

Member Function Documentation

Codec ( )

IMPORT_C CHeaderCodec *

Codec

(

)

const

Obtain the protocol handler's header codec.

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
aSession	The HTTP session on which this protocol handler will be installed.

DoCancel ( )

IMPORT_C void

DoCancel

(

)

[protected, virtual]

Reimplemented from CActive::DoCancel()

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

FindProtocolTransaction ( RHTTPTransaction )

IMPORT_C CProtTransaction *

FindProtocolTransaction

(

RHTTPTransaction

aTransaction

)

const [protected]

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
aTransaction	The transaction to search for.
aProtTransaction	Reference to a CProtTransaction which will be set to the CProtTransaction which wraps the RHTTPTransaction.

Return Value: 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.

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
aInterfaceId	the UID of the API function being called.
aInterfacePtr	reference to pointer to actual function implementation (in the derived class)

MHFLoad ( RHTTPSession, THTTPFilterHandle )

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

Reimplemented from MHTTPFilter::MHFLoad(RHTTPSession,THTTPFilterHandle)

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

Parameters
aSession	The session it's being added to.
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]

Reimplemented from MHTTPFilterBase::MHFRunError(TInt,RHTTPTransaction,const THTTPEvent &)

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.

See also: MHTTPFilterBase

Parameters
aError	The leave code that RunL left with.
aTransaction	The transaction that was being processed.
aEvent	The Event that was being processed.

Return Value: KErrNone if the error has been cancelled or the code of the continuing error otherwise.

MHFRunL ( RHTTPTransaction, const THTTPEvent & )

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

Reimplemented from MHTTPFilterBase::MHFRunL(RHTTPTransaction,const THTTPEvent &)

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.

See also: MHTTPFilterBase

Parameters
aTransaction	The transaction that the event has occurred on.
aEvent	aEvent The event that has occurred.

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

MHFSessionRunError ( TInt, const THTTPSessionEvent & )

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

Reimplemented from MHTTPFilterBase::MHFSessionRunError(TInt,const THTTPSessionEvent &)

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.

See also: MHTTPFilterBase

Parameters
aError	The leave code that RunL left with.
aEvent	The Event that was being processed.

Return Value: KErrNone if the error has been cancelled or the code of the continuing error otherwise.

MHFSessionRunL ( const THTTPSessionEvent & )

IMPORT_C void

MHFSessionRunL

(

const THTTPSessionEvent &

aEvent

)

[virtual]

Reimplemented from MHTTPFilterBase::MHFSessionRunL(const THTTPSessionEvent &)

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.

See also: MHTTPFilterBase

Parameters
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

MHFUnload ( RHTTPSession, THTTPFilterHandle )

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

Reimplemented from MHTTPFilter::MHFUnload(RHTTPSession,THTTPFilterHandle)

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

Parameters
aSession	The session it's being removed from
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. Implementation of CProtocolHandler class *****************************************************

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

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

NumActiveTransactions ( )

IMPORT_C TInt

NumActiveTransactions

(

)

const [protected]

Obtain the number of currently active transactions

Return Value: 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]

Reimplemented from CActive::RunError(TInt)

Intended Usage: Do any cleanup required should RunL leave

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

Return Value: A final error code - KErrNone if the error was handled by this method.

RunL ( )

IMPORT_C void

RunL

(

)

[protected, virtual]

Reimplemented from CActive::RunL()

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

SessionServerCert ( )

IMPORT_C const CCertificate *

SessionServerCert

(

)

Get the Server Certificate for the current session.

Return Value: The certificate information or NULL if it is not available

SessionServerCert ( TCertInfo & )

TInt

SessionServerCert

(

TCertInfo &

aServerCert

)

[pure virtual]

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

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

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

TransactionCompleted ( RHTTPTransaction, THTTPEvent )

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

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.

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

Leave Codes
THTTPPanic::EInvalidFilterHandle	if unable to send event.

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
aTrans	(in) the completed transaction

TransactionServerCert ( RHTTPTransaction )

IMPORT_C const CCertificate *

TransactionServerCert

(

RHTTPTransaction

aTransaction

)

Get the Server Certificate for the specified transaction.

Parameters
aTransaction	The transaction for which the certificate is requested

Return Value: The certificate information or NULL if it is not available

TransactionServerCert ( TCertInfo &, RHTTPTransaction )

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

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

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

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