/*

* Copyright (c) 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:  IMPS Connection UI.

*

*/

#ifndef __CIMPSPRESENCECONNECTIONUING_H__

#define __CIMPSPRESENCECONNECTIONUING_H__

// INCLUDES

#include <E32base.h>

#include <PEngPresenceEngineConsts2.h>

#include <impspresenceconnectionuiconstsng.h>

// FORWARD DECLARATION

class MIMPSConnProcessObserver;

class CIMPSSAPSettingsStore;

class CIMPSPresenceConnectionUiImp;

class CIMPSSAPSettings;

class CPEngNWSessionSlotID2;

// CLASS DECLARATION

/**

 * CIMPSPresenceConnectionUi.

 *

 * CIMPSPresenceConnectionUi encapsulates remote Presence Server connection /

 * disconnection procedures. CIMPSPresenceConnectionUi allows applications

 * just execute the connection procedure, CIMPSPresenceConnectionUi shows

 * all required UI notes, asks login data from user when needed, etc.

 *

 * @lib IMPSConnectionUi

 * @since 3.0

 */

class CIMPSPresenceConnectionUi : public CBase

    {

    public:  // Two-phased constructors and destructor

        /**

         * Two-phased constructor.

         *

         * @param aClient The client using the Connection UI

         * @param aSapStore The SAP settings store to use.

         * Given SAP settings store object lifetime must be

         * longer than created CIMPSPresenceConnectionUi.

         * If no SAP settings store provided, creates own

         * SAP Settings store internally when needed.

         */

        IMPORT_C static CIMPSPresenceConnectionUi* NewL(

            TIMPSConnectionClient aClient,

            CIMPSSAPSettingsStore* aSapStore = NULL );

        /**

         * Two-phased constructor.

         * Leaves CIMPSPresenceConnectionUi object on the

         * CleanupStack.

         *

         * @param aClient The client using the Connection UI

         * @param aSapStore The SAP settings store to use.

         * Given SAP settings store object lifetime must be

         * longer than created CIMPSPresenceConnectionUi.

         * If no SAP settings store provided, creates own

         * SAP Settings store internally when needed.

         */

        IMPORT_C static CIMPSPresenceConnectionUi* NewLC(

            TIMPSConnectionClient aClient,

            CIMPSSAPSettingsStore* aSapStore = NULL );

        /**

         * Destructor.

         */

        IMPORT_C virtual ~CIMPSPresenceConnectionUi();

    public:  // New connection handling methods

        /**

         * Connects to remote presence server.

         *

         * Handles error situations internally by showing

         * a proper error note. Asks login data and used server

         * from user when needed. Retries to open the connection if

         * needed.

         *

         * Connection status is returned as return value.

         * Internal Symbian OS errors (like running out of resources,

         * or other fatal errors coming from underlying Presence Engine)

         * are handled by leaving.

         *

         * The client must intialize an instance of CPEngNWSessionSlotID2

         * and give it as a parameter. When the call returns the slot ID

         * contains the current active connection's network session slot ID.

         *

         * @since 3.0

         * @param aClient The client using the Connection UI to login

         * to presence service. (This client is logged in.)

         * @param aLoginType Wanted Connection UI behaviour.

         * @param aNWSessionSlotID a network session slot ID, on return will contain

         *        the active network session slot ID

         * @param aObserver The observer to notify from login process

         * events.

         * @return Login operation status, one of following:

         * - KErrNone ==> Login succeeded

         * - KErrNotFound ==> Missing the whole default SAP / or no SAP's at all

         * - KErrArgument ==> Default / selected SAP to login was

         *                    missing some required fields. (URL & AccessPoint)

         * - KErrCancel ==> User has cancelled the login at some point.

         * - KErrAlreadyExist ==> Current client is already logged in.

         *                        (Thus not a real error.)

         * - KErrGeneral ==> General failure during login (no connection

         *                   to network, network access denied, etc..)

         */

        IMPORT_C TInt LoginL( TIMPSConnectionClient aClient,

                              TIMPSLoginType aLoginType,

                              CPEngNWSessionSlotID2& aNWSessionSlotID,

                              MIMPSConnProcessObserver* aObserver = NULL,

                              CIMPSSAPSettings* aSap = NULL, TBool aLastLoginSap = EFalse );

        /**

         * Disconnects from remote presence server.

         *

         * Internal Symbian OS errors (like running out of resources,

         * or other fatal errors coming from underlying Presence Engine)

         * are handled by leaving.

         *

         * @since 3.0

         * @param aNWSessionSlotID a network session slot ID to logout from.

         * @param aObserver The observer to notify from logout process

         * events.

         * @return Currently always KErrNone.

         */

        IMPORT_C TInt LogoutL( const CPEngNWSessionSlotID2& aNWSessionSlotID,

                               MIMPSConnProcessObserver* aObserver = NULL );

        /**

         * Handles the application exit according the

         * IMPS Server Settings specification.

         *

         * Internal Symbian OS errors (like running out of resources,

         * or other fatal errors coming from underlying Presence Engine)

         * are handled by leaving.

         *

         * @since 3.0

         * @param aClient Which client categorys exit to handle.

         *

         * @param TIMPSExitType Wished  behaviour of handle exit.

         * EIMPSNormalExit:

         * If there exist open connection for the given application

         * category, and the connection type is is  manual or application

         * launch, a confirmation query is opened wether to close

         * open connection or not. Connection is closed if desired so.

         * EIMPSForceExit:

         * No confirmation queries etc. isn't shown.

         * Existing open connection is silently closed.

         *

         * EIMPSLeaveSessionOpenExit:

         * The network session is left open by storing the network session

         * slot ownership to Presence engine. This ownership is restored

         * next time the application starts

         *

         * @param aNWSessionSlotID the current network session slot ID.

         * @param aObserver The observer to notify from logout process

         * events.

         * @return Currently always KErrNone.

         */

        IMPORT_C TInt HandleApplicationExitL( TIMPSConnectionClient aClient,

                                              TIMPSExitType aExitType,

                                              const CPEngNWSessionSlotID2& aNWSessionSlotID,

                                              MIMPSConnProcessObserver* aObserver = NULL );

        /**

         * Gets the remote presence server connection status.

         *

         * @since 3.0

         * @param aClient The client which connection status

         * to check.

         * @return ETrue if client is logged in, else EFalse.

         */

        IMPORT_C TBool LoggedInL( TIMPSConnectionClient aClient );

        /**

         * Gets the currently active network session slot id.

         * If there is no active network session slot ID return

         * the default SAP's network session slot ID.

         * If there are no SAPs defined in the system leaves

         * with KErrNotFound.

         * Note that ownership is transferred to the caller.

         *

         * @since 3.0

         * @param aClient The client which slots to get

         * @return the network session slot ID

         */

        IMPORT_C CPEngNWSessionSlotID2* GetActiveNWSessionSlotIDL( TIMPSConnectionClient aClient );

        /**

         * Gets the remote presence server settings.

         *

         * Gets the remote presence server settings for

         * current connection. There can be just one

         * real network presence connection active at time,

         * and this method retrieves details of that

         * connection. (Different client groups share

         * logically on real network connection.)

         *

         * If there isn't a active (logged in) connection

         * for any of known clients, returns KErrNotFound.

         * Else the given aSap is filled with connection

         * settings and KErrNone is returned.

         *

         * If sap get fails due out of resources or to some

         * other fatal error coming from underlying PEC engine,

         * leaves with system error codes. In this case

         * aSap parameter state is undetermined.

         *

         * @since 3.0

         * @param aNWSessionSlotID the current active network session slot ID

         * @param aSap The SAP container to fill with current

         * connection settings.

         * @return KErrNone if there exist a connection for known

         * client. Else KErrNotFound.

         */

        IMPORT_C TInt GetLoggedInSapL( const CPEngNWSessionSlotID2& aNWSessionSlotID,

                                       CIMPSSAPSettings& aSap );

        /**

         * Gets the pure connection status from Presence Engine.

         *

         * @since 3.0

         * @param aNWSessionSlotID a network session slot ID

         * @return Connection status from Presence Engine.

         */

        IMPORT_C TPEngNWSessionSlotState PureServiceStatusL(

            const CPEngNWSessionSlotID2& aNWSessionSlotID );

        /**

         * Gets the currently ongoing connection

         * state change operation. Returned operation

         * is client wide, so it doesn't care about which

         * client is doing the operation.

         *

         * @since 3.0

         * @param aAddtionalDesc The descriptor describing / related

         * to current connection operation. Method allocates a

         * buffer for descriptive descriptor if needed and returns

         * its to caller trough the HBufC*& aDetailDesc.

         * Ownership of the created buffer is returned to

         * caller. (NOTE! Only EIMPSConnOppClientLogin returns

         * descriptive text, currently connected server name.

         * Other operations return NULL.)

         * @return The Current connection operation.

         */

        IMPORT_C TIMPSConnectionOperation CurrentConnectionOperationL( HBufC*& aAddtionalDesc );

    public:  // Other new functions

        /**

         * Displays a list query for selecting a domain ("@domain.com" etc.)

         * @param aSelectedDomain Here is copied the domain user selected.

         * @param aSap Current SAP settings, previously selected domain is

         *             stored per SAP.

         * @return If user cancelled the query return 0,

         *         otherwise the dialog dismiss key code

         * @since 3.1u

         */

        IMPORT_C TInt DisplayDomainSelectionQueryL( TDes& aSelectedDomain,

                                                    CIMPSSAPSettings* aSap );

    private: //Constructors.

        /**

         * C++ default constructor.

         */

        CIMPSPresenceConnectionUi( TIMPSConnectionClient aClient );

        /**

         * Symbian OS constructor.

         */

        void ConstructL( CIMPSSAPSettingsStore* aSapStore );

    private: //Data

        CIMPSPresenceConnectionUiImp*     iImp;          ///<Implementation, owned

        TIMPSConnectionClient             iClient;       ///<Client using the Connection UI

        TAny*                             iReserved1;    ///<Reserved, owned

    };

#endif      //__CIMPSPRESENCECONNECTIONUING_H__

//  End of File