第2讲 Hi3861的WiFi实验-API-1

引言

在本专栏的第1讲中介绍过Hi3861，这是一款带MCU的WiFi芯片，它的WiFi模块主要有两种工作模式：AP（Access Point）模式、Station模式。

（1）AP模式

AP模式，也称为“接入点模式”或“WiFi热点模式”。在这种模式下，Hi3861就是一个WiFi热点，允许其它设备接入，以它为中心组成一个WiFi局域网。

（2）Station模式

Station模式，也称为“站点模式”或“WiFi设备模式”。在这种模式下，Hi3861就是一个WiFi设备，可以扫描并接入周边的WiFi热点。

在这一讲中，带大家做两个编程实验，分别测试Hi3861的AP模式和Station模式。不过在编程之前，需要先熟悉一些应用程序接口（API），因为我们需要在编写实验代码时调用这些API。

​

从这篇文章开始，先介绍Hi3861的WiFi编程实验中要用到的应用程序接口（API）。

与WiFi编程实验相关的API主要集中在Wifiservice和Netif这两个模块里面。

​

一、Wifiservice

1.1 Wifiservice简介

1.1.1 Wifiservice的官方文档

在下面这个链接中，有Wifiservice的详细说明文档。

https://device.harmonyos.com/cn/docs/documentation/apiref/wifiservice-0000001055195054

在第1讲中介绍鸿蒙系统的技术架构时讲过，鸿蒙系统在系统这一层是按照“系统（子系统集） > 子系统（Subsystem） > 组件/功能模块（Component）”逐级展开的。

如上图所示，实验中用的Hi3861开发板属于连接类模组，上面跑的是轻量级鸿蒙系统；在鸿蒙系统中，有一个系统基础能力子系统集；在这个子系统集中，有一个公共通信子系统；在公共通信子系统中有一个对外提供WLAN服务的功能模块（注：没有出现在上图中），而 Wifiservice 就是这个功能模块的对外接口。

1.1.2 Wifiservice的代码仓库

Wifiservice在gitee上的代码仓库：

https://gitee.com/openharmony/communication_wifi_lite

如上图所示，foundation 是鸿蒙系统中的“系统基础能力子系统集”；communication 是“公共通信子系统”，在 OpenHarmony 中被称为“分布式软总线子系统”（https://gitee.com/openharmony/docs/tree/master/zh-cn/readme）；wifi_lite 是一个能够提供WLAN服务的功能模块；在 interfaces/wifiservice 文件夹中声明了 wifi_lite 这个功能模块的对外接口（注：可用 Wifiservice 指代 wifi_lite 这个功能模块）。

1.1.3 Wifiservice在鸿蒙工程中的位置

启动 DevEco Device Tool，打开按照文章《获取OpenHarmony源码：从DevEco Marketplace获取（2）》创建的鸿蒙项目。

1、Wifiservice头文件路径

foundation/communication/wifi_lite/interfaces/wifiservice

在wifiservice文件夹中共有9个头文件，用于声明 wifi_lite 模块的对外接口，其中处于顶层的头文件有两个：wifi_device.h 和 wifi_hotspot.h，打开这两个头文件，可以看到其它的头文件都包含到这两个头文件里了（甚至在wifi_hotspot.h中还包含了wifi_device.h）。从这两个头文件的名称，我们大概可以猜出，wifi_hotspot.h用于WiFi的热点模式，wifi_device.h用于WiFi的设备模式。

2、Wifiservice源文件路径

device/soc/hisilicon/hi3861v100/hi3861_adapter/hals/communication/wifi_lite/wifiservice/source

source文件夹里面是 wifi_lite 模块对外接口的实现，最重要的是 wifi_device.c 和 wifi_hotspot.c 这两个文件，分别对应WiFi设备模式和热点模式下的接口实现。

​

1.2 Wifiservice的API

Wifiservice提供的API主要包括一些结构体和接口函数，另外还有一些宏、枚举类型等。下面仅介绍在本次实验代码中用到的一些结构体和接口函数，对于其他的接口，建议大家还是结合头文件中的定义，去看Wifiservice的说明文档。

1.2.1 结构体：WifiEvent

WifiEvent结构体，称为“WiFi事件回调函数指针结构体”，或简称为“WiFi事件结构体”，在头文件 wifi_event.h 中定义。说明文档：

https://device.harmonyos.com/cn/docs/develop/apiref/wifievent-0000001054876478

什么是WiFi事件？

在Wifiservice这个模块中定义了5种WiFi事件：两种Station模式下的事件；三种AP模式下的事件。以Hi3861为例：

1、Station模式下的WiFi事件

（1）Hi3861作为WiFi设备，与周边WiFi热点的连接状态发生变化（接入/断开）。

（2）Hi3861作为WiFi设备，对周边WiFi热点的扫描状态发生变化（启动/停止扫描）。

2、AP模式下的WiFi事件

（1）Hi3861作为WiFi接入点（热点），WiFi热点的状态发生变化（打开/关闭）。

（2）Hi3861作为WiFi接入点（热点），发现有设备接入。

（3）Hi3861作为WiFi接入点（热点），发现有设备离开。

Wifiservice这个模块允许我们针对每一种事件写一个对该事件的处理函数，一旦这种事件发生，相应的处理函数就会被系统自动执行，我们把这样的函数称为WiFi事件的回调函数。

注意： 这些回调函数的参数和返回值类型，都已经在Wifiservice这个模块中规定好了，函数名需要自己定义，函数里面的代码，也就是如何对发生的WiFi事件进行处理，当然也需要自己去写。

