// 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__