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

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.

Returns

record count or Error code

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.

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

Returns

WHD_SUCCESS or Error code

uint32_t whd_wifi_stop_scan(whd_interface_t ifp)

Abort a previously issued scan.

Parameters

ifp – Pointer to handle instance of whd interface

Returns

WHD_SUCCESS or Error code

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.

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.

Returns

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

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.

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.

Returns

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

uint32_t whd_wifi_leave(whd_interface_t ifp)

Disassociates from a Wi-Fi network.

Applicable only for STA role

Parameters

ifp – Pointer to handle instance of whd interface.

Returns

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