--- /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 <e32base.h>
+#include <badesca.h>
+#include <bamdesca.h>
+#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