CProtocolHandler Class Reference
| class CProtocolHandler : public CActive |
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).
Constructor & Destructor Documentation
CProtocolHandler(RHTTPSession)
Constructs a protocol handler associated with the supplied HTTP client session.
Parameters
| RHTTPSession aSession | (in) The session on which the new protocol handler will be installed. |
~CProtocolHandler()
| IMPORT_C | ~CProtocolHandler | ( | ) | [virtual] |
Intended Usage: Class destructor.
Member Functions Documentation
CancelTransactionHook(CProtTransaction &)
| void | CancelTransactionHook | ( | CProtTransaction & | aTransaction | ) | [private, pure virtual] |
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.
ClosedTransactionHook(CProtTransaction *)
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.
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)
Second phase construction in which any necessary allocation is done Implementations of this interface may leave with KErrNoMemory
Parameters
| RHTTPSession aSession | The HTTP session on which this protocol handler will be installed. |
CreateCodecL()
| void | CreateCodecL | ( | ) | [private, pure virtual] |
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.
CreateProtTransactionL(RHTTPTransaction)
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.
CRxData CTxData Parameters
| RHTTPTransaction aTransaction | The RHTTPTransaction object associated with this CProtTransaction object. |
DoCancel()
| IMPORT_C void | DoCancel | ( | ) | [protected, virtual] |
Intended Usage: Cancel outstanding asynchronous requests that this object has made
FindProtocolTransaction(RHTTPTransaction)
FindTransaction(RHTTPTransaction, const CProtTransaction *&)
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
| RHTTPTransaction aTransaction | The transaction to search for. |
| const CProtTransaction *& aProtTransaction | Reference to a CProtTransaction which will be set to the CProtTransaction which wraps the RHTTPTransaction. |
FindTransaction(RHTTPTransaction)
Searches the array of CProtTransaction objects to if the aTransaction object is wrapped by one of them.
GetInterfaceL(TUid, MProtHandlerInterface *&)
Intended Usage: This is a mechanism for allowing future change to CProtocolHandler API without breaking BC.
Parameters
| TUid aInterfaceId | the UID of the API function being called. |
| MProtHandlerInterface *& aInterfacePtr | reference to pointer to actual function implementation (in the derived class) |
HandleCancelTransaction(RHTTPTransaction)
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.
- Pre-condition
- A CProtTransaction object exists for this transaction.
- Post-condition
- The state of the CProtTransaction object is set to ECancelled and it has been reset.
HandleClosedTransaction(RHTTPTransaction)
MHFLoad(RHTTPSession, THTTPFilterHandle)
Intended Usage: Called when the filter is being added to the session's filter queue. MHTTFilter
Parameters
| RHTTPSession aSession | The session it's being added to. |
| THTTPFilterHandle 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 &)
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. MHTTPFilterBase
Parameters
| TInt aError | The leave code that RunL left with. |
| RHTTPTransaction aTransaction | The transaction that was being processed. |
| const THTTPEvent & aEvent | The Event that was being processed. |
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.
THTTPEvent - leave
- Standard Symbian OS error codes. e.g. KErrNoMemory.
MHTTPFilterBase Parameters
| RHTTPTransaction aTransaction | The transaction that the event has occurred on. |
| const THTTPEvent & aEvent | aEvent The event that has occurred. |
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. MHTTPFilterBase
Parameters
| TInt aError | The leave code that RunL left with. |
| const THTTPSessionEvent & aEvent | The Event that was being processed. |
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.
- 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
MHTTPFilterBase
MHFUnload(RHTTPSession, THTTPFilterHandle)
Intended Usage: Called when the filter is being removed from a session's filter queue. MHTTFilter
Parameters
| RHTTPSession aSession | The session it's being removed from |
| THTTPFilterHandle 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)
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.
- leave
- KErrNoMemory if there was not enough memory to create the object.
Implementation of
CProtocolHandler class *****************************************************
Parameters
| const TDesC8 & aProtocol | (in) The name of the protocol required. |
| RHTTPSession aSession | (in) The HTTP session on which this protocol handler will be installed. |
NotifyNewRequestBodyPart(CProtTransaction &)
| void | NotifyNewRequestBodyPart | ( | CProtTransaction & | aTransaction | ) | [private, pure virtual] |
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.
NumActiveTransactions()
| IMPORT_C TInt | NumActiveTransactions | ( | ) | const [protected] |
Obtain 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] |
Intended Usage: Do any cleanup required should RunL leave
Parameters
| TInt aError | (in) The error code that RunL left with |
RunL()
| IMPORT_C void | RunL | ( | ) | [protected, virtual] |
Intended Usage: Do some processing when a previous asynchronous request made by this object has completed.
ServiceL(CProtTransaction &)
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.
Parameters
| CProtTransaction & aTrans | The pending protocol transaction object which is to be serviced. |
SessionServerCert()
| IMPORT_C const CCertificate * | SessionServerCert | ( | ) | |
Get the Server Certificate for the current session.
SessionServerCert(TCertInfo &)
Intended Usage: Get the Server Certificate for the current session.
Parameters
| TCertInfo & aServerCert | A TCertInfo which will be filled with the certificate information |
SubmitTransactionL(RHTTPTransaction)
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.
- Pre-condition
- None
- Post-condition
- If there is a new pending CProtTransaction object the protocol handler will have been self-completed (i.e. the RunL will be called).
TransactionCompleted(RHTTPTransaction, THTTPEvent)
TransactionCompletedL(RHTTPTransaction, THTTPEvent)
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.
- leave
- THTTPPanic::EInvalidFilterHandle if unable to send event.
Parameters
| RHTTPTransaction aTrans | (in) the completed transaction |
| THTTPEvent aEventStatus | (in) an event to be sent back to the client along the filter queue |
TransactionFailed(RHTTPTransaction)
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.
TransactionServerCert(RHTTPTransaction)
| IMPORT_C const CCertificate * | TransactionServerCert | ( | RHTTPTransaction | aTransaction | ) | |
Get the Server Certificate for the specified transaction.
Parameters
| RHTTPTransaction aTransaction | The transaction for which the certificate is requested |
TransactionServerCert(TCertInfo &, RHTTPTransaction)
Intended Usage: Get the Server Certificate for the specified transaction.
Parameters
| TCertInfo & aServerCert | A TCertInfo which will be filled with the certificate information |
| RHTTPTransaction aTransaction | The transaction for which the certificate is requested |
Member Data Documentation
CHeaderCodec * iCodec
The codec used for this protocol handler (to be specialised in subclasses)
RHTTPTransaction
iCurrentTransaction
The transaction which is currently being serviced - used in RunError so we know which transaction caused RunL to leave.
TUid
iDtor_ID_Key
|
TUid
| iDtor_ID_Key | [private] |
The destructor key UID indentification required by ECom
__DECLARE_LOG CSecurityPolicy * iSecurityPolicy
HTTP logger handle (debug only) An interface providing the security policy. This may be NULL if there is no security policy plugin
RHTTPSession
iSession
The session to which this protocol handler is dedicated
RPointerArray< CProtTransaction > iTransactions
A list of transactions. Each transaction has a list state, e.g. pending, active, etc.
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.