1 /*

     2 * Copyright (c) 2005-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 the License "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:  Interface implemented by core server.

    15 *                Adaptation layer can use core services through this interface.

    16 *

    17 */

    18 

    19 /*

    20 * %version: 30 %

    21 */

    22 

    23 #ifndef ABS_CORE_SERVER_H

    24 #define ABS_CORE_SERVER_H

    25 

    26 #include "am_platform_libraries.h"

    27 #include "core_types.h"

    28 #include "core_type_list.h"

    29 

    30 class ScanList;

    31 

    32 /**

    33  * Abstract core server interface class for WLAN management functionality.

    34  *

    35  * This interface is implemented by the core server and it provides

    36  * methods for the adaptation layer.

    37  *

    38  * @since S60 v3.1

    39  */

    40 class abs_core_server_c

    41     {

    42 

    43 public:

    44 

    45     /**

    46      * Destructor.

    47      */

    48     virtual ~abs_core_server_c() {};

    49 

    50     /**

    51      * Asynchronous methods that the core server will complete by calling

    52      * abs_core_server_callback_c::request_complete.

    53      */

    54 

    55     /**

    56      * Connect to a network.

    57      *

    58      * @since S60 v3.1

    59      * @param request_id An unique identification for the request.

    60      * @param settings The settings used for establishing the connection.

    61      * @param connect_status contains the error code of connection attempt

    62      *        on completion

    63      * @param ssid_list List of possible secondary SSIDs.

    64      */

    65     virtual void connect(

    66         u32_t request_id,

    67         const core_iap_data_s& settings,

    68         core_connect_status_e& connect_status,

    69         core_type_list_c<core_ssid_entry_s>* ssid_list = NULL ) = 0;

    70 

    71     /**

    72      * Disconnect an active connection.

    73      * 

    74      * @since S60 v3.1

    75      * @param request_id An unique identification for the request.

    76      */

    77     virtual void release(

    78         u32_t request_id ) = 0;

    79 

    80     /**

    81      * Request available networks with the given SSID.

    82      * 

    83      * @since S60 v3.1

    84      * @param request_id An unique identification for the request.

    85      * @param scan_mode Defines whether active or passive scan is performed.

    86      * @param scan_ssid Name of the network to scan for.

    87      * @param scan_channels Channels to scan.

    88      * @param scan_data Scan results are stored here.

    89      * @param scan_max_age Maximum age of returned scan results in seconds.

    90      * @param is_current_ap_added Whether the current AP needs to be added during an ongoing

    91      *                            connection if not otherwise found in the scan.

    92      * @note If the length of the SSID is zero, a broadcast scan is performed.

    93      */

    94     virtual void get_scan_result(

    95         u32_t request_id,

    96         core_scan_mode_e scan_mode,

    97         const core_ssid_s& scan_ssid,

    98         const core_scan_channels_s& scan_channels,

    99         u8_t scan_max_age,

   100         ScanList& scan_data,

   101         bool_t is_current_ap_added = true_t ) = 0;

   102 

   103     /**

   104      * Find which iaps from the given list are currently available.

   105      * @since S60 v3.1

   106      * @param request_id An unique identification for the request.

   107      * @param is_active_scan_allowed specifies whether active scanning is allowed.

   108      * @param iap_data_list containing list of iap data structures.

   109      * @param iap_id_list list of iap ids are stored here on completion.

   110      * @param iap_ssid_list List of possible secondary SSIDs.

   111      * @param scan_data contains the scan results

   112      */

   113     virtual void get_available_iaps(

   114         u32_t request_id,

   115         bool_t is_active_scan_allowed,

   116         core_type_list_c<core_iap_data_s>& iap_data_list,

   117         core_type_list_c<u32_t>& iap_id_list,

   118         core_type_list_c<core_ssid_entry_s>* iap_ssid_list,

   119         ScanList& scan_data ) = 0;

   120 

   121     /**

   122      * Get the current RCPI value of the connection.

   123      * 

   124      * @since S60 v3.1

   125      * @param request_id An unique identification for the request.

   126      * @param rcpi Current channel power indicator (RCPI).

   127      */

   128     virtual void get_current_rcpi(

   129         u32_t request_id,

   130         u32_t& rcpi ) = 0;

   131 

   132     /**

   133      * Disable all WLAN activity.

   134      *

   135      * Disconnects the active connection and prevents any further

   136      * WLAN activity until enable_wlan() is called.

   137      *

   138      * @since S60 v3.1

   139      * @param request_id An unique identification for the request.

   140      */        

   141     virtual void disable_wlan(

   142         u32_t request_id ) = 0;

   143         

   144     /**

   145      * Allow WLAN activity after disabled_wlan().

   146      *

   147      * @since S60 v3.1     

   148      * @param request_id An unique identification for the request.

   149      */

   150     virtual void enable_wlan(

   151         u32_t request_id ) = 0;

   152 

   153     /**

   154      * Get packet statistics of the current connection.

   155      *

   156      * @since S60 v3.2

   157      * @param request_id An unique identification for the request.

   158      * @param statistics Packet statistics of the current connection.     

   159      */

   160     virtual void get_packet_statistics(

   161         u32_t request_id,

   162         core_packet_statistics_s& statistics ) = 0;

   163 

   164     /**

   165      * Request creation of a virtual traffic stream.

   166      *

   167      * @since S60 v3.2

   168      * @param request_id An unique identification for the request.

   169      * @param tid TID of the virtual traffic stream.

   170      * @param user_priority User Priority of the virtual traffic stream.

   171      * @param is_automatic_stream Whether the virtual traffic stream

   172      *                            has been created automatically.

   173      * @param params Parameters of the virtual traffic stream.

   174      * @param stream_id ID assigned to this virtual traffic stream on

   175      *                  successful completion.

   176      * @param stream_status Status of the virtual traffic stream on

   177      *                      successful completion. 

   178      * @note If the TID has been defined as TRAFFIC_STREAM_ID_NONE,

   179      *       core server will select the next free ID.

   180      */

   181     virtual void create_traffic_stream(

   182         u32_t request_id,

   183         u8_t tid,

   184         u8_t user_priority,

   185         bool_t is_automatic_stream,

   186         const core_traffic_stream_params_s& params,

   187         u32_t& stream_id,

   188         core_traffic_stream_status_e& stream_status ) = 0;

   189 

   190     /**

   191      * Request deletion of a virtual traffic stream.

   192      *

   193      * @since S60 v3.2

   194      * @param request_id An unique identification for the request.

   195      * @param stream_id ID of the virtual traffic stream.

   196      */

   197     virtual void delete_traffic_stream(

   198         u32_t request_id,

   199         u32_t stream_id ) = 0;

   200 

   201     /**

   202      * Start Protected Setup.

   203      * 

   204      * @since S60 v3.2

   205      * @param request_id An unique identification for the request.

   206      * @param iap_data IAP data used for running Protected Setup.

   207      * @param iap_data_list IAP data results from a successful Protected Setup operation.

   208      * @param protected_setup_status contains the error code of Protected Setup attempt

   209      *        on completion.

   210      */

   211     virtual void run_protected_setup(

   212         u32_t request_id,

   213         const core_iap_data_s& iap_data,

   214         core_type_list_c<core_iap_data_s>& iap_data_list,

   215         core_protected_setup_status_e& protected_setup_status ) = 0;

   216 

   217     /**

   218      * Initiate a roam to the given BSSID.

   219      * 

   220      * @since S60 v3.2

   221      * @param request_id An unique identification for the request.

   222      * @param bssid BSSID to roam to. If BSSID is set to BROADCAST_MAC_ADDR,

   223      *              search for a better BSS is initiated.

   224      * @note This method does not guarantee that the a roam to the given BSSID

   225      *       will occur. If the roam succeeds, the request will be completed

   226      *       with core_error_ok, otherwise with an error code.  

   227      */

   228     virtual void directed_roam(

   229         u32_t request_id,

   230         const core_mac_address_s& bssid ) = 0;

   231 

   232     /**

   233      * Synchronous methods.

   234      */

   235     

   236     /**

   237      * Get the BSSID of the access point currently connected to.

   238      * 

   239      * @since S60 v3.1

   240      * @param bssid BSSID of the access point.

   241      * @return core_error_ok if success, an error code otherwise.

   242      */

   243     virtual core_error_e get_current_bssid(

   244         core_mac_address_s& bssid ) = 0;

   245 

   246     /**

   247      * Get the name of the network (SSID) currently connected to.

   248      * 

   249      * @since S60 v3.1

   250      * @param ssid Current SSID.

   251      * @return core_error_ok if success, an error code otherwise.

   252      */

   253     virtual core_error_e get_current_ssid(

   254         core_ssid_s& ssid ) = 0;

   255 

   256     /**

   257      * Get the current security mode of the connection.

   258      * 

   259      * @since S60 v3.1

   260      * @param mode Current security mode.

   261      * @return core_error_ok if success, an error code otherwise.

   262      */

   263     virtual core_error_e get_current_security_mode(

   264         core_connection_security_mode_e& mode ) = 0;

   265 

   266     /**

   267      * Get the current connection state.

   268      * 

   269      * @since S60 v3.1

   270      * @param state Current connection state.

   271      * @return core_error_ok if success, an error code otherwise.

   272      */

   273     virtual core_error_e get_current_connection_state(

   274         core_connection_state_e& state ) = 0;

   275 

   276     /**

   277      * Inform core server about updated device settings.

   278      * 

   279      * @since S60 v3.1     

   280      * @param settings Updated device settings.

   281      * @return core_error_ok if success, an error code otherwise.

   282      * @note This method does not guarantee that the new parameters

   283      *       are taken into use immediately.

   284      */

   285     virtual core_error_e update_device_settings(

   286         core_device_settings_s& settings ) = 0;

   287 

   288     /**

   289      * Set the preferred power save mode.

   290      * 

   291      * @since S60 v3.1

   292      * @param mode Preferred power save mode.

   293      * @return core_error_ok if success, an error code otherwise.

   294      * @note This method does not guarantee that the new parameters

   295      *       are taken into use immediately.

   296      */

   297     virtual core_error_e set_power_save_mode(

   298         const core_power_save_mode_s& mode ) = 0;

   299 

   300     /**

   301      * Add a BSSID to the rogue list.

   302      *

   303      * Prevents roaming to the given BSSID and hides it from

   304      * the scan results.

   305      *

   306      * @since S60 v3.1

   307      * @param bssid BSSID to add to the list.

   308      * @return core_error_ok if success, an error code otherwise.

   309      * @note The list entry will be persistent, meaning it will not

   310      *       be cleared when the connection is closed.

   311      */

   312     virtual core_error_e add_bssid_to_rogue_list(

   313         const core_mac_address_s& bssid ) = 0;

   314 

   315     /**

   316      * Remove a BSSID from the rogue list.

   317      *

   318      * @since S60 v3.1

   319      * @param bssid BSSID to remove from the list.

   320      * @return core_error_ok if success, an error code otherwise.

   321      */

   322     virtual core_error_e remove_bssid_from_rogue_list(

   323         const core_mac_address_s& bssid ) = 0;

   324 

   325     /**

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

   327      *

   328      * @since S60 v3.2

   329      * @param rogue_list List of BSSIDs on the rogue list.

   330      * @return core_error_ok if success, an error code otherwise.

   331      */

   332     virtual core_error_e get_rogue_list(

   333         core_type_list_c<core_mac_address_s>& rogue_list ) = 0;

   334 

   335     /**

   336      * Set the RCP level notification boundary.

   337      *

   338      * When the signal strength is getting worse (RCPI value is getting smaller),

   339      * the core server will indicate core_notification_e::core_notification_rcp_changed

   340      * when the RCPI value gets smaller than the the rcp_level_boundary value.

   341      *

   342      * When the signal strength is getting better, the core server will indicate

   343      * core_notification_e::core_notification_rcp_changed when the RCPI value

   344      * gets bigger than the combined value of rcp_level_boundary and hysteresis.

   345      *

   346      * @since S60 v3.1

   347      * @param rcp_level_boundary RCP level notification boundary.

   348      * @param hysteresis Specifies the difference between boundaries when 

   349      *        the RCP level is rising vs. descending

   350      * @return core_error_ok if success, an error code otherwise.

   351      */

   352     virtual core_error_e set_rcp_level_notification_boundary(

   353         const i32_t rcp_level_boundary,

   354         const i32_t hysteresis ) = 0;

   355 

   356     /**

   357      * Clear packet statistics of the current connection.

   358      *

   359      * @since S60 v3.2

   360      * @return core_error_ok if success, an error code otherwise.

   361      */

   362     virtual core_error_e clear_packet_statistics() = 0;

   363 

   364     /**

   365      * Get the current U-APSD settings.

   366      *

   367      * @since S60 v3.2

   368      * @param settings Current U-APSD settings.

   369      * @return core_error_ok if success, an error code otherwise.

   370      */

   371     virtual core_error_e get_uapsd_settings(

   372         core_uapsd_settings_s& settings ) = 0;

   373 

   374     /**

   375      * Set the U-APSD settings.

   376      *

   377      * @since S60 v3.2

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

   379      * @return core_error_ok if success, an error code otherwise.

   380      * @note This method does not guarantee that the new parameters

   381      *       are taken into use immediately.

   382      */

   383     virtual core_error_e set_uapsd_settings(

   384         const core_uapsd_settings_s& settings ) = 0;

   385 

   386     /**

   387      * Get the current power save settings.

   388      *

   389      * @since S60 v3.2

   390      * @param settings Current power save settings.

   391      * @return core_error_ok if success, an error code otherwise.

   392      */

   393     virtual core_error_e get_power_save_settings(

   394         core_power_save_settings_s& settings ) = 0;

   395 

   396     /**

   397      * Set the power save settings.

   398      *

   399      * @since S60 v3.2

   400      * @param settings Current power save settings to be set.

   401      * @return core_error_ok if success, an error code otherwise.

   402      * @note This method does not guarantee that the new parameters

   403      *       are taken into use immediately.

   404      */

   405     virtual core_error_e set_power_save_settings(

   406         const core_power_save_settings_s& settings ) = 0;

   407 

   408     /**

   409      * Get information about the current AP.

   410      *

   411      * @since S60 v3.2

   412      * @param info Information about the current AP.

   413      * @return core_error_ok if success, an error code otherwise.

   414      */

   415     virtual core_error_e get_current_ap_info(

   416         core_ap_information_s& info ) = 0;

   417 

   418     /**

   419      * Get roam metrics of the current connection.

   420      *

   421      * @since S60 v3.2

   422      * @param roam_metrics Roam metrics of the current connection.

   423      */

   424     virtual void get_roam_metrics(

   425         core_roam_metrics_s& roam_metrics ) = 0;

   426 

   427     /**

   428      * Set the arp filter.

   429      *

   430      * @since S60 v5.0

   431      * @param filter Current ARP filter to be set.

   432      * @return core_error_ok if success, an error code otherwise.

   433      * @note This method does not guarantee that the new filter

   434      *       is taken into use immediately.

   435      */

   436     virtual core_error_e set_arp_filter(

   437         const core_arp_filter_s& filter ) = 0;

   438 

   439     /**

   440      * Delivers multicast MAC address to drivers.

   441      *

   442      * @since S60 v3.1

   443      * @param join_group is set true_t if adding a multicast address

   444      *        otherwise the address will be removed.

   445      * @param multicast_addr contains the MAC address to add/remove

   446      * @return core_error_ok if success, an error code otherwise.

   447      * @note This method does not guarantee that the new address

   448      *       is taken into use immediately.

   449      */

   450     virtual core_error_e configure_multicast_group(

   451         bool_t join_group,

   452         const core_mac_address_s& multicast_addr ) = 0;

   453 

   454     /**

   455      * Get information about current traffic statuses and traffic modes for

   456      * access classes.

   457      *

   458      * @since S60 v3.2

   459      * @param info Information about the current traffic statuses and traffic modes.

   460      * @return core_error_ok if success, an error code otherwise.

   461      */

   462     virtual core_error_e get_current_ac_traffic_info(

   463         core_ac_traffic_information_s& info ) = 0;

   464 

   465     /**

   466      * Schedule an immediate driver unload.

   467      *

   468      * @since S60 v3.1     

   469      * @return core_error_ok if success, an error code otherwise.

   470      */

   471     virtual core_error_e unload_drivers() = 0;

   472 

   473     /**

   474      * An asynchronous request from the core server has been completed.

   475      *

   476      * @since S60 v3.1

   477      * @param request_id Identification of the corresponding request.

   478      * @param status Completion status of the request.

   479      */

   480     virtual void request_complete(

   481         u32_t request_id,

   482         core_error_e status ) = 0;

   483 

   484     /**

   485      * Cancel a pending asynchronous request.

   486      * 

   487      * @since S60 v3.1

   488      * @param request_id Identification of the corresponding request.

   489      */

   490     virtual void cancel_request(

   491         u32_t request_id ) = 0;

   492 

   493     };

   494 

   495 #endif // ABS_CORE_SERVER_H