1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Implementation of Extended Connection Preferences API.

    15 *              

    16 *              This API defines extended connection parameters as a part of

    17 *              custom preferences mechanism making possible for Symbian 

    18 *              licensees to define their own parameter extensions.

    19 *

    20 */

    21 

    22 #if !(defined __EXTENDEDCONNPREF_H__)

    23 #define __EXTENDEDCONNPREF_H__

    24 

    25 #include <e32base.h>

    26 #include <comms-infras/metadata.h>

    27 #include <connpref.h>

    28 #include <cmmanagerdef.h>

    29 

    30 

    31 class TExtendedConnPref : public Meta::SMetaDataECom

    32 /**

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

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

    35 

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

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

    38 TConnPrefList. The extented connection preference can be appeded to connection

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

    40 out as follows. 

    41 

    42 See connpref.h for more details.

    43 

    44 @code

    45 

    46 RSocketServ sockSvr;

    47 RConnection conn;

    48 

    49 sockSvr.Connect();

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

    51 CleanupClosePushL(conn);

    52 

    53 TConnPrefList prefList;

    54 TExtendedConnPref extPrefs;

    55 

    56 extPrefs.SetSnapPurpose( CMManager::ESnapPurposeInternet );

    57 extPrefs.SetNoteBehaviour( ENoteBehaviourConnSilent );

    58 

    59 prefList.AppendL(&extPrefs);

    60 

    61 TInt error = conn.Start(prefList);

    62 

    63 CleanupStack::PopAndDestroy(&conn);

    64 @endcode

    65 

    66 @see TConnPrefList

    67 @see RConnection::Start

    68 

    69 @publishedAll

    70 @released since S60 5.2

    71 */

    72     {

    73 public:

    74  

    75     enum

    76         {

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

    78         EUid = 0x20016A82, 

    79         /** Subidentifier. */

    80         ETypeId = 1

    81         };

    82 

    83     /**

    84     * ExtendedConnBearer enables application to request a specific bearer for

    85     * a connection.

    86     */

    87     enum TExtendedConnBearer

    88         {

    89         /** Bearer support unknown. */

    90         EExtendedConnBearerUnknown  = 0x00000000,

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

    92         EExtendedConnBearerCellular = 0x00000001,

    93         /** WLAN bearer support. */

    94         EExtendedConnBearerWLAN     = 0x00000002

    95         };

    96 

    97     /**

    98     * TNoteBehaviour enables application to request a specific behaviour from

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

   100     */

   101     enum TNoteBehaviour

   102         {

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

   104         ENoteBehaviourDefault            = 0x00000000,

   105         /**

   106         * Starts connection and roams between different bearers without any 

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

   108         */

   109         ENoteBehaviourConnDisableNotes   = 0x00000001,

   110         /**

   111         * Roams between different bearers without displaying any queries to

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

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

   114         * queries which would need user's confirmation.

   115         */

   116         ENoteBehaviourConnDisableQueries = 0x00000002

   117         };

   118 

   119     /**

   120     * Starts connection and roams between different bearers without any 

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

   122     * to the user.

   123     */

   124     static const TUint32 ENoteBehaviourConnSilent =

   125         ENoteBehaviourConnDisableNotes | ENoteBehaviourConnDisableQueries;

   126 

   127     /** 

   128     * Constructor.

   129     */

   130     IMPORT_C TExtendedConnPref();

   131     

   132     /**

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

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

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

   136     * SNAPs to find the ID of the right one.

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

   138     * 

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

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

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

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

   143     * selection dialog shall be enabled.

   144     * 

   145     * @param aSnapPurpose SNAP Purpose.

   146     */

   147     IMPORT_C void SetSnapPurpose( CMManager::TSnapPurpose aSnapPurpose );

   148 

   149     /**

   150     * Gets SNAP purpose.

   151     *

   152     * @return SNAP purpose.

   153     */

   154     IMPORT_C CMManager::TSnapPurpose SnapPurpose() const;

   155 

   156     /**

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

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

   159     * Default value is 0.

   160     *

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

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

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

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

   165     * selection dialog shall be enabled.

   166     *

   167     * @param aSnap SNAP id.

   168     */

   169     IMPORT_C void SetSnapId( TUint32 aSnapId );

   170 

   171     /**

   172     * Gets SNAP id.

   173     *

   174     * @return SNAP id.

   175     */

   176     IMPORT_C TUint32 SnapId() const;

   177 

   178     /**

   179     * Sets IAP id.

   180     * 

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

   182     * IAP id no matter what existing connections are available.

   183     * 

   184     * If IAP id is zero, it is interpreted as

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

   186     * Default value is 0.

   187     * 

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

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

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

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

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

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

   194     * selection dialog shall be enabled.

   195     * 

   196     * @param aIap IAP id.

   197     */

   198     IMPORT_C void SetIapId( TUint32 aIapId );

   199 

   200     /**

   201     * Gets IAP id.

   202     *

   203     * @return IAP id.

   204     */

   205     IMPORT_C TUint32 IapId() const;

   206 

   207     /**

   208     * Sets bearer, use combination of TExtendedConnBearer values.

   209     * Default value is KExtendedConnBearerUnknown.

   210     *

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

   212     *                   TExtendedConnBearer values.

   213     *                   Type is TUint32 due to bitfield character.

   214     */

   215     IMPORT_C void SetBearerSet( TUint32 aBearerSet );

   216 

   217     /**

   218     * Gets set of requested bearers.

   219     *

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

   221     *         character.

   222     */

   223     IMPORT_C TUint32 BearerSet() const;

   224 

   225     /**

   226     * Sets note behaviour, use combination of TNoteBehaviour values.

   227     * Default value is ENoteBehaviourDefault.

   228     * This method does not control connection selection dialog or disconnect

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

   230     *

   231     * @param aNoteBehaviour Note behaviour as a combination of TNoteBehaviour

   232     *                       values. Type is TUint32 due to bitfield

   233     *                       character.

   234     */ 

   235     IMPORT_C void SetNoteBehaviour( TUint32 aNoteBehaviour );

   236 

   237     /**

   238     * Gets note behaviour.

   239     *

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

   241     *         Type is TUint32 due to bitfield character.

   242     */

   243     IMPORT_C TUint32 NoteBehaviour() const;

   244 

   245     /**

   246     * Enables or disables Disconnect dialog.

   247     * By default, Disconnect dialog is enabled.

   248     *

   249     * @param aEnableDisconnectDialog Indicates whether Disconnect dialog is

   250     *                                enabled or disabled.

   251     */

   252     IMPORT_C void SetDisconnectDialog( TBool aEnableDisconnectDialog );

   253 

   254     /**

   255     * Indicates whether Disconnect dialog is enabled.

   256     *

   257     * @return Indicates whether Disconnect dialog is enabled.

   258     */

   259     IMPORT_C TBool DisconnectDialog() const;

   260 

   261     /**

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

   263     * matching with BearerSet are shown in the dialog.

   264     * By default, Connection selection dialog is disabled.

   265     *

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

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

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

   269     * CMManager::ESnapPurposeUnknown.

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

   271     * selection dialog shall be enabled.

   272     *

   273     * @param aConnSelectionDialog Indicates whether Connection selection

   274     *                             dialog is enabled or disabled.

   275     */

   276     IMPORT_C void SetConnSelectionDialog( TBool aConnSelectionDialog );

   277 

   278     /**

   279     * Indicates whether Connection selection dialog is enabled.

   280     *

   281     * @return Indicates whether Connection selection dialog is enabled.

   282     */

   283     IMPORT_C TBool ConnSelectionDialog() const;

   284 

   285     /**

   286     * Enables or disables forced roaming.

   287     * By default, forced roaming is enabled.

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

   289     * 

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

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

   292     * becomes available, 3G connection is disconnected.

   293     * 

   294     * @param aForcedRoaming Indicates whether forced roaming is enabled or

   295     *                       disabled.

   296     */

   297     IMPORT_C void SetForcedRoaming( TBool aForcedRoaming );

   298 

   299     /**

   300     * Indicates whether forced roaming is enabled.

   301     *

   302     * @return Indicates whether forced roaming is enabled.

   303     */

   304     IMPORT_C TBool ForcedRoaming() const;

   305 

   306 protected:

   307     /** SMetaData implied functions */

   308     EXPORT_DATA_VTABLE_AND_FN

   309 

   310 private:

   311 

   312     /** SNAP purpose. */

   313     CMManager::TSnapPurpose iSnapPurpose;

   314     /** SNAP id. */

   315     TUint32 iSnapId;

   316     /** IAP id. */

   317     TUint32 iIapId;

   318     /** Bearer set. */

   319     TUint32 iBearerSet;

   320     /** Note behaviour. */

   321     TUint32 iNoteBehaviour;

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

   323     TBool iDisconnectDialog;

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

   325     TBool iConnSelectionDialog;

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

   327     TBool iForcedRoaming;

   328     };

   329 

   330 

   331 #endif __EXTENDEDCONNPREF_H__