--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/http/framework/cprotocolhandler.h Tue Mar 16 16:12:26 2010 +0000
@@ -0,0 +1,555 @@
+// 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/licencesv10.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);
+
+/**
+ 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;
+
+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__