1 /*

     2 * Copyright (c) 2006-2008 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:  ECom interface definition for WLAN Control API.

    15 *

    16 */

    17 

    18 /*

    19 * %version: 11 %

    20 */

    21 

    22 #ifndef WLANCONTROLINTERFACE_H

    23 #define WLANCONTROLINTERFACE_H

    24 

    25 #include <wlanpowersaveinterface.h> // TWlanPowerSave

    26 #include <wlanmgmtcommon.h>         // TWlanBssid, TWlanSsid

    27 

    28 // INCLUDES

    29 #include <e32std.h>

    30 

    31 

    32 /** Defines the possible values of maximum service period length. */

    33 enum TWlanMaxServicePeriodLength

    34     {

    35     EWlanMaxServicePeriodLengthAll,

    36     EWlanMaxServicePeriodLengthTwo,

    37     EWlanMaxServicePeriodLengthFour,

    38     EWlanMaxServicePeriodLengthSix,

    39     };

    40 

    41 /** Defines the possible values of last cause for roaming. */

    42 enum TWlanRoamReason

    43     {

    44     EWlanRoamReasonLowRssi,

    45     EWlanRoamReasonApLost,

    46     };

    47 

    48 /**

    49  * Possible WLAN regions.

    50  */

    51 enum TWlanRegion

    52     {

    53     /** Channels 1-11, USA */

    54     EFCC    = 0x10,

    55     /** Channels 1-13, Europe */

    56     EETSI   = 0x30,

    57     };

    58 

    59 /** Possible WLAN power save modes. */

    60 enum TWlanPowerSaveMode

    61     {

    62     /** Automatic mode, wake-up mode and interval adjusted dynamically. */

    63     EWlanPowerSaveModeAutomatic,

    64     /** Power save is disabled. */

    65     EWlanPowerSaveModeNone,

    66     /** Power save is enabled, wake-up at every beacon. */

    67     EWlanPowerSaveModeBeacon,

    68     /** Power save is enabled, wake-up at every DTIM. */

    69     EWlanPowerSaveModeDtim,

    70     /** Power save is enabled, wake-up at every Nth DTIM, where N is defined by DTIM skipping interval. */

    71     EWlanPowerSaveModeDtimSkipping

    72     };

    73 

    74 /** Defines a structure for storing WLAN packet statistics. */

    75 struct TWlanPacketStatistics

    76     {

    77     /** Number of sent data frames. */

    78     TUint32 txFrames;

    79     /** Number of successfully received data frames. */

    80     TUint32 rxFrames;

    81     /** Number of sent multicast data frames. */

    82     TUint32 txMulticastFrames;

    83     /** Number of successfully received multicast data frames. */

    84     TUint32 rxMulticastFrames;

    85     /** Number of received frames with FCS errors. */

    86     TUint32 fcsErrors;

    87     /** Total number of retransmissions done. */

    88     TUint32 txRetries;

    89     /** Number of data frames that could not be to delivered. */

    90     TUint32 txErrors;

    91     };

    92 

    93 /** Defines the U-APSD settings for the access categories. */

    94 struct TWlanUapsdSettings

    95     {

    96     /** Defines the maximum number of frames to send during a service period. */

    97     TWlanMaxServicePeriodLength maxServicePeriodLength;

    98     /** Whether U-APSD is trigger and delivery-enabled for Voice. */

    99     TBool uapsdForVoice;

   100     /** Whether U-APSD is trigger and delivery-enabled for Video. */

   101     TBool uapsdForVideo;

   102     /** Whether U-APSD is trigger and delivery-enabled for BestEffort. */

   103     TBool uapsdForBestEffort;

   104     /** Whether U-APSD is trigger and delivery-enabled for Background. */

   105     TBool uapsdForBackground;

   106     };

   107 

   108 /** Defines the power save settings for the access categories. */

   109 struct TWlanPowerSaveSettings

   110     {

   111     /** Whether the terminal stays in U-APSD power save when using Voice. */

   112     TBool stayInUapsdPsModeForVoice;

   113     /** Whether the terminal stays in U-APSD power save when using Video. */

   114     TBool stayInUapsdPsModeForVideo;

   115     /** Whether the terminal stays in U-APSD power save when using BestEffort. */

   116     TBool stayInUapsdPsModeForBestEffort;

   117     /** Whether the terminal stays in U-APSD power save when using Background. */

   118     TBool stayInUapsdPsModeForBackground;

   119     /** Whether the terminal stays in legacy power save when using Voice. */

   120     TBool stayInLegacyPsModeForVoice;

   121     /** Whether the terminal stays in legacy power save when using Video. */

   122     TBool stayInLegacyPsModeForVideo;

   123     /** Whether the terminal stays in legacy power save when using BestEffort. */

   124     TBool stayInLegacyPsModeForBestEffort;

   125     /** Whether the terminal stays in legacy power save when using Background. */

   126     TBool stayInLegacyPsModeForBackground;

   127     };

   128 

   129 /**

   130  * Data structure for storing information about an AP.

   131  */

   132 struct TWlanAccessPointInfo

   133     {

   134     /** The SSID of the AP. */

   135     TWlanSsid ssid;

   136     /** The BSSID of the AP. */

   137     TWlanBssid bssid;

   138     /** Capabilities of the AP. */

   139     TUint16 capabilities;

   140     /** The channel AP is on. */

   141     TUint8 channel;

   142     /** Received Signal Strength Indicator (RSSI). */

   143     TUint8 rssi;

   144     /** Basic rates bitmap of the AP. Rates are defined in TWlanRate. */

   145     TUint32 basicRates;

   146     /** Supported rates bitmap of the AP. Rates are defined in TWlanRate. */

   147     TUint32 supportedRates;

   148     /** The security mode of the AP. */

   149     TWlanConnectionExtentedSecurityMode securityMode;

   150     /** Whether Admission Control must be used with Voice. */

   151     TBool isAcRequiredForVoice;

   152     /** Whether Admission Control must be used with Video. */

   153     TBool isAcRequiredForVideo;

   154     /** Whether Admission Control must be used with BestEffort. */

   155     TBool isAcRequiredForBestEffort;

   156     /** Whether Admission Control must be used with Background. */

   157     TBool isAcRequiredForBackground;

   158     /** Whether the AP supports WPX. */

   159     TBool isWpx;

   160     };

   161 

   162 

   163 /**

   164  * Data structure for storing roaming metrics information.

   165  */

   166 struct TWlanRoamMetrics

   167     {

   168     /** Connection attempt total counter. */

   169     TUint32 connectionAttemptTotalCount;

   170     /** Unsuccesfull connection attempt counter. */

   171     TUint32 unsuccesfullConnectionAttemptCount;

   172     /** Roaming counter. */

   173     TUint32 roamingCounter;

   174     /** Coverage loss counter. */

   175     TUint32 coverageLossCount;

   176 

   177     /** The total duration (ms) of the last roaming (= data path broken time + scanning time). */

   178     TUint32 lastRoamTotalDuration;

   179     /** The duration (ms) how long the data path was broken during the last roaming. */

   180     TUint32 lastRoamDataPathBrokenDuration;

   181     /** The cause for the last roaming. */

   182     TWlanRoamReason lastRoamReason;

   183     };

   184 

   185 

   186 /**

   187  * @brief ECom interface definition for WLAN Control API.

   188  *

   189  * This class defines the methods used for...

   190  *

   191  * @since S60 v3.2

   192  */

   193 class MWlanControlInterface

   194     {

   195 

   196 public:

   197 

   198     /**

   199      * Get packet statistics of the current connection.

   200      *

   201      * @since S60 v3.2

   202      * @param aStatistics Packet statistics of the current connection.

   203      * @return KErrNone if statistics were read successfully, an error otherwise.

   204      */

   205     virtual TInt GetPacketStatistics(

   206         TWlanPacketStatistics& aStatistics ) = 0;

   207 

   208     /**

   209      * Clear packet statistics of the current connection.

   210      *

   211      * @since S60 v3.2

   212      */        

   213     virtual void ClearPacketStatistics() = 0;

   214 

   215     /**

   216      * Get the current U-APSD settings.

   217      *

   218      * @since S60 v3.2

   219      * @param aSettings Current U-APSD settings.

   220      * @return KErrNone if settings were read successfully, an error otherwise.

   221      */

   222     virtual TInt GetUapsdSettings(

   223         TWlanUapsdSettings& aSettings ) = 0;

   224 

   225     /**

   226      * Set the U-APSD settings.

   227      *

   228      * @since S60 v3.2

   229      * @param aSettings Current U-APSD settings to be set.

   230      * @return KErrNone if settings were set successfully, an error otherwise.

   231      */

   232     virtual TInt SetUapsdSettings(

   233         const TWlanUapsdSettings& aSettings ) = 0;

   234 

   235     /**

   236      * Get the current power save settings.

   237      *

   238      * @since S60 v3.2

   239      * @param aSettings power save settings.

   240      * @return KErrNone if settings were read successfully, an error otherwise.

   241      */

   242     virtual TInt GetPowerSaveSettings(

   243         TWlanPowerSaveSettings& aSettings ) = 0;

   244 

   245     /**

   246      * Set the power save settings.

   247      *

   248      * @since S60 v3.2

   249      * @param aSettings Current power save settings to be set.

   250      * @return KErrNone if settings were set successfully, an error otherwise.

   251      */      

   252     virtual TInt SetPowerSaveSettings(

   253         const TWlanPowerSaveSettings& aSettings ) = 0;

   254 

   255 

   256     /**

   257      * Get information about the current AP.

   258      *

   259      * @since S60 v3.2

   260      * @param aInfo Information about the current AP.

   261      * @return KErrNone if information is available, an error otherwise.

   262      */

   263     virtual TInt GetAccessPointInfo(

   264         TWlanAccessPointInfo& aInfo ) = 0;

   265 

   266     /**

   267      * Get roam metrics of the current connection.

   268      *

   269      * @since S60 v3.2

   270      * @param aRoamMetrics Roam metrics of the current connection.

   271      * @return KErrNone if settings were read successfully, an error otherwise.

   272      */

   273     virtual TInt GetRoamMetrics(

   274         TWlanRoamMetrics& aRoamMetrics ) = 0;

   275 

   276     /**

   277      * Return a list of BSSIDs on the rogue list.

   278      *

   279      * @since S60 v3.2

   280      * @param aRogueList List of BSSIDs on the rogue list.

   281      * @return KErrNone if list were read successfully, an error otherwise.

   282      */

   283     virtual TInt GetRogueList(

   284         CArrayFixSeg<TWlanBssid>& aRogueList ) = 0;

   285         

   286     /**

   287      * Get the current regulatory domain.

   288      *

   289      * @since S60 v3.2

   290      * @param aRegion current region.

   291      * @return KErrNone if value was read successfully, an error otherwise.

   292      */

   293     virtual TInt GetRegulatoryDomain(

   294         TWlanRegion& aRegion ) = 0;

   295         

   296     /**

   297      * Get the current power save mode.

   298      *

   299      * @since S60 v3.2

   300      * @param aPowerSaveMode current power save mode.

   301      * @return KErrNone if value was read successfully, an error otherwise.

   302      */

   303     virtual TInt GetPowerSaveMode(

   304         TWlanPowerSave& aPowerSaveMode ) = 0;

   305 

   306     /**

   307      * Set the power save mode.

   308      *

   309      * @note This method is meant for overriding the dynamic power save mode selection

   310      *       for testing purposes. Overriding the power save mode may have an adverse

   311      *       effect on throughput and/or power consumption. Dynamic selection can be

   312      *       re-enabled by setting the mode to EWlanPowerSaveModeAutomatic.

   313      *

   314      * @since S60 v5.0.1

   315      * @param aMode Power save mode to be set.

   316      * @return KErrNone if the mode was set successfully, an error otherwise.

   317      */

   318     virtual TInt SetPowerSaveMode(

   319         TWlanPowerSaveMode aMode ) = 0;

   320 

   321     };

   322 

   323 #endif // WLANCONTROLINTERFACE_H