/*

* 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