sta

xf_wifi sta. 更多...

sta 的协作图:

函数
xf_err_t	xf_wifi_sta_init (const xf_wifi_sta_cfg_t *p_cfg)
	启用 wifi STA 模式.
xf_err_t	xf_wifi_sta_deinit (void)
	反初始化 wifi STA 模式, 并且释放相关资源.
xf_err_t	xf_wifi_sta_get_netif (xf_netif_t *p_netif_hdl)
	获取 STA 的 netif 句柄.
xf_err_t	xf_wifi_sta_set_cb (xf_wifi_cb_t cb_func, void *user_args)
	wifi STA 设置回调函数.
xf_err_t	xf_wifi_sta_set_ip_cb (xf_ip_cb_t cb_func, void *user_args)
	STA 设置 ip 事件回调函数.
xf_err_t	xf_wifi_sta_connect (xf_wifi_sta_cfg_t *p_cfg)
	STA 连接到指定 AP.
bool	xf_wifi_sta_is_connected (void)
	STA 检查是否已经连接到 AP.
xf_err_t	xf_wifi_sta_disconnect (void)
	STA 主动断开 AP 连接。
xf_err_t	xf_wifi_sta_get_ap_info (xf_wifi_ap_info_t *p_info)
	STA 获取当前连接到的 AP 的信息。
xf_err_t	xf_wifi_scan_start (const xf_wifi_scan_cfg_t *p_cfg, bool block)
	wifi 启动 AP 扫描。
xf_err_t	xf_wifi_scan_stop (void)
	wifi 停止 AP 扫描。
xf_err_t	xf_wifi_scan_get_result (xf_wifi_ap_info_t result_array[], uint32_t result_array_size, uint32_t *p_result_num)
	wifi 获取扫描结果。
xf_err_t	xf_wifi_scan_clear_result (void)
	wifi 清除扫描结果。

详细描述

xf_wifi sta.

函数说明

xf_wifi_sta_init()

xf_err_t xf_wifi_sta_init

(

const xf_wifi_sta_cfg_t *

p_cfg

)

启用 wifi STA 模式.

注解

注意，此函数只是启用 STA 模式，并**不**连接 AP。 连接 AP 请调用 xf_wifi_sta_connect().

参数

[in]

p_cfg

STA 配置（目标 AP 配置）。仅在内部拷贝记录。可以为 NULL.

返回

xf_err_t

• XF_OK 启用成功或连接成功
• XF_FAIL 失败

注意

函数行为约定.

• xf_wifi_sta_init() 应在内部完成:
  • 判断是否已初始化。
    • 已初始化时返回 XF_ERR_INITED.
  • 判断参数合法性。
    • p_cfg 允许为 NULL, 此时仅启用站点模式。
  • 检测内部 netif 组件是否初始化，未初始化则先初始化。
    • 不分离 netif 的原因是： 某些系统会在 wifi 组件内部完成对 netif 的注册，不需要显式初始化， 用户使用 netif 时只需 netif_find() 找到对应的网络接口即可。
    • 内部实现时需要保存对应 sta 的 netif，以供后续 xf_wifi_ap_get_netif() 使用。
  • 配置 wifi 组件为 sta 模式，如果 p_cfg 不为 NULL 则保存配置。
    • 对于不支持的配置，应当以 XF_LOGW() 输出。
  • 如果 p_cfg->p_static_ip == NULL 内部自动启用 dhcp 客户端器；否则根据配置设置 ip。

示例

examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/base_scan/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

xf_wifi_sta_deinit()

xf_err_t xf_wifi_sta_deinit

(

void

)

反初始化 wifi STA 模式, 并且释放相关资源.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

xf_wifi_sta_get_netif()

xf_err_t xf_wifi_sta_get_netif

(

xf_netif_t *

p_netif_hdl

)

获取 STA 的 netif 句柄.

参数

[out]

p_netif_hdl

传出对应的 netif 句柄, 通过该句柄可配置 IP 等信息.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

示例

examples/protocols/http_request/main/xf_main.c , 以及 examples/protocols/icmp_echo/main/xf_main.c.

xf_wifi_sta_set_cb()

xf_err_t xf_wifi_sta_set_cb	(	xf_wifi_cb_t	cb_func,
		void *	user_args
	)

