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