diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/http/framework/cprotocolhandler.h --- /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 +#include +#include +#include + +// 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 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__