wifi STA 设置回调函数.

参数

[in]	cb_func	回调函数, 见 xf_wifi_cb_t.
[in]	user_args	调用回调函数时的用户参数.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

注解

1. 建议在启用 STA 前设置回调.

示例

examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/base_scan/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

xf_wifi_sta_set_ip_cb()

xf_err_t xf_wifi_sta_set_ip_cb	(	xf_ip_cb_t	cb_func,
		void *	user_args
	)

STA 设置 ip 事件回调函数.

参数

[in]	cb_func	回调函数, 见 xf_ip_cb_t.
[in]	user_args	调用回调函数时的用户参数。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

注解

1. 建议在启用 STA 前设置回调.

示例

examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

xf_wifi_sta_connect()

xf_err_t xf_wifi_sta_connect

(

xf_wifi_sta_cfg_t *

p_cfg

)

STA 连接到指定 AP.

参数

p_cfg

目标 AP 配置. 如果在调用 xf_wifi_sta_init() 时已经填入，可以填入 NULL 使用之前的配置。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

示例

examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

xf_wifi_sta_is_connected()

bool xf_wifi_sta_is_connected

(

void

)

STA 检查是否已经连接到 AP.

返回

true 已经连接到 AP

false 未连接到 AP

示例

examples/wireless/wifi/get_started/station/main/xf_main.c, examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c , 以及 examples/wireless/wifi/static_ip/station/main/xf_main.c.

xf_wifi_sta_disconnect()

xf_err_t xf_wifi_sta_disconnect

(

void

)

STA 主动断开 AP 连接。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

xf_wifi_sta_get_ap_info()

xf_err_t xf_wifi_sta_get_ap_info

(

xf_wifi_ap_info_t *

p_info

)

STA 获取当前连接到的 AP 的信息。

参数

[out]

p_info

传出 AP 的信息。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败或未连接

xf_wifi_scan_start()

xf_err_t xf_wifi_scan_start	(	const xf_wifi_scan_cfg_t *	p_cfg,
		bool	block
	)

wifi 启动 AP 扫描。

注解

AP 模式下能否扫描取决于具体平台。

参数

p_cfg	wifi 扫描参数。
block	是否阻塞扫描。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

示例

examples/wireless/wifi/scan/base_scan/main/xf_main.c , 以及 examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c.

xf_wifi_scan_stop()

xf_err_t xf_wifi_scan_stop

(

void

)

wifi 停止 AP 扫描。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

xf_wifi_scan_get_result()

xf_err_t xf_wifi_scan_get_result	(	xf_wifi_ap_info_t	result_array[],
		uint32_t	result_array_size,
		uint32_t *	p_result_num
	)

wifi 获取扫描结果。

注解

如果需要读取结果，建议使用足够大的内存，一次读取所有结果。

参数

[out]	result_array	保存结果的数组。 result_array 指向用于存放信息的内存。 p_result_num 可以为 NULL(或者 p_result_num 为 0)， 此时仅查询已连接的 STA 个数。
	result_array_size	保存结果数组的最大容量（单位：个）。可以为 0.
[out]	p_result_num	result_array 和 result_array_size 有效时传出实际读出数。 无效时传出扫描结果个数。不能为 NULL.

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

示例

examples/wireless/wifi/scan/base_scan/main/xf_main.c , 以及 examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c.

xf_wifi_scan_clear_result()

xf_err_t xf_wifi_scan_clear_result

(

void

)

wifi 清除扫描结果。

注解

1. 小心使用，不同平台对扫描结果的需求不同。 esp32 上不需要扫描结果也可以连接；ws63 上清除了扫描结果则无法连接。

2. 使用 xf_wifi_scan_get_result() 读取完毕后，请及时调用此接口 确保具体 SDK 内部申请的内存得以释放。

3. 扫描完毕后，如果不需要连接，或者结果中没有目标 AP，则直接调用此接口清理； 或者有目标 AP，连接后调用此接口清理。

返回

xf_err_t

• XF_OK 成功
• XF_FAIL 失败

示例

examples/wireless/wifi/scan/base_scan/main/xf_main.c , 以及 examples/wireless/wifi/scan/scan_and_connect/main/xf_main.c.