WifiEvent结构体中的成员就是上述这5种WiFi事件的回调函数的指针，如下图所示：

（1）Hi3861作为WiFi设备，与周边WiFi热点的连接状态发生变化（接入/断开）时，第1个函数指针OnWifiConnectionChanged指向的函数被自动执行，同时会给这个函数传入两个参数：state和info。如果state=0，说明Hi3861与WiFi热点之间的连接状态是从连接变成了断开；如果state=1，说明Hi3861与WiFi热点之间的连接状态是从断开变成了连接。第二个参数info是指向WifiLinkedInfo结构体的指针，在这个结构体中存放的是Hi3861接入的那个WiFi热点的信息。

（2）Hi3861作为WiFi设备，对周边WiFi热点的扫描状态发生变化（启动/停止扫描）时，第2个函数指针OnWifiScanStateChanged指向的函数被自动执行，同时会给这个函数传入两个参数：state和size。如果state=0，说明Hi3861启动对周边WiFi热点的扫描；如果state=1，说明Hi3861对周边WiFi热点的扫描结束了。第二个参数size是扫描到的WiFi热点的个数。

（3）Hi3861作为WiFi接入点（热点），WiFi热点的状态发生变化（打开/关闭）时，第3个函数指针OnHotspotStateChanged指向的函数被自动执行，同时会给这个函数传入一个参数：state。如果state=0，说明Hi3861的WiFi热点关闭了；如果state=1，说明Hi3861的WiFi热点打开了。

（4）Hi3861作为WiFi接入点（热点），发现有设备接入时，第4个函数指针OnHotspotStaJoin指向的函数被自动执行，同时会给这个函数传入一个参数：info。参数info是指向StationInfo结构体的指针，在这个结构体中存放的是刚刚接入热点的设备的信息。

（5）Hi3861作为WiFi接入点（热点），发现有设备离开时，第5个函数指针OnHotspotStaLeave指向的函数被自动执行，同时会给这个函数传入一个参数：info。参数info是指向StationInfo结构体的指针，在这个结构体中存放的是刚刚离开热点的设备的信息。

例如，在本次实验的实验代码中，定义了一个名为g_wifiEventHandler的WiFi事件回调函数结构体，如下所示：

WifiEvent g_wifiEventHandler = {0};        //WiFi事件回调函数结构体

1.2.2 结构体：WifiDeviceConfig

WifiDeviceConfig结构体用于存放WiFi设备的配置信息，在wifi_device_config.h头文件中定义，如下图所示。说明文档：

https://device.harmonyos.com/cn/docs/develop/apiref/wifideviceconfig-0000001055036456

WifiDeviceConfig结构体中有10个成员：

（1）ssid：WiFi设备要连接的WiFi热点的名称，字符串，最长32字节。

（2）bssid：WiFi设备要连接的WiFi热点的MAC地址，6字节。

（3）preSharedKey：WiFi设备要连接的WiFi热点的密码，最长65字节。

（4）securityType：WiFi设备要连接的WiFi热点的加密方式。查看在同一头文件中定义的枚举类型WifiSecurityType，有三种有效的加密方式可选：WIFI_SEC_TYPE_WEP、WIFI_SEC_TYPE_PSK、WIFI_SEC_TYPE_SAE。

（5）netId：被分配的网络号。

（6）freq：通信频率。

（7）wapiPskType：PSK这种加密方式的类型，有两种：ASCII码、16进制数，见同一头文件中定义的枚举类型WifiPskType。

（8）ipType：IP地址类型，有两种：静态IP、动态分配IP，见同一头文件中定义的枚举类型IpType。

（9）staticIp：这个成员是一个IpConfig结构体（在同一头文件中定义），用于存放静态IP的信息，包括IP地址、网关、DNS服务器、子网掩码。

（10）isHiddenSsid：WiFi设备要连接的WiFi热点是否隐藏了SSID。0：未隐藏；1：隐藏。

小贴士：

所谓SSID，就是Service Set Identifier的缩写，用于区分不同的无线网络，最多可以有32个字符。SSID通常由AP广播出来，可以被周边的WiFi设备扫描到，也可以出于安全考虑不广播SSID，此时用户就要手工设置SSID才能将设备接入相应的网络。简单说，SSID就是一个WiFi局域网的名称。
一个WiFi局域网SS（Service Set）中可能会有多个AP，每个AP和至少一个接入该AP的WiFi设备（Station）构成了一个BSS（Basic Service Set），这个BSS的标识就是BSSID。BSSID是一个48bit的数值，通常是AP的MAC地址，用来对较小BSS区域进行标识。

1.2.3 结构体：WifiLinkedInfo

WifiLinkedInfo结构体用于存放设备刚刚接入或离开的WiFi热点的信息，在头文件wifi_linked_info.h中定义，如下图所示。说明文档：

https://device.harmonyos.com/cn/docs/documentation/apiref/wifilinkedinfo-0000001055195070

WifiLinkedInfo结构体中有8个成员：

（1）ssid：WiFi热点的名称，字符串，最长32字节。

（2）bssid：WiFi热点的MAC地址，6字节。

（3）rssi：WiFi热点的信号强度。

（4）band：WiFi热点的通信频段（信道）。

（5）frequency：WiFi热点的通信频率。

（6）connState：当前与WiFi热点的连接状态（1：连接；0：断开），见同一头文件中定义的枚举类型WifiConnState。

（7）disconnectedReason：WiFi设备与WiFi热点断开的原因。

（8）ipAddress：WiFi热点的IP地址。

​

未完待续 …