1 /*

     2 * Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Abstract base class for WV engine service APIs.

    15 *

    16 */

    17 

    18 #ifndef IMPS_CLIENT_H

    19 #define IMPS_CLIENT_H

    20 

    21 // INCLUDES

    22 #include <e32base.h>

    23 #include "impsconst.h"

    24 #include "impsservices.h"

    25 #include "impsdetailed.h"

    26 

    27 

    28 // DATA TYPES

    29 

    30 enum TImpsServiceStatus

    31     {

    32     EImps_ON_LINE,

    33     EImps_NOT_LOGGED,

    34     EImps_SHUTTING_DOWN

    35     };

    36 

    37 

    38 // FORWARD DECLARATIONS

    39 class CImpsHandler2;

    40 class MImpsStatusHandler2;

    41 class MImpsErrorHandler2;

    42 class RImpsClient2;  

    43 

    44 // CLASS DECLARATION

    45 

    46 /**

    47 * RImpsEng

    48 */

    49 

    50 class RImpsEng : public RSessionBase

    51     {

    52 

    53     public: // Constructors and destructor

    54 

    55         /**

    56         * Constructor

    57         */

    58         IMPORT_C RImpsEng();

    59 

    60 

    61     public: // New functions

    62         

    63         /**

    64         * Connect to the engine.

    65         * Starts engine process if necessary

    66         * @param aRate error failure rate, for testing only.

    67         * @return General error code

    68         */

    69         IMPORT_C TInt Connect( TInt aRate = 0 );

    70 

    71         /**

    72         * Close connection to engine

    73         */

    74         IMPORT_C void Close();

    75         

    76         /**

    77         * Csp identifier

    78         * @return TImpsCspIdentifier 

    79         */

    80         TImpsCspIdentifier* CspIdentifier();

    81         

    82         /**

    83         * Set csp identifier

    84         * @param aCspId id of the csp session

    85         */

    86         void SetCspIdentifier( TImpsCspIdentifier aCspId );

    87         

    88 

    89     protected:

    90 

    91         /**

    92         * Gives the client side code version.

    93         *

    94         * @return version

    95         */      

    96         TVersion Version() const;

    97         

    98 

    99     private:

   100 

   101         /**

   102         * Check if server is running

   103         * @return ETrue if running

   104         */

   105         TBool IsServerStarted();

   106 

   107         /**

   108         * Start server thread

   109         * @param aRate OOM failure reate for testing only

   110         * @param sRound number of round, determines the drive where to start. 

   111         * @return error code

   112         */

   113         TInt StartServer( TInt aRate, TInt aRound );

   114 

   115 

   116     private: // data

   117 

   118         TBool                   iSessionOk;

   119         TImpsCspIdentifier      iCspId;

   120    

   121     };

   122 

   123 

   124 /**

   125 *  RImpsClient2 API

   126 *

   127 *  Abstract base class for WV engine service APIs.

   128 *

   129 */ 

   130 

   131 class RImpsClient2 : public RSubSessionBase

   132     {

   133 

   134     public: // Constructors and destructor

   135 

   136         /**

   137         * C++ default constructor.

   138         */      

   139         IMPORT_C RImpsClient2();

   140 

   141     public: // New functions        

   142 

   143         // INITILIZATION AND CONNECT

   144 

   145         /**

   146         * Registers the service status change observer.

   147         * Ignored if API has already registered an observer

   148         * This can be called after the actual registeration of the

   149         * particular client has been made (RegisterL).

   150         * @param aObs status observer implementation

   151         */

   152         IMPORT_C void RegisterStatusObserverL( MImpsStatusHandler2* aObs );

   153 

   154         /**

   155         * Unregisters the service status change observer.

   156         * Ignored if API does not have registered observer.

   157         * This method is not necessary if unregister of the particular

   158         * client type has been executed (Unregister).

   159         */

   160         IMPORT_C void UnregisterStatusObserverL( );

   161 

   162         /**

   163         * Available services accessor

   164         * Notice that the method leaves with KImpsErrorServices until

   165         * service negotiation has been run.

   166         * @param aServices Service tree having 

   167         * all supported features and functions.

   168         */

   169         IMPORT_C void GetServicesL( TImpsServices& aServices );

   170 

   171         /**

   172         * Register an error event observer.

   173         * If this is not registered then a client does not

   174         * receive error events from WV engine.

   175         * An application may implement only one HandleErrorL method

   176         * and give pointer to it in each WV client instance.

   177         * @param aObs error event observer

   178         */

   179         IMPORT_C void RegisterErrorObserverL( MImpsErrorHandler2& aObs );

   180 

   181         /**

   182         * Unregisters an error observer.

   183         * Ignored if API does not have an error observer.

   184         * This method is not necessary if unregister of the particular

   185         * client has been executed (Unregister).

   186         */

   187         IMPORT_C void UnregisterErrorObserverL( );

   188 

   189         /**

   190         * Get the maximum TransactionContent size that WV engine

   191         * and WV server can handle, related to ParserSize.

   192         * Note that if service negotiation is not finished, this

   193         * method returns 0.

   194         * 

   195         * @return size or zero

   196         */

   197         IMPORT_C TInt MaxTransactionContentLengthL( );

   198 

   199         /**

   200         * Get WV CSP version currently used

   201         * Used literals are defined in impsconst.h

   202         * @return version, e.g. "CSP1.1"

   203         */

   204         IMPORT_C TPtrC WVVersionL(); 

   205 

   206         /**

   207         * Get CSP identifier used in login

   208         * Leaves with KErrNotFound if not logged in.

   209         * @return TImpsCspIdentifier

   210         */

   211         IMPORT_C TImpsCspIdentifier* CspIdentifierL(); 

   212 

   213         /**

   214         * Cancel the ongoing request

   215         * Removes the request from engine's message queue

   216         */

   217         IMPORT_C void CancelTransaction( TInt aOperationId ); 

   218         

   219         /**

   220         * Sets the expiry time for requests

   221         * New expiry time will be used for following requests that 

   222         * are sent by corresponding impsclient.

   223         * Negative values are ignored.

   224         */

   225         IMPORT_C void SetExpiryTime( TInt aSeconds ); 

   226 

   227         /**

   228         * Internal use only.

   229         * Error observer accessor

   230         * @return error observer

   231         */

   232         MImpsErrorHandler2* ErrorHandler();

   233 

   234         /**

   235         * Internal use only

   236         * @return TImpsCspIdentifier

   237         */

   238         TImpsCspIdentifier* CspIdentifier(); 

   239         

   240 

   241     protected: // New functions

   242 

   243         /**

   244         * Unregisters the listener object and disconnects from the server.

   245         */

   246         void DoUnregister();

   247 

   248         /**

   249         * Assign application id for this session.

   250         *

   251         * This is an optional method, but highly recommended to provide

   252         * enhanced message routing in the terminal.

   253         * Possible reason for the method to fail is that 

   254         * RegisterL has not executed.

   255         * 

   256         * @param aClientId client-id for message routing

   257         * @return error code 

   258         */

   259         TInt DoAssign( const TDesC& aClientId );

   260 

   261         /**

   262         * Increases the operation id and if it goes over the upper range limit

   263         * set it back to the lower limit

   264         */

   265         void IncreaseOpId( );

   266 

   267         /**

   268         * Sets the operation id's upper and lower limit.

   269         * Also set the operation id to the lowerlimit.

   270         */

   271         void SetOpIdRange( );

   272 

   273        /**

   274         * Registers the listener object for Access events and connects to

   275         * the Symbian OS Server.

   276         * @param aEngine WV Engine server instance

   277         * @param aHandler event observer

   278         * @param aReq request to server TImpsServRequest

   279         * @return operation id

   280         */

   281         TInt DoRegister2( RImpsEng& aEngine,

   282                           CImpsHandler2* aHandler,

   283                           TInt aReq );

   284 

   285     private:

   286 

   287        /**

   288         * Registers the listener object for events and connects to

   289         * the Symbian OS Server.

   290         * @param aEngine WV Engine server instance

   291         * @param aHandler event observer

   292         * @return error code

   293         */

   294         virtual TInt DoRegister( RImpsEng& aEngine,

   295                                  CImpsHandler2* aHandler ) = 0;

   296 

   297 

   298     protected: // data

   299 

   300         CImpsHandler2*            iHandler;

   301         CActive*                  iActiveCommand;

   302         TBool                     iRunning;

   303         HBufC*                    iClientId;

   304         TInt                      iOpId; 

   305         TInt                      iLimitUpperValue;

   306         TInt                      iLimitLowerValue;

   307         TBool                     iSessionOpen;

   308         TBool                     iHandleNew;

   309         TBool                     iAnyContent;

   310         RImpsEng*                  iEngine; 

   311      

   312     private: // friend classes

   313         friend class CImpsHandler2;

   314     

   315     };

   316 

   317 /**

   318 * MImpsStatusHandler2

   319 *

   320 * Abstract interface for handling general status events from the server.

   321 * User derives his class from this and implements the methods below.

   322 */

   323 

   324 class MImpsStatusHandler2

   325     {

   326 

   327     public: // New functions

   328 

   329     /**

   330     * Observer method for changes in service status.

   331     * Each service type API may register this observer 

   332     * by RegisterStatusObserverL.

   333     * @param aStatus new status.

   334     * @param aCspId CSP session identifier

   335     */

   336     virtual void HandleStatusChangeL( TImpsServiceStatus aStatus,

   337                                       TImpsCspIdentifier& aCspId )  = 0;

   338 

   339     };

   340 

   341 /**

   342 * MImpsErrorHandler2

   343 *

   344 * Abstract interface for handling error events from the server.

   345 * User derives his class from this and implements the method below.

   346 */

   347 

   348 class MImpsErrorHandler2

   349     {

   350 

   351     public: // New functions

   352 

   353     /**

   354     * Observer method for error messages.

   355     * This provides data for partial error responses too.

   356     * Each service API MUST register this observer by RegisterErrorObserverL

   357     * immediately after Register method.

   358     * @param aStatus error code. 

   359     * @param aOpId operation id to map responses to the requests.

   360     * @param aDescripton error description

   361     * @param aDetailedRes detailed error description

   362     * @param aCspId CSP session identifier

   363     */

   364     virtual void HandleErrorL( TInt aStatus,

   365                                TInt aOpId,

   366                                const TDesC* aDescription,

   367                                const CImpsDetailed* aDetailedRes,

   368                                TImpsCspIdentifier& aCspId ) = 0;

   369 

   370     };

   371 

   372 

   373 #endif      // IMPS_CLIENT_H  

   374             

   375 // End of File