diff -r 000000000000 -r 094583676ce7 inc/ImpsClient.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/ImpsClient.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,375 @@ +/* +* Copyright (c) 2002-2005 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Abstract base class for WV engine service APIs. +* +*/ + +#ifndef IMPS_CLIENT_H +#define IMPS_CLIENT_H + +// INCLUDES +#include +#include "impsconst.h" +#include "impsservices.h" +#include "impsdetailed.h" + + +// DATA TYPES + +enum TImpsServiceStatus + { + EImps_ON_LINE, + EImps_NOT_LOGGED, + EImps_SHUTTING_DOWN + }; + + +// FORWARD DECLARATIONS +class CImpsHandler2; +class MImpsStatusHandler2; +class MImpsErrorHandler2; +class RImpsClient2; + +// CLASS DECLARATION + +/** +* RImpsEng +*/ + +class RImpsEng : public RSessionBase + { + + public: // Constructors and destructor + + /** + * Constructor + */ + IMPORT_C RImpsEng(); + + + public: // New functions + + /** + * Connect to the engine. + * Starts engine process if necessary + * @param aRate error failure rate, for testing only. + * @return General error code + */ + IMPORT_C TInt Connect( TInt aRate = 0 ); + + /** + * Close connection to engine + */ + IMPORT_C void Close(); + + /** + * Csp identifier + * @return TImpsCspIdentifier + */ + TImpsCspIdentifier* CspIdentifier(); + + /** + * Set csp identifier + * @param aCspId id of the csp session + */ + void SetCspIdentifier( TImpsCspIdentifier aCspId ); + + + protected: + + /** + * Gives the client side code version. + * + * @return version + */ + TVersion Version() const; + + + private: + + /** + * Check if server is running + * @return ETrue if running + */ + TBool IsServerStarted(); + + /** + * Start server thread + * @param aRate OOM failure reate for testing only + * @param sRound number of round, determines the drive where to start. + * @return error code + */ + TInt StartServer( TInt aRate, TInt aRound ); + + + private: // data + + TBool iSessionOk; + TImpsCspIdentifier iCspId; + + }; + + +/** +* RImpsClient2 API +* +* Abstract base class for WV engine service APIs. +* +*/ + +class RImpsClient2 : public RSubSessionBase + { + + public: // Constructors and destructor + + /** + * C++ default constructor. + */ + IMPORT_C RImpsClient2(); + + public: // New functions + + // INITILIZATION AND CONNECT + + /** + * Registers the service status change observer. + * Ignored if API has already registered an observer + * This can be called after the actual registeration of the + * particular client has been made (RegisterL). + * @param aObs status observer implementation + */ + IMPORT_C void RegisterStatusObserverL( MImpsStatusHandler2* aObs ); + + /** + * Unregisters the service status change observer. + * Ignored if API does not have registered observer. + * This method is not necessary if unregister of the particular + * client type has been executed (Unregister). + */ + IMPORT_C void UnregisterStatusObserverL( ); + + /** + * Available services accessor + * Notice that the method leaves with KImpsErrorServices until + * service negotiation has been run. + * @param aServices Service tree having + * all supported features and functions. + */ + IMPORT_C void GetServicesL( TImpsServices& aServices ); + + /** + * Register an error event observer. + * If this is not registered then a client does not + * receive error events from WV engine. + * An application may implement only one HandleErrorL method + * and give pointer to it in each WV client instance. + * @param aObs error event observer + */ + IMPORT_C void RegisterErrorObserverL( MImpsErrorHandler2& aObs ); + + /** + * Unregisters an error observer. + * Ignored if API does not have an error observer. + * This method is not necessary if unregister of the particular + * client has been executed (Unregister). + */ + IMPORT_C void UnregisterErrorObserverL( ); + + /** + * Get the maximum TransactionContent size that WV engine + * and WV server can handle, related to ParserSize. + * Note that if service negotiation is not finished, this + * method returns 0. + * + * @return size or zero + */ + IMPORT_C TInt MaxTransactionContentLengthL( ); + + /** + * Get WV CSP version currently used + * Used literals are defined in impsconst.h + * @return version, e.g. "CSP1.1" + */ + IMPORT_C TPtrC WVVersionL(); + + /** + * Get CSP identifier used in login + * Leaves with KErrNotFound if not logged in. + * @return TImpsCspIdentifier + */ + IMPORT_C TImpsCspIdentifier* CspIdentifierL(); + + /** + * Cancel the ongoing request + * Removes the request from engine's message queue + */ + IMPORT_C void CancelTransaction( TInt aOperationId ); + + /** + * Sets the expiry time for requests + * New expiry time will be used for following requests that + * are sent by corresponding impsclient. + * Negative values are ignored. + */ + IMPORT_C void SetExpiryTime( TInt aSeconds ); + + /** + * Internal use only. + * Error observer accessor + * @return error observer + */ + MImpsErrorHandler2* ErrorHandler(); + + /** + * Internal use only + * @return TImpsCspIdentifier + */ + TImpsCspIdentifier* CspIdentifier(); + + + protected: // New functions + + /** + * Unregisters the listener object and disconnects from the server. + */ + void DoUnregister(); + + /** + * Assign application id for this session. + * + * This is an optional method, but highly recommended to provide + * enhanced message routing in the terminal. + * Possible reason for the method to fail is that + * RegisterL has not executed. + * + * @param aClientId client-id for message routing + * @return error code + */ + TInt DoAssign( const TDesC& aClientId ); + + /** + * Increases the operation id and if it goes over the upper range limit + * set it back to the lower limit + */ + void IncreaseOpId( ); + + /** + * Sets the operation id's upper and lower limit. + * Also set the operation id to the lowerlimit. + */ + void SetOpIdRange( ); + + /** + * Registers the listener object for Access events and connects to + * the Symbian OS Server. + * @param aEngine WV Engine server instance + * @param aHandler event observer + * @param aReq request to server TImpsServRequest + * @return operation id + */ + TInt DoRegister2( RImpsEng& aEngine, + CImpsHandler2* aHandler, + TInt aReq ); + + private: + + /** + * Registers the listener object for events and connects to + * the Symbian OS Server. + * @param aEngine WV Engine server instance + * @param aHandler event observer + * @return error code + */ + virtual TInt DoRegister( RImpsEng& aEngine, + CImpsHandler2* aHandler ) = 0; + + + protected: // data + + CImpsHandler2* iHandler; + CActive* iActiveCommand; + TBool iRunning; + HBufC* iClientId; + TInt iOpId; + TInt iLimitUpperValue; + TInt iLimitLowerValue; + TBool iSessionOpen; + TBool iHandleNew; + TBool iAnyContent; + RImpsEng* iEngine; + + private: // friend classes + friend class CImpsHandler2; + + }; + +/** +* MImpsStatusHandler2 +* +* Abstract interface for handling general status events from the server. +* User derives his class from this and implements the methods below. +*/ + +class MImpsStatusHandler2 + { + + public: // New functions + + /** + * Observer method for changes in service status. + * Each service type API may register this observer + * by RegisterStatusObserverL. + * @param aStatus new status. + * @param aCspId CSP session identifier + */ + virtual void HandleStatusChangeL( TImpsServiceStatus aStatus, + TImpsCspIdentifier& aCspId ) = 0; + + }; + +/** +* MImpsErrorHandler2 +* +* Abstract interface for handling error events from the server. +* User derives his class from this and implements the method below. +*/ + +class MImpsErrorHandler2 + { + + public: // New functions + + /** + * Observer method for error messages. + * This provides data for partial error responses too. + * Each service API MUST register this observer by RegisterErrorObserverL + * immediately after Register method. + * @param aStatus error code. + * @param aOpId operation id to map responses to the requests. + * @param aDescripton error description + * @param aDetailedRes detailed error description + * @param aCspId CSP session identifier + */ + virtual void HandleErrorL( TInt aStatus, + TInt aOpId, + const TDesC* aDescription, + const CImpsDetailed* aDetailedRes, + TImpsCspIdentifier& aCspId ) = 0; + + }; + + +#endif // IMPS_CLIENT_H + +// End of File