/*

* Copyright (c) 2009 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: Implementation of Extended Connection Preferences API.

*              

*              This API defines extended connection parameters as a part of

*              custom preferences mechanism making possible for Symbian 

*              licensees to define their own parameter extensions.

*

*/

#if !(defined __EXTENDEDCONNPREF_H__)

#define __EXTENDEDCONNPREF_H__

#include <e32base.h>

#include <comms-infras/metadata.h>

#include <connpref.h>

#include <cmmanagerdef.h>

class TExtendedConnPref : public Meta::SMetaDataECom

/**

User of this API must remember to link against extendedconnpref.lib and 

netmeta.lib and add #include <extendedconnpref.h>.

Set methods for the extended connection preference. This preference cannot be

used with RConnection::Start as a TConnPref. It must be part of a 

TConnPrefList. The extented connection preference can be appeded to connection

setup parameters before RConnection::Start() dispatch. Appending is carried 

out as follows. 

See connpref.h for more details.

@code

RSocketServ sockSvr;

RConnection conn;

sockSvr.Connect();

User::LeaveIfError(conn.Open(sockSvr));

CleanupClosePushL(conn);

TConnPrefList prefList;

TExtendedConnPref extPrefs;

extPrefs.SetSnapPurpose( CMManager::ESnapPurposeInternet );

extPrefs.SetNoteBehaviour( ENoteBehaviourConnSilent );

prefList.AppendL(&extPrefs);

TInt error = conn.Start(prefList);

CleanupStack::PopAndDestroy(&conn);

@endcode

@see TConnPrefList

@see RConnection::Start

@publishedAll

@released since S60 5.2

*/

    {

public:

    enum

        {

        /** UID for Extended Connection Preference API implementation. */

        EUid = 0x20016A82, 

        /** Subidentifier. */

        ETypeId = 1

        };

    /**

    * ExtendedConnBearer enables application to request a specific bearer for

    * a connection.

    */

    enum TExtendedConnBearer

        {

        /** Bearer support unknown. */

        EExtendedConnBearerUnknown  = 0x00000000,

        /** Support GPRS, 3G and Cdma2000 bearers. CSD not supported. */

        EExtendedConnBearerCellular = 0x00000001,

        /** WLAN bearer support. */

        EExtendedConnBearerWLAN     = 0x00000002

        };

    /**

    * TNoteBehaviour enables application to request a specific behaviour from

    * the middleware regarding displaying of dialogs, notes and queries.

    */

    enum TNoteBehaviour

        {

        /** Displays notes and queries according to default settings. */

        ENoteBehaviourDefault            = 0x00000000,

        /**

        * Starts connection and roams between different bearers without any 

        * notes, i.e., notes about connection state are not shown to the user.

        */

        ENoteBehaviourConnDisableNotes   = 0x00000001,

        /**

        * Roams between different bearers without displaying any queries to

        * the user but informs the user on the events with dialogs or notes.

        * User is able to see only notes about connection state but not any

        * queries which would need user's confirmation.

        */

        ENoteBehaviourConnDisableQueries = 0x00000002

        };

    /**

    * Starts connection and roams between different bearers without any 

    * queries, dialogs or notes, i.e., nothing about connection is shown

    * to the user.

    */

    static const TUint32 ENoteBehaviourConnSilent =

        ENoteBehaviourConnDisableNotes | ENoteBehaviourConnDisableQueries;

    /** 

    * Constructor.

    */

    IMPORT_C TExtendedConnPref();

    /**

    * Sets the purpose of the SNAP identifying where the connection is 

    * requested to. This function enables applications to start a connection

    * to, e.g., Internet SNAP or intranet SNAP without iterating through all

    * SNAPs to find the ID of the right one.

    * Default value is ESnapPurposeUnknown meaning that any SNAP is fine.

    * 

    * If SNAP purpose is set, IAP id shall be zero.

    * If SNAP purpose is set, SNAP id shall be zero.

    * If SNAP purpose is set, Connection selection dialog shall be disabled.

    * Either SNAP purpose, SNAP id, or IAP id shall be given, or Connection

    * selection dialog shall be enabled.

    * 

    * @param aSnapPurpose SNAP Purpose.

    */

    IMPORT_C void SetSnapPurpose( CMManager::TSnapPurpose aSnapPurpose );

    /**

    * Gets SNAP purpose.

    *

    * @return SNAP purpose.

    */

    IMPORT_C CMManager::TSnapPurpose SnapPurpose() const;

    /**

    * Sets SNAP id. If SNAP id is zero, it is interpreted as 

    * client's request for not requesting any specific SNAP.

    * Default value is 0.

    *

    * If SNAP id is set, IAP id shall be zero.

    * If SNAP id is set, SNAP purpose shall be CMManager::ESnapPurposeUnknown.

    * If SNAP id is set, Connection selection dialog shall be disabled.

    * Either SNAP purpose, SNAP id, or IAP id shall be given, or Connection

    * selection dialog shall be enabled.

    *

    * @param aSnap SNAP id.

    */

    IMPORT_C void SetSnapId( TUint32 aSnapId );

    /**

    * Gets SNAP id.

    *

    * @return SNAP id.

    */

    IMPORT_C TUint32 SnapId() const;

    /**

    * Sets IAP id.

    * 

    * Setting IAP id means that the connection will be made utilizing given

    * IAP id no matter what existing connections are available.

    * 

    * If IAP id is zero, it is interpreted as

    * client's request for not requesting any specific IAP.

    * Default value is 0.

    * 

    * If IAP id is set, SNAP id shall be zero.

    * If IAP id is set, SNAP purpose shall be CMManager::ESnapPurposeUnknown.

    * If IAP id is set, Connection selection dialog shall be disabled.

    * If IAP id is set, bearer set shall be EExtendedConnBearerUnknown.

    * If IAP id is set, forced roaming is disabled automatically.

    * Either SNAP purpose, SNAP id, or IAP id shall be given, or Connection

    * selection dialog shall be enabled.

    * 

    * @param aIap IAP id.

    */

    IMPORT_C void SetIapId( TUint32 aIapId );

    /**

    * Gets IAP id.

    *

    * @return IAP id.

    */

    IMPORT_C TUint32 IapId() const;

    /**

    * Sets bearer, use combination of TExtendedConnBearer values.

    * Default value is KExtendedConnBearerUnknown.

    *

    * @param aBearerSet A set of bearers as a combination of

    *                   TExtendedConnBearer values.

    *                   Type is TUint32 due to bitfield character.

    */

    IMPORT_C void SetBearerSet( TUint32 aBearerSet );

    /**

    * Gets set of requested bearers.

    *

    * @return Set of requested bearers. Type is TUint32 due to bifield

    *         character.

    */

    IMPORT_C TUint32 BearerSet() const;

    /**

    * Sets note behaviour, use combination of TNoteBehaviour values.

    * Default value is ENoteBehaviourDefault.

    * This method does not control connection selection dialog or disconnect

    * dialog. There are own methods for these purposes in this API.

    *

    * @param aNoteBehaviour Note behaviour as a combination of TNoteBehaviour

    *                       values. Type is TUint32 due to bitfield

    *                       character.

    */ 

    IMPORT_C void SetNoteBehaviour( TUint32 aNoteBehaviour );

    /**

    * Gets note behaviour.

    *

    * @return Note behaviour as a combination of TNoteBehaviour values.

    *         Type is TUint32 due to bitfield character.

    */

    IMPORT_C TUint32 NoteBehaviour() const;

    /**

    * Enables or disables Disconnect dialog.

    * By default, Disconnect dialog is enabled.

    *

    * @param aEnableDisconnectDialog Indicates whether Disconnect dialog is

    *                                enabled or disabled.

    */

    IMPORT_C void SetDisconnectDialog( TBool aEnableDisconnectDialog );

    /**

    * Indicates whether Disconnect dialog is enabled.

    *

    * @return Indicates whether Disconnect dialog is enabled.

    */

    IMPORT_C TBool DisconnectDialog() const;

    /**

    * Enables or disables Connection selection dialog. Only the SNAPs/IAPs

    * matching with BearerSet are shown in the dialog.

    * By default, Connection selection dialog is disabled.

    *

    * If Connection selection dialog is enabled, SNAP id shall be zero.

    * If Connection selection dialog is enabled, IAP id shall be zero.

    * If Connection selection dialog is enabled, SNAP purpose shall be

    * CMManager::ESnapPurposeUnknown.

    * Either SNAP purpose, SNAP id, or IAP id shall be given, or Connection

    * selection dialog shall be enabled.

    *

    * @param aConnSelectionDialog Indicates whether Connection selection

    *                             dialog is enabled or disabled.

    */

    IMPORT_C void SetConnSelectionDialog( TBool aConnSelectionDialog );

    /**

    * Indicates whether Connection selection dialog is enabled.

    *

    * @return Indicates whether Connection selection dialog is enabled.

    */

    IMPORT_C TBool ConnSelectionDialog() const;

    /**

    * Enables or disables forced roaming.

    * By default, forced roaming is enabled.

    * Forced roaming only applies on connections made to Internet SNAP.

    * 

    * Forced roaming means that the connection can be torn down by the

    * middleware when better one is available. E.g., when known WLAN IAP

    * becomes available, 3G connection is disconnected.

    * 

    * @param aForcedRoaming Indicates whether forced roaming is enabled or

    *                       disabled.

    */

    IMPORT_C void SetForcedRoaming( TBool aForcedRoaming );

    /**

    * Indicates whether forced roaming is enabled.

    *

    * @return Indicates whether forced roaming is enabled.

    */

    IMPORT_C TBool ForcedRoaming() const;

protected:

    /** SMetaData implied functions */

    EXPORT_DATA_VTABLE_AND_FN

private:

    /** SNAP purpose. */

    CMManager::TSnapPurpose iSnapPurpose;

    /** SNAP id. */

    TUint32 iSnapId;

    /** IAP id. */

    TUint32 iIapId;

    /** Bearer set. */

    TUint32 iBearerSet;

    /** Note behaviour. */

    TUint32 iNoteBehaviour;

    /** Indicates whether UI disconnect dialog is shown. */

    TBool iDisconnectDialog;

    /** Indicates whether UI connection selection dialog is shown. */    

    TBool iConnSelectionDialog;

    /** Indicates whether forced roaming is enabled. */

    TBool iForcedRoaming;

    };

#endif __EXTENDEDCONNPREF_H__