Wifiservice

    You can use this module to enable and disable the Wi-Fi station or hotspot mode, connect to and disconnect from a station or hotspot, query the station or hotspot status, and listen for events.

    Since:

    1.0

    Version:

    1.0

    Summary

    Files

    Data Structures

    Data Structure Name

    Description

    Represents the station information.

    WifiDeviceConfig

    Represents the Wi-Fi station configuration used to connect to a specified Wi-Fi device.

    Represents the Wi-Fi station configuration used to connect to a specified Wi-Fi device.

    WifiEvent

    Represents the pointer to a Wi-Fi event callback for station and hotspot connection, disconnection, or scan.

    Represents the hotspot configuration.

    WifiLinkedInfo

    Represents the Wi-Fi connection information.

    Represents the Wi-Fi scan result information.

    Macros

    Macro Name and Value

    Description

    WIFI_MAX_CONFIG_SIZE   10

    Indicates the maximum number of Wi-Fi station configurations that can be added using .

    WIFI_CONFIG_INVALID   (-1)

    Indicates the value of networkId when the configuration file is unavailable.

       33

    Indicates the maximum length of a Wi-Fi SSID.

    WIFI_MAX_KEY_LEN   65

    Indicates the maximum length of a Wi-Fi key.

       6

    Indicates the maximum length of a Wi-Fi MAC address or a Wi-Fi BSSID.

    WIFI_PSK_LEN   32

    Indicates the maximum length of a Wi-Fi PSK.

       1

    Indicates that the Wi-Fi station mode is enabled.

    WIFI_STA_NOT_ACTIVE   0

    Indicates that the Wi-Fi station mode is disabled.

       1

    Indicates that the Wi-Fi hotspot mode is enabled.

    WIFI_HOTSPOT_NOT_ACTIVE   0

    Indicates that the Wi-Fi hotspot mode is disabled.

       10

    Indicates the maximum number of event listeners that can be registered using RegisterWifiEvent.

    HOTSPOT_DEFAULT_CHANNEL    6

    Defines the default channel of the hotspot mode.

    WIFI_MAX_STA_NUM    6

    Defines the maximum number of stations connected to a hotspot.

    WIFI_SCAN_HOTSPOT_LIMIT    64

    Indicates the maximum number of hotspots that can be detected in a Wi-Fi scan.

    Typedefs

    Typedef Name

    Description

    typedef struct WifiDeviceConfig 

    Represents the Wi-Fi station configuration used to connect to a specified Wi-Fi device.

    Enumerations

    Enumeration Name

    Description

    {   WIFI_SEC_TYPE_INVALID = -1, , WIFI_SEC_TYPE_WEP, ,   WIFI_SEC_TYPE_SAE }

    Enumerates Wi-Fi security types.

    { WIFI_PSK_TYPE_ASCII = 0, }

    Enumerates psk encryption types.

    WifiScanType { , WIFI_SSID_SCAN, , WIFI_BAND_SCAN }

    Enumerates Wi-Fi scan types.

    {   WIFI_SUCCESS = 0, = -1, ERROR_WIFI_CHIP_INVALID = -2, = -3,   ERROR_WIFI_RTT_CONTROLLER_INVALID = -4, = -5, ERROR_WIFI_NOT_AVAILABLE = -6, = -7,   ERROR_WIFI_BUSY = -8, = -9 }

    Enumerates Wi-Fi error codes.

    WifiEventState { = 0, WIFI_STATE_AVALIABLE }

    Enumerates states in Wi-Fi events.

    { RSSI_LEVEL_1 = 1, = 2, RSSI_LEVEL_3 = 3, = 4 }

    Enumerates received signal strength indicator (RSSI) levels.

    HotspotBandType { = 1, HOTSPOT_BAND_TYPE_5G = 2 }

    Enumerates frequency bands supported by the Wi-Fi hotspot mode.

    { WIFI_DISCONNECTED, }

    Enumerates Wi-Fi connection states.

    Functions

    Function Name

    Description

    EnableWifi (void)

     

    Enables the station mode.

    DisableWifi (void)

     

    Disables the station mode.

    IsWifiActive (void)

    int 

    Checks whether the station mode is enabled.

    (void)

    WifiErrorCode 

    Starts a Wi-Fi scan.

    (WifiScanInfo result, unsigned int size)

     

    Obtains an array of hotspots detected in a Wi-Fi scan.

    AddDeviceConfig (const config, int result)

    WifiErrorCode 

    Adds a specified hotspot configuration for connecting to a hotspot.

    (WifiDeviceConfig result, unsigned int size)

     

    Obtains all hotspot configurations.

    RemoveDevice (int networkId)

     

    Removes a hotspot configuration matching a specified networkId.

    ConnectTo (int networkId)

     

    Connects to a hotspot matching a specified networkId.

    Disconnect (void)

     

    Disconnects this Wi-Fi connection.

    GetLinkedInfo ( result)

    WifiErrorCode 

    Obtains information about the connected hotspot.

    (WifiEvent event)

     

    Registers a callback for a specified Wi-Fi event.

    UnRegisterWifiEvent (const event)

    WifiErrorCode 

    Unregisters a callback previously registered for a specified Wi-Fi event.

    (unsigned char result)

    WifiErrorCode 

    Obtains the MAC address of this device.

    (WifiScanParams params)

     

    Starts a Wi-Fi scan based on a specified parameter.

    EnableHotspot (void)

    Enables the hotspot mode.

    (void)

    WifiErrorCode 

    Disables the hotspot mode.

    (const HotspotConfig config)

     

    Sets a specified hotspot configuration.

    GetHotspotConfig ( result)

    WifiErrorCode 

    Obtains a specified hotspot configuration.

    (void)

    int 

    Checks whether the hotspot mode is enabled.

    GetStationList ( result, unsigned int size)

    WifiErrorCode 

    Obtains an array of stations connected to this hotspot.

    (int rssi, int band)

    int 

    Obtains the signal level indicated by a specified received signal strength indicator (RSSI) and frequency band.

    SetBand (int band)

     

    Sets the frequency band for this hotspot.

    GetBand (int result)

     

    Obtains the frequency band of this hotspot.

    Details

    Macro Definition Documentation

    WIFI_CONFIG_INVALID

    Description:

    Indicates the value of networkId when the configuration file is unavailable.

    Generally, the configuration file is unavailable because the configuration matching the networkId is uninitialized.

    WIFI_HOTSPOT_ACTIVE

    Description:

    Indicates that the Wi-Fi hotspot mode is enabled.

    WIFI_HOTSPOT_NOT_ACTIVE

    1. #define WIFI_HOTSPOT_NOT_ACTIVE   0

    Description:

    Indicates that the Wi-Fi hotspot mode is disabled.

    WIFI_MAC_LEN

    1. #define WIFI_MAC_LEN   6

    Description:

    Indicates the maximum length of a Wi-Fi MAC address or a Wi-Fi BSSID.

    WIFI_MAX_CONFIG_SIZE

    1. #define WIFI_MAX_CONFIG_SIZE   10

    Description:

    Indicates the maximum number of Wi-Fi station configurations that can be added using .

    If the maximum number is reached, an error will be returned. In this case, you must delete at least one configuration before you can add new ones.

    WIFI_MAX_EVENT_SIZE

    1. #define WIFI_MAX_EVENT_SIZE   10

    Description:

    Indicates the maximum number of event listeners that can be registered using .

    When the maximum number is reached, you need to unregister at least one listener before registering new ones.

    WIFI_MAX_KEY_LEN

    1. #define WIFI_MAX_KEY_LEN   65

    Description:

    Indicates the maximum length of a Wi-Fi key.

    The maximum length is 64, and the last bit is reserved and set to \0.

    WIFI_MAX_SSID_LEN

      Description:

      Indicates the maximum length of a Wi-Fi SSID.

      The maximum length is 32, and the last bit is reserved and set to \0.

      WIFI_PSK_LEN

      1. #define WIFI_PSK_LEN   32

      Description:

      Indicates the maximum length of a Wi-Fi PSK. 

      1. #define WIFI_STA_ACTIVE   1

      Description:

      Indicates that the Wi-Fi station mode is enabled.

      WIFI_STA_NOT_ACTIVE

      1. #define WIFI_STA_NOT_ACTIVE   0

      Description:

      Indicates that the Wi-Fi station mode is disabled.

      Typedef Documentation

      WifiDeviceConfig

      1. typedef struct [WifiDeviceConfig]($api-api-LinkIoT-WifiDeviceConfig.md) [WifiDeviceConfig]($api-api-LinkIoT-WifiDeviceConfig.md)

      Description:

      Represents the Wi-Fi station configuration used to connect to a specified Wi-Fi device.

      Enumeration Type Documentation

      HotspotBandType

      1. enum [HotspotBandType]($api-api-LinkIoT-Wifiservice.md#ga37e10532da87571ee89193beac42d246)

      Description:

      Enumerates frequency bands supported by the Wi-Fi hotspot mode.

      Enumerator

      Description
      HOTSPOT_BAND_TYPE_2G 

      2.4 GHz

      HOTSPOT_BAND_TYPE_5G 

      5 GHz

      RssiLevel

      1. enum [RssiLevel]($api-api-LinkIoT-Wifiservice.md#gadb1b12fe6311711103e759aac7a470d4)

      Description:

      Enumerates received signal strength indicator (RSSI) levels.

      Four RSSI levels are available: 1 to 4. The higher the RSSI level, the stronger the Wi-Fi signal.

      Enumerator

      Description
      RSSI_LEVEL_1 

      Level 1. The RSSI value for a 2.4 GHz hotspot ranges from -88 (included) to -82 (excluded), and that for a 5 GHz hotspot ranges from -85 (included) to -79 (excluded).

      RSSI_LEVEL_2 

      Level 2. The RSSI value for a 2.4 GHz hotspot ranges from -82 (included) to -75 (excluded), and that for a 5 GHz hotspot ranges from -79 (included) to -72 (excluded).

      RSSI_LEVEL_3 

      Level 3. The RSSI value for a 2.4 GHz hotspot ranges from -75 (included) to -65 (excluded), and that for a 5 GHz hotspot ranges from -72 (included) to -65 (excluded).

      RSSI_LEVEL_4 

      Level 4. The RSSI value for a 2.4 GHz or 5 GHz hotspot is greater than or equal to -65.

      WifiConnState

      Description:

      Enumerates Wi-Fi connection states.

      Enumerator

      Description
      WIFI_DISCONNECTED 

      Disconnected

      WIFI_CONNECTED 

      Connected

      WifiErrorCode

      Description:

      Enumerates Wi-Fi error codes.

      Enumerator

      Description
      WIFI_SUCCESS 

      No errors.

      ERROR_WIFI_INVALID_ARGS 

      Invalid parameters

      ERROR_WIFI_CHIP_INVALID 

      Invalid chip

      ERROR_WIFI_IFACE_INVALID 

      Invalid Wi-Fi interface

      ERROR_WIFI_RTT_CONTROLLER_INVALID 

      Invalid RTT controller

      ERROR_WIFI_NOT_SUPPORTED 

      Wi-Fi not supported by the current version or device

      ERROR_WIFI_NOT_AVAILABLE 

      Wi-Fi unavailable

      ERROR_WIFI_NOT_STARTED 

      Wi-Fi not initialized or started

      ERROR_WIFI_BUSY 

      System busy

      ERROR_WIFI_UNKNOWN 

      Unknown error

      WifiEventState

      1. enum [WifiEventState]($api-api-LinkIoT-Wifiservice.md#ga6be99f93ce0d2d222c1f5f0a8217354d)

      Description:

      Enumerates states in Wi-Fi events.

      WifiPskType

      1. enum [WifiPskType]($api-api-LinkIoT-Wifiservice.md#gaa1a44d23b8478232f14d2adfc82cee77)

      Description:

      Enumerates psk encryption types.

      Enumerator

      Description
      WIFI_PSK_TYPE_ASCII 

      Indicates that the ascii type of psk encryption type

      WIFI_PSK_TYPE_HEX 

      Indicates that the hex type of psk encryption type

      WifiScanType

      1. enum [WifiScanType]($api-api-LinkIoT-Wifiservice.md#ga007bf5e22727debc02cad860e41a60a3)

      Description:

      Enumerates Wi-Fi scan types.

      Enumerator

      Description
      WIFI_FREQ_SCAN 

      A scan based on a specified frequency.

      WIFI_SSID_SCAN 

      A scan based on a specified SSID.

      WIFI_BSSID_SCAN 

      A scan based on a specified BSSID.

      WIFI_BAND_SCAN 

      A scan based on a specified frequency band.

      WifiSecurityType

      1. enum [WifiSecurityType]($api-api-LinkIoT-Wifiservice.md#ga97c133f7db7c1234babcde03c4ce1b05)

      Description:

      Enumerates Wi-Fi security types.

      Enumerator

      Description
      WIFI_SEC_TYPE_INVALID 

      Invalid security type

      WIFI_SEC_TYPE_OPEN 

      Open

      WIFI_SEC_TYPE_WEP 

      Wired Equivalent Privacy (WEP)

      WIFI_SEC_TYPE_PSK 

      Pre-shared key (PSK)

      WIFI_SEC_TYPE_SAE 

      Simultaneous Authentication of Equals (SAE)

      Function Documentation

      AddDeviceConfig()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) AddDeviceConfig (const [WifiDeviceConfig]($api-api-LinkIoT-WifiDeviceConfig.md) * config, int * result )

      Description:

      Adds a specified hotspot configuration for connecting to a hotspot.

      This function generates a networkId.

      Parameters:

      Name

      Description
      config Indicates the hotspot configuration to add.
      result Indicates the generated networkId. Each networkId matches a hotspot configuration.

      Returns:

      Returns WIFI_SUCCESS if the specified hotspot configuration is added; returns an error code defined in otherwise.

      AdvanceScan()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) AdvanceScan ([WifiScanParams]($api-api-LinkIoT-WifiScanParams.md) * params)

      Description:

      Starts a Wi-Fi scan based on a specified parameter.

      Only results matching the specified parameter will be returned for the Wi-Fi scan.

      Parameters:

      Name

      Description
      params Indicates the pointer to the parameter for starting the Wi-Fi scan. For details, see WifiScanParams.

      Returns:

      Returns if the Wi-Fi scan is started successfully; returns an error code defined in WifiErrorCode otherwise.

      ConnectTo()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) ConnectTo (int networkId)

      Description:

      Connects to a hotspot matching a specified networkId.

      Before calling this function, call AddDeviceConfig to add a hotspot configuration.

      Parameters:

      Name

      Description
      networkId Indicates the networkId matching the target hotspot.

      Returns:

      Returns if the hotspot is connected; returns an error code defined in WifiErrorCode otherwise.

      DisableHotspot()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) DisableHotspot (void )

      Description:

      Disables the hotspot mode.

      Returns:

      Returns WIFI_SUCCESS if the hotspot mode is disabled; returns an error code defined in otherwise.

      DisableWifi()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) DisableWifi (void )

      Description:

      Disables the station mode.

      Returns:

      Returns if the station mode is disabled; returns an error code defined in WifiErrorCode otherwise. 

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) Disconnect (void )

      Description:

      Disconnects this Wi-Fi connection.

      Returns:

      Returns if this Wi-Fi connection is disconnected; returns an error code defined in WifiErrorCode otherwise.

      EnableHotspot()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) EnableHotspot (void )

      Description:

      Enables the hotspot mode.

      Before using this function, you need to invoke SetHotspotConfig and set at least the SSID, security type, and key.

      Returns:

      Returns if the hotspot mode is enabled; returns an error code defined in WifiErrorCode otherwise.

      EnableWifi()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) EnableWifi (void )

      Description:

      Enables the station mode.

      Returns:

      Returns WIFI_SUCCESS if the station mode is enabled; returns an error code defined in otherwise.

      GetBand()

      Description:

      Obtains the frequency band of this hotspot.

      Parameters:

      Name

      Description
      result Indicates the obtained frequency band.

      Returns:

      Returns WIFI_SUCCESS if the frequency band is obtained; returns an error code defined in otherwise.

      GetDeviceConfigs()

      Description:

      Obtains all hotspot configurations.

      Hotspot configurations were added using .

      Parameters:

      Name

      Description
      result Indicates the array of all hotspot configurations. The array is requested and released by the caller. The value must be greater than or equal to .
      size Indicates the size of the array.

      Returns:

      Returns WIFI_SUCCESS if all hotspot configurations are obtained; returns an error code defined in otherwise.

      GetDeviceMacAddress()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) GetDeviceMacAddress (unsigned char * result)

      Description:

      Obtains the MAC address of this device.

      Parameters:

      Name

      Description
      result Indicates the MAC address of this device. It is a char array whose length is 6.

      Returns:

      Returns WIFI_SUCCESS if the MAC address of this device is obtained; returns an error code defined in otherwise.

      GetHotspotConfig()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) GetHotspotConfig ([HotspotConfig]($api-api-LinkIoT-HotspotConfig.md) * result)

      Description:

      Obtains a specified hotspot configuration.

      The hotspot configuration includes the SSID, security type, and key.

      Parameters:

      Returns:

      Returns WIFI_SUCCESS if the hotspot configuration is obtained; returns an error code defined in otherwise.

      GetLinkedInfo()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) GetLinkedInfo ([WifiLinkedInfo]($api-api-LinkIoT-WifiLinkedInfo.md) * result)

      Description:

      Obtains information about the connected hotspot.

      Parameters:

      Name

      Description
      result Indicates the information about the connected hotspot.

      Returns:

      Returns WIFI_SUCCESS if the information about the connected hotspot is obtained; returns an error code defined in otherwise.

      GetScanInfoList()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) GetScanInfoList ([WifiScanInfo]($api-api-LinkIoT-WifiScanInfo.md) * result, unsigned int * size )

      Description:

      Obtains an array of hotspots detected in a Wi-Fi scan.

      The array of hotspots can be obtained only after the Wi-Fi scan is complete.

      Parameters:

      Name

      Description
      result Indicates the array of hotspots detected in a Wi-Fi scan. The array is requested and released by the caller. The value must be greater than or equal to WIFI_SCAN_HOTSPOT_LIMIT.
      size Indicates the size of the array.

      Returns:

      Returns if the array of hotspots detected in the Wi-Fi scan is obtained; returns an error code defined in WifiErrorCode otherwise.

      GetSignalLevel()

      1. int GetSignalLevel (int rssi, int band )

      Description:

      Obtains the signal level indicated by a specified received signal strength indicator (RSSI) and frequency band.

      Based on the signal level, you can display the signal strength represented by the number of signal bars.

      Parameters:

      Name

      Description
      rssi Indicates the RSSI.
      band Indicates the frequency band, either or HOTSPOT_BAND_TYPE_2G.

      Returns:

      Returns the signal level if it is obtained; returns -1 otherwise.

      GetStationList()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) GetStationList ([StationInfo]($api-api-LinkIoT-StationInfo.md) * result, unsigned int * size )

      Description:

      Obtains an array of stations connected to this hotspot.

      The station information is defined in StationInfo.

      Parameters:

      Name

      Description
      result Indicates the array of stations connected to this hotspot. The array is requested and released by the caller. The value must be greater than or equal to WIFI_MAX_STA_NUM.
      size Indicates the size of the array.

      Returns:

      Returns if the array of stations connected to this hotspot is obtained; returns an error code defined in WifiErrorCode otherwise.

      IsHotspotActive()

      1. int IsHotspotActive (void )

      Description:

      Checks whether the hotspot mode is enabled.

      Returns:

      Returns WIFI_HOTSPOT_ACTIVE if the hotspot mode is enabled; returns otherwise.

      IsWifiActive()

      1. int IsWifiActive (void )

      Description:

      Checks whether the station mode is enabled.

      Returns:

      Returns if the station mode is enabled; returns WIFI_STA_NOT_ACTIVE otherwise.

      RegisterWifiEvent()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) RegisterWifiEvent ([WifiEvent]($api-api-LinkIoT-WifiEvent.md) * event)

      Description:

      Registers a callback for a specified Wi-Fi event.

      The registered callback will be invoked when the Wi-Fi event defined in WifiEvent occurs.

      Parameters:

      Name

      Description
      event Indicates the event for which the callback is to be registered.

      Returns:

      Returns WIFI_SUCCESS if the callback is registered successfully; returns an error code defined in otherwise.

      RemoveDevice()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) RemoveDevice (int networkId)

      Description:

      Removes a hotspot configuration matching a specified networkId.

      Parameters:

      Name

      Description
      networkId Indicates the networkId matching the hotspot configuration to remove.

      Returns:

      Returns WIFI_SUCCESS if the hotspot configuration is removed; returns an error code defined in otherwise.

      Scan()

      1. [WifiErrorCode]($api-api-LinkIoT-Wifiservice.md#ga2506c6ad226c4feb1d19248013ff9568) Scan (void )

      Description:

      Starts a Wi-Fi scan.

      Returns:

      Returns if the Wi-Fi scan is started; returns an error code defined in WifiErrorCode otherwise.

      SetBand()

        Description:

        Sets the frequency band for this hotspot.

        Parameters:

        Name

        Description
        band Indicates the frequency band to set.

        Returns:

        Returns if the frequency band is set; returns an error code defined in WifiErrorCode otherwise.

        SetHotspotConfig()

        Description:

        Sets a specified hotspot configuration.

        The hotspot configuration includes the SSID, security type, and key. The configuration set overwrites the existing configuration and takes effect after the hotspot mode is re-enabled. Before enabling the hotspot mode for the first time, you must call this function.

        Parameters:

        Name

        Description
        config Indicates the hotspot configuration to set.

        Returns:

        Returns if the hotspot configuration is set; returns an error code defined in WifiErrorCode otherwise.

        UnRegisterWifiEvent()

        Description:

        Unregisters a callback previously registered for a specified Wi-Fi event.

        Parameters:

        Name

        Description
        event Indicates the event for which the callback is to be unregistered.

        Returns:

        Returns if the callback is unregistered successfully; returns an error code defined in WifiErrorCode otherwise.