WHD Wi-Fi join, Scan and Halt API

group wifijoin

Wi-Fi APIs for join, scan & leave.

Typedefs

typedef void (*whd_scan_result_callback_t)(whd_scan_result_t **result_ptr, void *user_data, whd_scan_status_t status)

Scan result callback function pointer type.

Parameters
  • result_ptr: A pointer to the pointer that indicates where to put the next scan result

  • user_data: User provided data

  • status: Status of scan process

Functions

uint32_t whd_wifi_scan_synch(whd_interface_t ifp, whd_sync_scan_result_t *scan_result, uint32_t count)

Initiates a scan to search for 802.11 networks.

This functions returns the scan results with limited sets of parameter in a buffer provided by the caller. It is also a blocking call. It is an simplified version of the whd_wifi_scan().

note

When scanning specific channels, devices with a strong signal strength on nearby channels may be detected

Return

record count or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

  • scan_result: pointer to user requested records buffer.

  • count: No of records user is interested in. If 0 return the total record count.

uint32_t whd_wifi_scan(whd_interface_t ifp, whd_scan_type_t scan_type, whd_bss_type_t bss_type, const whd_ssid_t *optional_ssid, const whd_mac_t *optional_mac, const uint16_t *optional_channel_list, const whd_scan_extended_params_t *optional_extended_params, whd_scan_result_callback_t callback, whd_scan_result_t *result_ptr, void *user_data)

Initiates a scan to search for 802.11 networks.

The scan progressively accumulates results over time, and may take between 1 and 10 seconds to complete. The results of the scan will be individually provided to the callback function. Note: The callback function will be executed in the context of the WHD thread and so must not perform any actions that may cause a bus transaction.

note

- When scanning specific channels, devices with a strong signal strength on nearby channels may be detected

  • Callback must not use blocking functions, nor use WHD functions, since it is called from the context of the WHD thread.

  • The callback, result_ptr and user_data variables will be referenced after the function returns. Those variables must remain valid until the scan is complete.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

  • scan_type: Specifies whether the scan should be Active, Passive or scan Prohibited channels

  • bss_type: Specifies whether the scan should search for Infrastructure networks (those using an Access Point), Ad-hoc networks, or both types.

  • optional_ssid: If this is non-Null, then the scan will only search for networks using the specified SSID.

  • optional_mac: If this is non-Null, then the scan will only search for networks where the BSSID (MAC address of the Access Point) matches the specified MAC address.

  • optional_channel_list: If this is non-Null, then the scan will only search for networks on the specified channels - array of channel numbers to search, terminated with a zero

  • optional_extended_params: If this is non-Null, then the scan will obey the specifications about dwell times and number of probes.

  • callback: The callback function which will receive and process the result data.

  • result_ptr: Pointer to a pointer to a result storage structure.

  • user_data: user specific data that will be passed directly to the callback function

uint32_t whd_wifi_stop_scan(whd_interface_t ifp)

Abort a previously issued scan.

Return

WHD_SUCCESS or Error code

Parameters
  • ifp: Pointer to handle instance of whd interface

uint32_t whd_wifi_join(whd_interface_t ifp, const whd_ssid_t *ssid, whd_security_t auth_type, const uint8_t *security_key, uint8_t key_length)

Joins a Wi-Fi network.

Scans for, associates and authenticates with a Wi-Fi network. On successful return, the system is ready to send data packets.

note

In case of WPA3/WPA2 transition mode, the security_key value is WPA3 password.

Return

WHD_SUCCESS when the system is joined and ready to send data packets Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • ssid: A null terminated string containing the SSID name of the network to join

  • auth_type: Authentication type

  • security_key: A byte array containing either the cleartext security key for WPA/WPA2/WPA3 secured networks

  • key_length: The length of the security_key in bytes.

uint32_t whd_wifi_join_specific(whd_interface_t ifp, const whd_scan_result_t *ap, const uint8_t *security_key, uint8_t key_length)

Joins a specific Wi-Fi network.

Associates and authenticates with a specific Wi-Fi access point. On successful return, the system is ready to send data packets.

Return

WHD_SUCCESS when the system is joined and ready to send data packets Error code if an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface

  • ap: A pointer to a whd_scan_result_t structure containing AP details and set ap.channel to 0 for unspecificed channel

  • security_key: A byte array containing either the cleartext security key for WPA/WPA2 secured networks

  • key_length: The length of the security_key in bytes.

uint32_t whd_wifi_leave(whd_interface_t ifp)

Disassociates from a Wi-Fi network.

Applicable only for STA role

Return

WHD_SUCCESS On successful disassociation from the AP Error code If an error occurred

Parameters
  • ifp: Pointer to handle instance of whd interface.