1 /*

     2 * Copyright (c) 2002-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 management services.

    15 *

    16 */

    17 

    18 /*

    19 * %version: 15 %

    20 */

    21 

    22 #ifndef WLANMGMTINTERFACE_H

    23 #define WLANMGMTINTERFACE_H

    24 

    25 // INCLUDES

    26 #include "wlanmgmtcommon.h"

    27 #include "wlanscaninfo.h"

    28 #include "wlantrafficstreamparameters.h"

    29 

    30 // CLASS DECLARATION

    31 /**

    32  * ECom interface class for WLAN management services.

    33  *

    34  * This class contains the methods for managing WLAN connections

    35  * and querying the statuses of various connection variables.

    36  *

    37  * @since Series 60 3.0

    38  */

    39 class MWlanMgmtInterface

    40     {

    41     public:

    42 

    43         /**

    44          * Activate the notification service.

    45          * 

    46          * After the client has enabled the notification service, it can

    47          * receive asynchronous notifications from the server.

    48          *

    49          * @param aCallback The class that implements the callback interface.

    50          * @note This method only activates notifications defined in callback interface v1.

    51          * @see ActivateExtendedNotificationsL

    52          */

    53         virtual void ActivateNotificationsL(

    54             MWlanMgmtNotifications& aCallback ) = 0;

    55         

    56         /**

    57          * Cancel the notification service.

    58          */

    59         virtual void CancelNotifications() = 0;

    60 

    61         /**

    62          * Perform a broadcast scan and return the detected WLAN networks.

    63          *

    64          * @param aResults Results of the scan.

    65          * @return KErrNone if successful, otherwise one of the system-wide

    66          *         error codes.

    67          */

    68         virtual TInt GetScanResults(

    69             CWlanScanInfo& aResults ) = 0;

    70 

    71         /**

    72          * Perform a broadcast scan and return the detected WLAN networks.

    73          *

    74          * @param aStatus Status of the calling active object. On successful

    75          *                completion contains KErrNone, otherwise one of the

    76          *                system-wide error codes.

    77          * @param aResults Results of the scan.

    78          */

    79         virtual void GetScanResults(

    80             TRequestStatus& aStatus,

    81             CWlanScanInfo& aResults ) = 0;

    82 

    83         /**

    84          * Get the BSSID of the BSS currently connected to.

    85          *

    86          * @remark This method can only be used while successfully connected to

    87          *         a WLAN network.

    88          * @param aBssid BSSID of the currently connected BSS.

    89          * @return KErrNone if successful, otherwise one of the system-wide

    90          *         error codes.

    91          */

    92         virtual TInt GetConnectionBssid(

    93             TWlanBssid& aBssid ) = 0;

    94 

    95         /**

    96          * Get the SSID of the WLAN network currently connected to.

    97          *

    98          * @remark This method can only be used while successfully connected to

    99          *         a WLAN network.

   100          * @param aSsid SSID of the currently connected network.

   101          * @return KErrNone if successful, otherwise one of the system-wide

   102          *         error codes.

   103          */

   104         virtual TInt GetConnectionSsid(

   105             TWlanSsid& aSsid ) = 0;

   106 

   107         /**

   108          * Get the current Received Signal Strength Indicator (RSSI).

   109          *

   110          * @remark This method can only be used while successfully connected to

   111          *         a WLAN network.

   112          * @param aSignalQuality Current RSSI.

   113          * @return KErrNone if successful, otherwise one of the system-wide

   114          *         error codes.

   115          */

   116         virtual TInt GetConnectionSignalQuality(

   117             TInt32& aSignalQuality ) = 0;

   118 

   119         /**

   120          * Get the mode of the WLAN connection.

   121          *

   122          * @param aMode The current mode of the connection.

   123          * @return KErrNone if successful, otherwise one of the system-wide

   124          *         error codes.

   125          */

   126         virtual TInt GetConnectionMode(

   127             TWlanConnectionMode& aMode ) = 0;

   128 

   129         /**

   130          * Get the currently used security mode of the WLAN connection.

   131          *

   132          * @remark This method can only be used while successfully connected to

   133          *         a WLAN network.

   134          * @param aMode The security mode of the connection.

   135          * @return KErrNone if successful, otherwise one of the system-wide

   136          *         error codes.

   137          * @deprecated This method is offered for backward compatibility reasons,

   138          *             GetExtendedConnectionSecurityMode() should be used instead.

   139          */

   140         virtual TInt GetConnectionSecurityMode(

   141             TWlanConnectionSecurityMode& aMode ) = 0;

   142         

   143         /**

   144          * Get the available WLAN IAPs.

   145          *

   146          * @param aAvailableIaps Array of IAP IDs available.

   147          * @return KErrNone if successful, otherwise one of the system-wide

   148          *         error codes.

   149          */

   150         virtual TInt GetAvailableIaps(

   151             RArray<TUint>& aAvailableIaps ) = 0;

   152         

   153         /**

   154          * Get the available WLAN IAPs.

   155          *

   156          * @param aStatus Status of the calling active object. On successful

   157          *                completion contains KErrNone, otherwise one of the

   158          *                system-wide error codes.       

   159          * @param aAvailableIaps Array of IAP IDs available.

   160          */

   161         virtual void GetAvailableIaps(

   162             TRequestStatus& aStatus,

   163             RArray<TUint>& aAvailableIaps ) = 0;

   164 

   165         /**

   166          * Notify the server about changed WLAN settings.

   167          */

   168         virtual void NotifyChangedSettings() = 0;

   169 

   170         /**

   171          * Adds a bssid to the blacklist

   172          *

   173          * @param aBssid The BSSID of the accesspoint.

   174          * @return KErrNone if successful, otherwise one of the system-wide

   175          *         error codes.

   176          */

   177         virtual TInt AddBssidToBlacklist(

   178             const TWlanBssid& aBssid ) = 0;

   179 

   180         /**

   181          * Updates the RSS notification class boundaries.

   182          *

   183          * @param aRssLevelBoundary Specifies the RSS level when a signal level notification

   184          *                          should be given. This boundary is used when signal level

   185          *                          is getting worse (see next parameter).

   186          * @param aHysteresis Specifies the difference between RSS notification trigger levels

   187          *                    of declining and improving signal quality, i.e. since aRssLevelBoundary

   188          *                    specifies the level boundary for declining signal, the same boundary

   189          *                    for improving signal is ( aRssLevelBoundary - aHysteresis ).

   190          * @return KErrNone if successful, otherwise one of the system-wide

   191          *         error codes.

   192          */

   193         virtual TInt UpdateRssNotificationBoundary( 

   194             const TInt32 aRssLevelBoundary,

   195             const TInt32 aHysteresis ) = 0;

   196 

   197         /**

   198          * Perform a direct scan for an SSID and return the detected WLAN networks.

   199          * If the SSID has zero length, a broadcast scan will be done.

   200          *

   201          * @param aSsid name of the WLAN network

   202          * @param aStatus Status of the calling active object. On successful

   203          *                completion contains KErrNone, otherwise one of the

   204          *                system-wide error codes.

   205          * @param aResults Results of the scan.

   206          */

   207         virtual void GetScanResults(

   208             TWlanSsid& aSsid,

   209             TRequestStatus& aStatus,

   210             CWlanScanInfo& aResults ) = 0;

   211         

   212         /**

   213          * Start Protected Setup.

   214          *

   215          * @param aStatus Status of the calling active object. On successful

   216          *                completion contains KErrNone, otherwise one of the

   217          *                system-wide error codes.

   218          * @param aId Service ID of network which user has selected to be configured.

   219          * @param aCredentials Results of a successful Protected Setup operation.

   220          * @sa \link psetup Protected Setup-specific error codes \endlink.

   221          */

   222         virtual void RunProtectedSetup(

   223             TRequestStatus& aStatus,

   224             TUint32 aId,

   225             CArrayFixSeg<TWlanProtectedSetupCredentialAttribute>& aCredentials ) = 0;

   226 

   227         /**

   228          * Cancel an outstanding Protected Setup operation.

   229          */

   230         virtual void CancelProtectedSetup() = 0;

   231 

   232         /**

   233          * Cancel an outstanding scan request.

   234          */

   235         virtual void CancelGetScanResults() = 0;

   236 

   237         /**

   238          * Cancel an outstanding IAP availability request.

   239          */

   240         virtual void CancelGetAvailableIaps() = 0;

   241 

   242         /**

   243          * Perform a direct scan for an SSID and return the detected WLAN networks.

   244          * If the SSID has zero length, a broadcast scan will be done.

   245          *

   246          * @param aCacheLifetime Defines how many seconds old cached results the client

   247          *                       is willing to accept. The valid is range is from 0 to

   248          *                       60 seconds. The value of -1 means the system default will

   249          *                       be used. The aCacheLifetime parameter has a meaning only

   250          *                       when the aMaxDelay parameter is zero.

   251          *                       Value will be changed to the actual value used by the

   252          *                       system.

   253          * @param aMaxDelay Maximum amount of seconds the client is willing to wait for

   254          *                  the scan results. The valid range is from 0 to 1200 seconds

   255          *                  or KWlanInfiniteScanDelay. KWlanInfiniteScanDelay

   256          *                  will never cause a scan, but the request will be

   257          *                  completed when any other broadcast scan request is completed.

   258          *                  Value will be changed to the actual value used by the system.

   259          * @param aSsid Name of the WLAN network.

   260          * @param aStatus Status of the calling active object. On successful

   261          *                completion contains KErrNone, otherwise one of the

   262          *                system-wide error codes.

   263          * @param aResults Results of the scan.

   264          */

   265         virtual void GetScanResults(

   266             TInt& aCacheLifetime,

   267             TUint& aMaxDelay,

   268             TWlanSsid& aSsid,

   269             TRequestStatus& aStatus,

   270             CWlanScanInfo& aResults ) = 0;

   271 

   272         /**

   273          * Get the available WLAN IAPs.

   274          *

   275          * @param aCacheLifetime Defines how many seconds old cached results the client

   276          *                       is willing to accept. The valid is range is from 0 to

   277          *                       60 seconds. The value of -1 means the system default will

   278          *                       be used. The aCacheLifetime parameter has a meaning only

   279          *                       when the aMaxDelay parameter is zero.

   280          *                       Value will be changed to the actual value used by the

   281          *                       system.

   282          * @param aMaxDelay Maximum amount of seconds the client is willing to wait for

   283          *                  the availability results. The valid range is from 0 to 1200

   284          *                  seconds or KWlanInfiniteScanDelay. KWlanInfiniteScanDelay

   285          *                  will never cause a scan, but the request will be

   286          *                  completed when any other broadcast scan request is completed.

   287          *                  Value will be changed to the actual value used by the system.

   288          * @param aStatus Status of the calling active object. On successful

   289          *                completion contains KErrNone, otherwise one of the

   290          *                system-wide error codes.

   291          * @param aAvailableIaps Array of IAP IDs available.

   292          */

   293         virtual void GetAvailableIaps(

   294             TInt& aCacheLifetime,

   295             TUint& aMaxDelay,

   296             TRequestStatus& aStatus,

   297             RArray<TUint>& aAvailableIaps ) = 0;

   298 

   299         /**

   300          * Add a list of SSIDs to the given IAP ID.

   301          *

   302          * The list of SSIDs is matched against the scan results during IAP availability

   303          * check and the corresponding IAP marked as available if a match is found.

   304          *

   305          * @param aIapId IAP ID the list is attached to.

   306          * @param aSsidList List of SSIDs. Any previous list attached will be overwritten.

   307          * @return KErrNone if the list was successfully added, an error code otherwise.

   308          */

   309         virtual TInt AddIapSsidList(

   310             TUint aIapId,

   311             const CArrayFixFlat<TWlanSsid>& aSsidList ) = 0;

   312 

   313         /**

   314          * Remove any list of SSIDs attached to the given IAP ID.

   315          *

   316          * @param aIapId IAP ID the list is attached to.

   317          * @return KErrNone if the list was successfully removed, an error code otherwise.

   318          */

   319         virtual TInt RemoveIapSsidList(

   320             TUint aIapId ) = 0;

   321 

   322         /**

   323          * Get the currently used security mode of the WLAN connection.

   324          *

   325          * @remark This method can only be used while successfully connected to

   326          *         a WLAN network.

   327          * @param aMode The security mode of the connection.

   328          * @return KErrNone if successful, otherwise one of the system-wide

   329          *         error codes.

   330          */

   331         virtual TInt GetExtendedConnectionSecurityMode(

   332             TWlanConnectionExtentedSecurityMode& aMode ) = 0;

   333 

   334         /**

   335          * Activate the extended notification service.

   336          * 

   337          * After the client has enabled the notification service, it can

   338          * receive asynchronous notifications from the server.

   339          *

   340          * @param aCallback The class that implements the callback interface.

   341          * @param aCallbackInterfaceVersion The callback interface version implemented by

   342          *                                  the client. This MUST NOT be touched.

   343          */

   344         virtual void ActivateExtendedNotificationsL(

   345             MWlanMgmtNotifications& aCallback,

   346             TUint aCallbackInterfaceVersion = KWlanCallbackInterfaceVersion ) = 0;

   347 

   348         /**

   349          * Create a virtual traffic stream.

   350          *

   351          * @param aStatus Status of the calling active object. On successful

   352          *                completion contains KErrNone, otherwise one of the

   353          *                system-wide error codes.

   354          * @param aStreamParameters Traffic stream parameters to use.

   355          * @param aStreamId Contains the ID assigned to this traffic stream

   356          *                  on successful completion.

   357          * @param aStreamStatus Contains the status of the traffic stream

   358          *                  on successful completion.

   359          */

   360         virtual void CreateTrafficStream(

   361             TRequestStatus& aStatus,

   362             const TWlanTrafficStreamParameters& aStreamParameters,

   363             TUint& aStreamId,

   364             TWlanTrafficStreamStatus& aStreamStatus ) = 0;

   365 

   366         /**

   367          * Cancel an outstanding traffic stream creation request.

   368          */

   369         virtual void CancelCreateTrafficStream() = 0;

   370 

   371         /**

   372          * Delete a virtual traffic stream.

   373          *

   374          * @param aStatus Status of the calling active object. On successful

   375          *                completion contains KErrNone, otherwise one of the

   376          *                system-wide error codes.

   377          * @param aStreamId ID of the traffic stream to delete.

   378          */

   379         virtual void DeleteTrafficStream(

   380             TRequestStatus& aStatus,

   381             TUint aStreamId ) = 0;

   382 

   383         /**

   384          * Cancel an outstanding traffic stream deletion request.

   385          */

   386         virtual void CancelDeleteTrafficStream() = 0;

   387 

   388         /**

   389          * Initiate a roam to the given BSSID.

   390          *

   391          * @param aStatus Status of the calling active object. On successful

   392          *                completion contains KErrNone, otherwise one of the

   393          *                system-wide error codes.

   394          * @param aBssid BSSID to roam to. If set to FF:FF:FF:FF:FF:FF address,

   395          *               search for a better BSS is initiated.

   396          */

   397         virtual void DirectedRoam(

   398             TRequestStatus& aStatus,

   399             const TWlanBssid& aBssid ) = 0;

   400 

   401         /**

   402          * Cancel an outstanding directed roam request.

   403          */

   404         virtual void CancelDirectedRoam() = 0;

   405 

   406     };

   407 

   408 #endif // WLANMGMTINTERFACE_H

   409             

   410 // End of File