diff -r 000000000000 -r 094583676ce7 inc/ImpsAccessCli.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/inc/ImpsAccessCli.h Thu Dec 17 08:41:52 2009 +0200 @@ -0,0 +1,356 @@ +/* +* 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 +#include +#include +#include "impsconst.h" +#include "impsclient.h" + +// CONSTANTS + +// FORWARD DECLARATIONS +class 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