General Description

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. More...

typedef void(*	whd_auth_result_callback_t) (void result_ptr, uint32_t len, whd_auth_status_t status, uint8_t flag, void *user_data)
	Auth result callback function pointer type. More...

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. More...

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. More...

uint32_t	whd_wifi_stop_scan (whd_interface_t ifp)
	Abort a previously issued scan. More...

uint32_t	whd_wifi_external_auth_request (whd_interface_t ifp, whd_auth_result_callback_t callback, void result_ptr, void user_data)
	Initiates SAE auth. More...

uint32_t	whd_wifi_stop_external_auth_request (whd_interface_t ifp)
	Abort authentication request. More...

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. More...

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. More...

uint32_t	whd_wifi_leave (whd_interface_t ifp)
	Disassociates from a Wi-Fi network. More...

Typedef Documentation

◆ whd_scan_result_callback_t

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

◆ whd_auth_result_callback_t

typedef void(* whd_auth_result_callback_t) (void *result_ptr, uint32_t len, whd_auth_status_t status, uint8_t *flag, void *user_data)

Auth result callback function pointer type.

Parameters

result_prt	A pointer to the pointer that indicates where to put the auth result
len	the size of result
status	Status of auth process
flag	flag of h2e will be indicated in auth request event, otherwise is NULL.
user_data	user specific data that will be passed directly to the callback function

Function Documentation

◆ whd_wifi_scan_synch()

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().

Parameters

ifp	Pointer to handle instance of whd interface
scan_result	Pointer to user requested records buffer.
count	Pointer to the no of records user is interested in, and also to the no of record received.

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

Returns: WHD_SUCCESS or Error code

◆ whd_wifi_scan()

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.

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

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.

Returns: WHD_SUCCESS or Error code

◆ whd_wifi_stop_scan()

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

◆ whd_wifi_external_auth_request()

uint32_t whd_wifi_external_auth_request	(	whd_interface_t	ifp,
		whd_auth_result_callback_t	callback,
		void *	result_ptr,
		void *	user_data
	)

Initiates SAE auth.

The results of the auth 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.

Parameters

ifp	Pointer to handle instance of whd interface
callback	The callback function which will receive and process the result data.
data	Pointer to a pointer to a result storage structure.
user_data	user specific data that will be passed directly to the callback function

Note

- 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.

Returns: WHD_SUCCESS or Error code

◆ whd_wifi_stop_external_auth_request()

uint32_t whd_wifi_stop_external_auth_request ( whd_interface_t ifp )

Abort authentication request.

Parameters

ifp	Pointer to handle instance of whd interface

Returns: WHD_SUCCESS or Error code

◆ whd_wifi_join()

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.

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.

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

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

◆ whd_wifi_join_specific()

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

◆ whd_wifi_leave()

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


		Wi-Fi Host Driver (WHD) Public API Reference Guide

General Description

Typedefs

Functions

Typedef Documentation

◆ whd_scan_result_callback_t

◆ whd_auth_result_callback_t

Function Documentation

◆ whd_wifi_scan_synch()

◆ whd_wifi_scan()

◆ whd_wifi_stop_scan()

◆ whd_wifi_external_auth_request()

◆ whd_wifi_stop_external_auth_request()

◆ whd_wifi_join()

◆ whd_wifi_join_specific()

◆ whd_wifi_leave()