/*
* 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