// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

 // All rights reserved.

 // This component and the accompanying materials are made available

 // under the terms of "Eclipse Public License v1.0"

 // which accompanies this distribution, and is available

 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

 //

 // Initial Contributors:

 // Nokia Corporation - initial contribution.

 //

 // Contributors:

 //

 // Description:

 // please do not delete

 // 

 //

 /**

  @file CProtocolHandler.h

  @warning : This file contains Rose Model ID comments 

 */

 #ifndef __CPROTOCOLHANDLER_H__

 #define __CPROTOCOLHANDLER_H__

 // System includes

 #include <e32base.h>

 #include <http/framework/httplogger.h>

 #include <http/mhttpfilter.h>

 #include <http/rhttpsession.h>

 // Forward declarations

 class CHeaderCodec;

 class CProtTransaction;

 class CSecurityPolicy;

 class MProtHandlerInterface;

 /**

 The ECom protocol handler plugin interface UID.

 @publishedAll

 @released

 */

 const TUid KUidProtocolHandlerPluginInterface = {0x1000A449};

 // 

 /**

 Defined active object priorities for the Protocol Handler

 @publishedAll

 @released

 */

 const TInt KProtocolHandlerActivePriority = CActive::EPriorityStandard;

 /**

 Defined active object priorities for the Transaction

 @publishedAll

 @released

 */

 const TInt KTransactionActivePriority = KProtocolHandlerActivePriority+1;

 //##ModelId=3C4C186A02A3

 class CProtocolHandler : public CActive, public MHTTPFilter

 /**

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

 @publishedAll

 @released

 */

 	{

 public:	// Methods

 /**	

 	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.

 	@param			aProtocol	(in) The name of the protocol required.

 	@param			aSession	(in) The HTTP session on which this protocol handler

 									 will be installed.

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

 */

 	//##ModelId=3C4C186B007E

 	static CProtocolHandler* NewL(const TDesC8& aProtocol, RHTTPSession aSession);

 /**	

 	Intended Usage:	Class destructor.

 */

 	//##ModelId=3C4C186B0075

 	IMPORT_C virtual ~CProtocolHandler();

 /**	

 	Obtain the protocol handler's header codec.

 	@return			The header codec owned by this protocol handler, or NULL if one

 					has not yet been created.

 	@see CHeaderCodec

 */

 	//##ModelId=3C4C186B0074

 	IMPORT_C CHeaderCodec* Codec() const;

 /** 

 	Get the Server Certificate for the current session.

 	@return	The certificate information or NULL if it is not available

 */

 	IMPORT_C const CCertificate* SessionServerCert();

 /** 

 	Get the Server Certificate for the specified transaction.

 	@param	aTransaction The transaction for which the certificate is requested

 	@return	The certificate information or NULL if it is not available

 */

 	IMPORT_C const CCertificate* TransactionServerCert( RHTTPTransaction aTransaction);

 public:	// Methods to be implemented in specific protocol handlers

 /** 

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

 	@param	aServerCert A TCertInfo which will be filled with the certificate information

 	@return	An error code.  KErrNone if aServerCert has been completed, otherwise one of 

 	the system wide error codes

 */

 	virtual TInt SessionServerCert(TCertInfo& aServerCert) = 0;

 /** 

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

 	@param	aServerCert A TCertInfo which will be filled with the certificate information

 	@param	aTransaction The transaction for which the certificate is requested

 	@return	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;

 public:	// Methods from MHTTPFilterBase

 /**

 	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 THTTPEvent

 	@param aTransaction The transaction that the event has occurred on.

 	@param aEvent aEvent The event that has occurred.

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

 	@see MHTTPFilterBase	

 */

 	//##ModelId=3C4C186B0061

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

 /**

 	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.

 	@param aEvent The session event that has occured.

 	@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

 	@see MHTTPFilterBase

 */

 	//##ModelId=3C4C186B0057

 	IMPORT_C virtual void MHFSessionRunL(const THTTPSessionEvent& aEvent);

 /**

 	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.

 	@param aError The leave code that RunL left with.

 	@param aTransaction The transaction that was being processed.

 	@param aEvent The Event that was being processed.

 	@return KErrNone if the error has been cancelled or the code

 			of the continuing error otherwise.

 	@see MHTTPFilterBase

 */

 	//##ModelId=3C4C186B0043

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

 /**

 	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.

 	@param aError The leave code that RunL left with.

 	@param aEvent The Event that was being processed.

 	@return KErrNone if the error has been cancelled or the code

 			of the continuing error otherwise.	

 	@see MHTTPFilterBase

 */

 	//##ModelId=3C4C186B0038	

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

 public:	// Methods from MHTTPFilter

 /** 

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

 	@param aSession The session it's being removed from

 	@param aHandle The filter handle. Complex filters may need to 

 				   refer to this to keep track of which particular registration is

 				   being unloaded.

 	@see MHTTFilter

 */

 	//##ModelId=3C4C186B0025

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

 /** 

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

 	@param aSession The session it's being added to.

 	@param aHandle The filter handle. Complex filters may need to keep

 				   track of this, for instance if generating events in response to

 				   external stimuli

 	@see MHTTFilter

  */

 	//##ModelId=3C4C186B001A

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

 protected: // callbacks/methods for sub-classes

 /**	

 	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.

 	@param			aTrans			(in) the completed transaction

 	@param			aEventStatus	(in) an event to be sent back to the client along

 										 the filter queue

 	@leave			THTTPPanic::EInvalidFilterHandle if unable to send event.

  */

 	//##ModelId=3C4C186B0010

 	IMPORT_C void TransactionCompletedL(RHTTPTransaction aTrans, THTTPEvent aEventStatus);

     IMPORT_C TInt TransactionCompleted(RHTTPTransaction aTrans, THTTPEvent aEventStatus);

 /**	

 	Obtain the number of currently active transactions

 	@return			The number of currently active transactions

  */

 	//##ModelId=3C4C186B0006

 	IMPORT_C TInt NumActiveTransactions() const;

 /**	

 	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.

 	@param			aTrans			(in) the completed transaction

  */

 	//##ModelId=3C4C186A03E5

 	IMPORT_C void TransactionFailed(RHTTPTransaction aTrans);

 /**	

 	Completes this active object - allows the protocol handler to

 	reevaluate the queue of pending transactions and service new ones

 	if possible.

  */

 	//##ModelId=3C4C186A03E4

 	IMPORT_C void CompleteSelf();

 /**	

 	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

 	@param aTransaction	The transaction to search for.

 	@param aProtTransaction	Reference to a CProtTransaction which will be set to the

 		   CProtTransaction which wraps the RHTTPTransaction.

 	@return 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.

  */

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

 	IMPORT_C CProtTransaction* FindProtocolTransaction(RHTTPTransaction aTransaction) const;

 private: // methods to be implemented in specific protocol handlers

 /**	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.

  */

 	//##ModelId=3C4C186A03DC

 	virtual void CreateCodecL() = 0;

 /**	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.

 	@param			aTransaction	The RHTTPTransaction object associated with

 									this CProtTransaction object.

 	@return			A pointer to a created CProtTransaction-derived class.

 	@see			CRxData

 	@see			CTxData

  */

 	//##ModelId=3C4C186A03DA

 	virtual CProtTransaction* CreateProtTransactionL(RHTTPTransaction aTransaction) = 0;

 /**	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.

 	@param			aTrans	The pending protocol transaction object which is to be

 							serviced.

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

  */

 	//##ModelId=3C4C186A03D0

 	virtual TBool ServiceL(CProtTransaction& aTrans) = 0;

 /**	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.

 	@param			aTrans		(in) A pointer to the transaction about to be closed.

  */

 	//##ModelId=3C4C186A03C6

 	virtual void ClosedTransactionHook(CProtTransaction* aTrans) = 0;

 /**	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.

 	@param			aTrans		(in) A reference to the transaction being cancelled.

  */

 	//##ModelId=3C4C186A03B3

 	virtual void CancelTransactionHook(CProtTransaction& aTransaction) = 0;

 /**	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.

 	@param			aTrans		(in) A reference to the transaction whose request body

 									 has new data available.

  */

 	//##ModelId=3C4C186A03A8

 	virtual void NotifyNewRequestBodyPart(CProtTransaction& aTransaction) = 0;

 protected: // Methods inherited from CActive

 /**	Intended Usage:	Do some processing when a previous asynchronous request made by

 					this object has completed.

  */

 	//##ModelId=3C4C186A0377

 	IMPORT_C virtual void RunL();

 /**	Intended Usage:	Do any cleanup required should RunL leave

 	@param			aError		(in) The error code that RunL left with

 	@return			A final error code - KErrNone if the error was handled by this

 					method.

  */

 	//##ModelId=3C4C186A036E

 	IMPORT_C virtual TInt RunError(TInt aError);

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

  */

 	//##ModelId=3C4C186A036D

 	IMPORT_C virtual void DoCancel();

 protected:	// Methods

 /**	

 	Constructs a protocol handler associated with the supplied HTTP

 	client session.

 	@param			aSession	(in) The session on which the new protocol handler will

 									 be installed.

  */

 	IMPORT_C CProtocolHandler(RHTTPSession aSession);

 /**	

 	Second phase construction in which any necessary allocation is done

 	Implementations of this interface may leave with KErrNoMemory

 	@param aSession The HTTP session on which this protocol handler

 		   will be installed.

  */

 	//##ModelId=3C4C186A036C

 	IMPORT_C void ConstructL(RHTTPSession aSession);

 protected: // Attributes

 	/** The session to which this protocol handler is dedicated

 	*/

 	//##ModelId=3C4C186A033C

 	RHTTPSession iSession;

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

 	*/

 	//##ModelId=3C4C186A032F

 	CHeaderCodec* iCodec;

 	/** HTTP logger handle (debug only)

 	*/

 	__DECLARE_LOG

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

 	//##ModelId=3C4C186A031D

 	CSecurityPolicy* iSecurityPolicy;	

 private: // Methods

 /**	

 	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.

 	@param			aTransaction	The submitted transaction.

 	@pre 			None

 	@post			If there is a new pending CProtTransaction object the protocol

 					handler will have been self-completed (i.e. the RunL will be 

 					called).

  */

 	//##ModelId=3C4C186A0362

 	void SubmitTransactionL(RHTTPTransaction aTransaction);

 /**	

 	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.

 	@param			RHTTPTransaction aTrans

 	@pre 			A CProtTransaction object exists for this transaction.

 	@post			The state of the CProtTransaction object is set to ECancelled 

 					and it has been reset.

  */

 	//##ModelId=3C4C186A0359

 	void HandleCancelTransaction(RHTTPTransaction aTrans);

 /**	

 	Removes the CProtTransaction object for the transaction

 	from the queue of CProtTransaction objects.

 	@param			RHTTPTransaction aTrans

 	@pre 			A CProtTransaction object exists for this transaction.

 	@post			The CProtTransaction object has been removed from the queue.

  */

 	//##ModelId=3C4C186A034F

 	void HandleClosedTransaction(RHTTPTransaction aTrans);

 /**	

 	Searches the array of CProtTransaction objects to if the

 	aTransaction object is wrapped by one of them.

 	@param			aTransaction	The transaction to search for.

 	@return			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.

  */

 	//##ModelId=3C4C186A0346

 	TInt FindTransaction(RHTTPTransaction aTransaction) const;

 protected:

 /**	

 	Intended Usage: This is a mechanism for allowing future change to CProtocolHandler API 

 	without breaking BC.

 	@param aInterfaceId		the UID of the API function being called.

 	@param aInterfacePtr	reference to pointer to actual function implementation (in the derived class)

  */

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

 public:

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

  */

 	//##ModelId=3C4C186A0344

 	inline virtual void Reserved2();

 private: // Attributes

 	/** A list of transactions. Each transaction has a list state, e.g. pending,

 		active, etc.

 	*/

 	//##ModelId=3C4C186A0313

 	RPointerArray<CProtTransaction>		iTransactions;

 	/**	The transaction which is currently being serviced - used in RunError so 

 		we know which transaction caused RunL to leave.

 	*/

 	//##ModelId=3C4C186A02FF

 	RHTTPTransaction					iCurrentTransaction;

 	/** The destructor key UID indentification required by ECom

 	*/

 	//##ModelId=3C4C186A02F5

 	TUid iDtor_ID_Key;

 	};

 /**

 Interface for adding to ProtocolHandler API

 @publishedAll

 @released

 */

 const TInt KProtHandlerSessionServerCertUid		= 0x1028180D;

 const TInt KProtHandlerTransactionServerCertUid	= 0x1028180E;

 class MProtHandlerInterface

 	{

 public:

 	/** 

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

 	@return	The certificate information or NULL if it is not available

 	*/

 	virtual const CCertificate*  SessionServerCert() = 0;

 	/** 

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

 	@param	aTransaction The transaction for which the certificate is requested

 	@return	The certificate information or NULL if it is not available

 	*/

 	virtual const CCertificate* TransactionServerCert( RHTTPTransaction aTransaction) = 0;

 	};

 inline void CProtocolHandler::GetInterfaceL(TUid, MProtHandlerInterface*&)

 	{}

 inline void CProtocolHandler::Reserved2()

 	{}

 #endif // __CPROTOCOLHANDLER_H__