Nokia N97 SDK
Example Applications Guide

WebClientEngine.h

00001 /*
00002 * ==============================================================================
00003 *  Name        : WebClientEngine.h
00004 *  Part of     : WebClient
00005 *  Interface   : 
00006 *  Description : 
00007 *  Version     : 
00008 *
00009 *  Copyright (c) 2005-2007 Nokia Corporation.
00010 *  This material, including documentation and any related 
00011 *  computer programs, is protected by copyright controlled by 
00012 *  Nokia Corporation.
00013 * ==============================================================================
00014 */
00015 
00016 #ifndef WEBCLIENTENGINE_H
00017 #define WEBCLIENTENGINE_H
00018 
00019 // INCLUDES
00020 #include <coecntrl.h>
00021 #include <http.h>
00022 #include <http\mhttpauthenticationcallback.h>
00023 #include <es_sock.h>
00024 
00025 // CONSTANTS
00026 const TInt KMaxHeaderNameLength     = 32;
00027 const TInt KMaxHeaderValueLength    = 128;
00028 const TInt KMaxAuthTypeLength       = 128;
00029 const TInt KMaxDateTimeStringLength = 40;
00030 const TInt KMaxStatusTextLength     = 32;
00031 
00032 // Used user agent for requests
00033 _LIT8( KUserAgent, "WebClient 1.0" );
00034 
00035 // This client accepts all content types.
00036 // (change to e.g. "text/plain" for plain text only)
00037 _LIT8( KAccept, "*/*" );
00038 
00039 // Format for output of data/time values
00040 _LIT( KDateFormat,"%D%M%Y%/0%1%/1%2%/2%3%/3 %:0%H%:1%T%:2%S.%C%:3" );
00041 
00042 // Some texts for header output
00043 _LIT( KColon, ": " );
00044 _LIT( Krealm, "Realm: " );
00045 
00046 
00047 // FORWARD DECLARATIONS
00048 class CWebClientAppUi;
00049 
00050 // CLASS DECLARATION
00051 
00052 /**
00053 * MWebClientObserver
00054 * CWebClientEngine passes events and responses body data with this interface. 
00055 * An instance of this class must be provided for construction of CWebClientEngine.
00056 */
00057 class MWebClientObserver 
00058     {
00059     public:
00060         /**
00061         * ClientEvent()
00062         * Called when event occurs in CWebClientEngine.
00063         * @param aEventDescription: A event in textual format, e.g.
00064         *                           "Transaction Successful"
00065         */
00066         virtual void ClientEvent( const TDesC& aEventDescription ) = 0;
00067 
00068     public:
00069         /**
00070         * ClientHeaderReceived()
00071         * Called when HTTP header is received.
00072         * @param aHeaderData: Header field name and value
00073         */
00074         virtual void ClientHeaderReceived( const TDesC& aHeaderData ) = 0;
00075 
00076         /**
00077         * ClientBodyReceived()
00078         * Called when a part of the HTTP body is received.
00079         * @param aBodyData:  Part of the body data received. (e.g. part of
00080         *                    the received HTML page)
00081         */
00082         virtual void ClientBodyReceived( const TDesC8& aBodyData ) = 0;
00083     };
00084 
00085 /**
00086 * CWebClientEngine
00087 * Provides simple interface to HTTP Client API.
00088 */
00089 class CWebClientEngine : public CBase, 
00090                          public MHTTPTransactionCallback,
00091                          public MHTTPAuthenticationCallback
00092     {
00093     public:
00094         /**
00095         * NewL()
00096         * Create a CWebClientEngine object.
00097         * @param  iObserver: 
00098         * @return A pointer to the created instance of CWebClientEngine
00099         */
00100         static CWebClientEngine* NewL( MWebClientObserver& aObserver );
00101 
00102         /**
00103         * NewLC()
00104         * Create a CWebClientEngine object.
00105         * @param  iObserver:
00106         * @return A pointer to the created instance of CWebClientEngine
00107         */
00108         static CWebClientEngine* NewLC( MWebClientObserver& aObserver );
00109 
00110         /**
00111         * ~CWebClientEngine()
00112         * Destroy the object
00113         */
00114         ~CWebClientEngine();
00115 
00116         /**
00117         * IssueHTTPGetL()
00118         * Starts a new HTTP GET transaction.
00119         * @param aUri: URI to get. (e.g. http://host.org")
00120         */
00121         void IssueHTTPGetL( const TDesC8& aUri );
00122 
00123         /**
00124         * CancelTransactionL()
00125         * Closes currently running transaction and frees resources related to it.
00126         */
00127         void CancelTransactionL();
00128 
00129         /**
00130         * IsRunning()
00131         * Checks if the transaction is running.
00132         * @return ETrue, if transaction is currently running.
00133         */
00134         inline TBool IsRunning() { return iRunning; };
00135 
00136         /**
00137         * SetCallBack()
00138         * Sets the callback address.
00139         * @param aCallBack: A pointer to calling instance.
00140         */
00141         void SetCallBack( CWebClientAppUi* aCallBack );
00142 
00143     private:
00144         /**
00145         * ConstructL()
00146         * Perform the second phase construction of a CWebClientEngine object.
00147         */
00148         void ConstructL();
00149 
00150         /**
00151         * CWebClientEngine()
00152         * Perform the first phase of two phase construction.
00153         * @param iObserver: 
00154         */
00155         CWebClientEngine( MWebClientObserver& iObserver );
00156 
00157         /**
00158         * SetHeaderL()
00159         * Sets header value of an HTTP request.
00160         * @param aHeaders:  Headers of the HTTP request
00161         * @param aHdrField: Enumerated HTTP header field, e.g. HTTP::EUserAgent
00162         * @param aHdrValue: New value for header field
00163         */
00164         void SetHeaderL( RHTTPHeaders aHeaders, TInt aHdrField, 
00165                          const TDesC8& aHdrValue );
00166 
00167         /**
00168         * DumpRespHeadersL()
00169         * Called when HTTP header is received.
00170         * Displays HTTP header field names and values
00171         * @param aTransaction: The transaction that is processed.
00172         */
00173         void DumpRespHeadersL( RHTTPTransaction& aTransantion );
00174 
00175         /**
00176         * HandleRunErrorL()
00177         * Called from MHFRunError() when *leave* occurs in handling of transaction event. 
00178         * @param aError:       The leave code that occured.
00179         */
00180         void HandleRunErrorL( TInt aError );
00181 
00182         /**
00183         * SetupConnectionL()
00184         */
00185         void SetupConnectionL();
00186 
00187     /**
00188     * From MHTTPSessionEventCallback
00189     */
00190     private:
00191         /**
00192         * MHFRunL()
00193         * Called by framework to notify about transaction events.
00194         * @param aTransaction: Transaction, where the event occured.
00195         * @param aEvent:       Occured event.
00196         */
00197         void MHFRunL( RHTTPTransaction aTransaction, const THTTPEvent& aEvent );
00198 
00199         /**
00200         * MHFRunError()
00201         * Called by framework when *leave* occurs in handling of transaction event. 
00202         * @param aError:       The leave code that occured.
00203         * @param aTransaction: The transaction that was being processed when leave occured.
00204         * @param aEvent:       The event that was being processed when leave occured.
00205         * @return KErrNone,    if the error was handled. Otherwise the value of aError, or
00206         *                      some other error value. Returning error value causes causes 
00207         *                      HTTP-CORE 6 panic.
00208         */
00209         TInt MHFRunError( TInt aError, 
00210                           RHTTPTransaction aTransaction, 
00211                           const THTTPEvent& aEvent );
00212 
00213     /**
00214     * From MHTTPAuthenticationCallback (needed for HTTP authentication)
00215     */
00216     private:
00217         /**
00218         * GetCredentialsL()
00219         * Called by framework when username and password for requested URI is 
00220         * needed.
00221         * @param aURI: The URI being requested (e.g. "http://host.org")
00222         * @param aRealm: The realm being requested (e.g. "user@host.org")
00223         * @param aAuthenticationType: Authentication type. (e.g. "Basic")
00224         * @param aUsername: Given user name.
00225         * @param aPassword: Given password.
00226         * @return A pointer to the created document
00227         */
00228         TBool GetCredentialsL(  const TUriC8& aUri, 
00229                                 RString aRealm, 
00230                                 RStringF aAuthenticationType, 
00231                                 RString& aUsername, 
00232                                 RString& aPassword );
00233 
00234     private: // Data
00235         RSocketServ             iSocketServ;
00236         RConnection             iConnection;
00237         RHTTPSession            iSession;
00238         RHTTPTransaction        iTransaction;
00239         MWebClientObserver&     iObserver;      // Used for passing body data and
00240                                                 // events to UI.
00241         TBool                   iRunning;       // ETrue, if transaction running
00242         TBool                   iConnectionSetupDone; // ETrue, if connection setup is done
00243         CWebClientAppUi*        iApplicationUi; // Pointer to AppUi instance
00244     };
00245 
00246 #endif // WEBCLIENTENGINE_H

© Nokia 2009

Back to top