/*

* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "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:    Class to handle connection creation.*

*/

#ifndef __VCX_CONNUTIL_H_

#define __VCX_CONNUTIL_H_

// INCLUDES

#include <e32base.h>

// FORWARD DECLARATIONS

class CVcxConnUtilImpl;

class MConnUtilEngineObserver;

// CLASS DECLARATION

/**

* Class is the main interface class for the vcxconnectionutility.dll.

* By using this class, client can fetch iap ID and maintain an active connection

* for that iap.

* Usage:

*  @code

*  #include <vcxconnectionutility.h>

*  #include <vcxconnutilengineobserver.h> // for receiving events from ALR and iap changes

*

*  // Instantiation of connectionutility is done by Instance()

*  // every Instance call increments internal reference count by 

*  // one. When reference count is decremented to 0 deallocation

*  // occurs. Client should make sure that it calls as many

*  // DecreaseReferenceCount() as it calls InstanceL()

*

*  CVcxConnectionUtility* conUtil = CVcxConnectionUtility::InstanceL();

* 

*  // in case client is interested in events from ALR or from iap changes,

*  // client must implement MConnUtilEngineObserver interface and register

*  // as observer. See MConnUtilEngineObserver documentation for details 

*  conUtil->RegisterObserverL( this );

* 

*  // getting the best possible iap is handled by the GetIap

*  TInt err( KErrNone );

*  TUint32 iapId( 0 );

*  err = conUtil->GetIap( iapId, EFalse );

*  // in case client does not want the "connecting" dialog  // shown, aSilent

*  // parameter should be ETrue     

*

*  // client can try to explicitly disconnect connection, but if there are other references 

*  // connection is not closed.

*  // suggestion is to maintain connection at all time as long as vcxconnectionutility 

*  // is being used and just react to notifications 

*  conUtil->Disconnect();

*  

*  // when connectionutility is no longer needed, client must call DecreaseReferenceCount()

*  // if there are no more references left, memory allocated for the library is deallocated

*  // and possible active connection is closed

*  // if client has registered as observer, it should deregister first 

*  conUtil->RemoveObserver();

*  conUtil->DecreaseReferenceCount();  

*  conutil = NULL;

* 

*  @endcode

* 

*

* @lib vcxconnectionutility.dll

*/

NONSHARABLE_CLASS( CVcxConnectionUtility) : public CActive

    {

    public: // Constructors and destructor

        /**

         * returns instance of the singleton object. This increases

         * local reference count by one, so utility members should

         * not be called through this.

         *

         * @return Pointer to CVcxConnectionUtility object.

         */

        IMPORT_C static CVcxConnectionUtility* InstanceL();

        /**

        * Remove the reference to this connectionutility instance.

        * 

        * This should be called when client does not need 

        * utility anymore.

        *

        * Decreases the reference count by one. When

        * all references are removed, the ui engine is destructed.

        */

        IMPORT_C void DecreaseReferenceCount();

    private:

        /**

         * Destructor.

         */

        virtual ~CVcxConnectionUtility();

        /**

         * constructor.

         *

         */

        CVcxConnectionUtility( );

        /**

         * Private 2nd phase construction.

         */

        void ConstructL();

        /**

         * From CActive, handles an active object’s request completion event

         */

        void RunL();

        /**

         * From CActive, implements cancellation of an outstanding request.

         * This function is called as part of the active object’s Cancel().

         */

        void DoCancel();  

    public: // New functions

        /**

        * Returns open IAP, if connection is not opened it is created

        *

        * @param aIapId     On return, IAP ID.

        * @param aSilent    If ETrue, tries to open connection silently (without dialogs)

        *                   In the 'Always ask' mode query dialog is always shown.

        *                    

        * @return KErrNone or one of the system wide error codes.

        */

        IMPORT_C TInt GetIap( TUint32& aIapId, TBool aSilent );

        /**

         * Gets WAP id from IAP id. Leaves with KErrNotFound if no record with given 

         * IAP id is found.

         * 

         * @param aIapId IAP id to match.

         * @return WAP id matching the given IAP id.

         */

        IMPORT_C TUint32 WapIdFromIapIdL( TUint32 aIapId );

        /**

        * Closes open connection.

        */

        IMPORT_C void DisconnectL();

        /**

         * Registers observer

         * 

         * @param MConnUtilEngineObserver

         */

        IMPORT_C void RegisterObserverL( MConnUtilEngineObserver* aObserver );

        /**

         * Removes observer from the array of observers

         * 

         * @param MConnUtilEngineObserver 

         */

        IMPORT_C void RemoveObserver( MConnUtilEngineObserver* aObserver );

        /**

         * Displays a wait note. Method calls notifier to show 

         * dialog and sets this active object active. If user cancels

         * dialog by pressing cancel, RunL is being called with KErrCancel.

         *   

         * @param aConnectionName name of connection to show on the dialog          

         */ 

        void DisplayWaitNote( const TDesC& aConnectionName = KNullDesC );

        /**

         * closes a wait note

         *           

         */

        void CloseWaitNote();

    private: // Data

        /**

         * Count of references to this object.

         */ 

        TInt iReferenceCount;

        /**

         * Utility implementation object

         */

        CVcxConnUtilImpl* iUtilImpl;

        /**

         * Notifier used for showing connecting dialogs

         */

        RNotifier iNotifier; 

    };

#endif // __VCXNS_CONNUTIL_H_

// End of File