/** 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: * Interface for WV access services**/#ifndef IMPS_ACCESS_CLIENT_H#define IMPS_ACCESS_CLIENT_H// INCLUDES#include <e32base.h>#include <badesca.h>#include <bamdesca.h>#include "impsconst.h"#include "impsclient.h"// CONSTANTS// FORWARD DECLARATIONSclass MImpsAccessHandler2;class CImpsAccessCommand2;// CLASS DECLARATION/*** RImpsAccessClient2 API** Applications use Access service via RImpsAccessClient2 class. * First, they need to connect to the server by calling RegisterL()* member function. Immediately after that an error handler* must be registered by RegisterErrorObserverL. * * When everything is done, call Unregister() to end* the session.** A user of this API must be aware that raising/releasing* the PDP context may affect the response times of called functions.** One client-server session can have only one CSP session.** Observer methods:* -----------------------* Client can be notified when a certain type of message is received * from the remote server.* Client has to be connected in the server in order to get notify events.* If the client is disconnected by server by calling Unregister(), * all notify requests and possible incoming events are cancelled. ** Notify events are session-specific, i.e. if you have several * ImpsAccessClients connected to the server, each has its own notify * requests. ** In order to use notify services, you need to implement * MImpsAccessHandler2 and give a pointer to your class in RegisterL.* Observer method doesn't need to do anything else than your application * needs it to do.** * Addressing:* -----------* WV CSP specification defines characters that must be escaped if they* occur within the User-ID, Resource or Domain portions of a Wireless Village* address. WV engine does NOT escape those characters on behalf of user * application. WV CSP also denies usage of certain characters in UserID* totally.**/ class RImpsAccessClient2 : public RImpsClient2 { public: // Constructors and destructor /** * C++ default constructor. */ IMPORT_C RImpsAccessClient2(); public: // New functions // INITILIZATION AND CONNECT /** * Registers the listener object for Access events and connects to * the Symbian OS Server. * Leaves with KImpsErrorAlreadyInUse if the client * has already registered. * @param aEngine WV Engine server instance * @param aObserver The observer. * @param aPriority Observer priority. Refer to CActive priority. */ IMPORT_C void RegisterL( RImpsEng& aEngine, MImpsAccessHandler2* aObserver, TInt aPriority = CActive::EPriorityStandard ); /** * Unregisters the listener object and disconnects from the server. */ IMPORT_C void Unregister(); /** * Get number of Symbian OS sessions connected to the server * @param aCspId Identifier for the session. * @return number of sessions */ IMPORT_C TInt NumberOfSessionsL( TImpsCspIdentifier& aCspId ); // ACCESS SERVICES /** * Login to Service Access Point (SAP). * MImpsAccessHandler2 handles successful server response. * Errors are handled by MImpsErrorHandler2: * KImpsErrorAP if access point cannot be accessed * KImpsErrorShuttingDown if authoritative session stop is ongoing. * . * Leaves with KErrArgument if maximum lengths of * parameters are exceeded. * Leaves with KErrNotReady if login cancellation * is still in progress. * The CSP session id is stored in the engine, and it is not * visible in this API. * If there is ongoing login to the same CSP session leaves with * KErrNotReady. * @param aCspId contains SAP URI and userId. Note that a * strict match will be used when compared to * existing sessions. * @param aPsw password * @param aClientId client id used to log in server. * The client-id having prefix '+' or number is considered * as MSISDN number (E.164), * otherwise it is handled as URL. * This MAY be used for CIR addressing if SAP is not able to * detect MSISDN number in other way * @param aAP CommDb id for access point * @param aKey1 privateKey1 or NULL * @param aKey2 privateKey2 or NULL * @return operation-id (positive) */ IMPORT_C TInt LoginL( TImpsCspIdentifier aCspId, const TDesC& aPsw, const TDesC& aClientId, TUint32 aAP, const TDesC* aKey1 = NULL, const TDesC* aKey2 = NULL ); /** * Login to Service Access Point (SAP) using reactive authorization. * MImpsAccessHandler2 handles successful server response. * Errors are handled by MImpsErrorHandler2: * KImpsErrorAP if access point cannot be accessed * KImpsErrorShuttingDown if authoritative session stop is ongoing. * . * Leaves with KErrArgument if maximum lengths of * parameters are exceeded. * Leaves with KErrNotReady if login cancellation * is still in progress. * The CSP session id is stored in the engine, and it is not * visible in this API. * If there is ongoing login to the same CSP session leaves with * KErrNotReady. * @param aCspId contains SAP URI and userId. Note that a * strict match will be used when compared to * existing sessions. * @param aPsw password * @param aClientId client id used to log in server. * The client-id having prefix '+' or number is considered * as MSISDN number (E.164), * otherwise it is handled as URL. * This MAY be used for CIR addressing if SAP is not able to * detect MSISDN number in other way * @param aAP CommDb id for access point * @param aKey1 privateKey1 or NULL * @param aKey2 privateKey2 or NULL * @return operation-id (positive) */ IMPORT_C TInt ReactiveLoginL( TImpsCspIdentifier aCspId, const TDesC& aPsw, const TDesC& aClientId, TUint32 aAP, const TDesC* aKey1 = NULL, const TDesC* aKey2 = NULL ); /** * Logout the client session. * MImpsAccessHandler2 handles successful server response. * Errors are handled by MImpsErrorHandler2 * KImpsErrorNotLogged if was not logged in. * KImpsErrorShuttingDown if authoritative session stop is ongoing. * Note: Error messages are not sent for all pending regular * requests in case of a CSP session logout (either a terminal * or a SAP initiated logout). After the status has changed to * NOT_LOGGED, the pending regular requests are ignored and the * corresponding observer methods are never called. Therefore * it is highly recommendable that one client instance of the * application registers a status observer to detect the * NOT_LOGGED status. * @return operation-id (positive) */ IMPORT_C TInt LogoutL( ); /** * Cancel the ongoing login * Causes a logout request to the WV server. * MImpsAccessHandler2 handles successful server response. * Errors are handled by MImpsErrorHandler2 * KImpsErrorNotLogged if is not tried to log in. * KImpsErrorShuttingDown if authoritative session stop is ongoing. * Leaves with KErrArgument if there is no ongoing login * If the login is completed in * engine, the request cannot be canceled, leaves with KErrNotFound. * In this kind of situations handleLogin or handleError will be called. * @param aCancelOpId, operation-id of the login call to be cancelled. */ IMPORT_C void CancelLoginL( TInt aCancelOpId ); /** * Authorative session stop * Closes all CSP sessions at once * * After this method has been called, WVEngine calls * HandleStatusChangeL(EImps_SHUTTING_DOWN).The client should then call * Unregister() immediately. When all clients are disconnected, WVEngine * goes down. All method calls except Unregister() * and Close() during the shutdown will cause KImpsErrorShuttingDown * Note: If there are any pending requests the WVEngine DOES NOT * complete the requests. */ IMPORT_C void CloseCspSessionsL( ); /** * Pointer to the observer handler * @return handler */ MImpsAccessHandler2* Handler(); /** * Get stored operation id * @return opId */ TInt LoginOpId(); /** * Is the login cancelled * @return boolean */ TBool LoginCancelled(); /** * Login cancel handled */ void CancelHandled(); private: /** * Registers the listener object for Access events and connects to * the Symbian OS Server. * @param aEngine WV Engine server instance * @param aHandler the observer * @return general error code */ TInt DoRegister( RImpsEng& aEngine, CImpsHandler2* aHandler ); private: // data CImpsAccessCommand2* iCommand; MImpsAccessHandler2* iHandlerCallBack; // Local copies of data to enable internally asyncronous request TPtrC8 iSAP; TInt iLoginOpId; TBool iLoginCancelled; private: // friend classes friend class CImpsAccessCommand2; };// CLASS DECLARATION/*** MImpsAccessHandler2** Abstract interface for handling the notify events from the server.* User derives his class from this and implements the methods below.*/class MImpsAccessHandler2 { public: // New functions /** * Observer method for Login event. * Login may be initiated by other application. * @param aId operation id received in LoginL. If this is 0, then the * login was initated by other application or SAP. * @param aCspId CSP session identifier */ virtual void HandleLoginL( TInt aId, TImpsCspIdentifier& aCspId ) = 0; /** * Observer method for Logout event. * @param aId operation id received in LogoutL. If this is 0, then the * logout was initated by other application or caused by a serious * network error. SAP initiated logouts are identfied with -1. * @param aCspId CSP session identifier */ virtual void HandleLogoutL( TInt aId, TImpsCspIdentifier& aCspId ) = 0; /** * Observer method for CancelLogin event. * @param aCancelledOpId operation id of the cancelled login. * @param aCspId CSP session identifier */ virtual void HandleLoginCancelL( TInt aCancelledOpId, TImpsCspIdentifier& aCspId ) = 0; /** * Obsolete, NOT IN USE * @param aId operation id * @param aNbr number of sessions * @param aCspId CSP session identifier * */ virtual void HandleNbrSessionsL( TInt aId, TInt aNbr, TImpsCspIdentifier& aCspId ) = 0; };#endif