diff --git a/en/device_api/hdi/wlan/wifi_hal.h b/en/device_api/hdi/wlan/wifi_hal.h new file mode 100644 index 0000000000000000000000000000000000000000..d892d3d2d4e81b959a7ebde59e070fabcdf01da5 --- /dev/null +++ b/en/device_api/hdi/wlan/wifi_hal.h @@ -0,0 +1,289 @@ +/* + * Copyright (c) 2021-2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. + * + * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface + * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, + * network devices, and power, and applying for, releasing, and moving network data buffers. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal.h + * + * @brief Declares APIs for basic WLAN features. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_H +#define WIFI_HAL_H + +#include "wifi_hal_ap_feature.h" +#include "wifi_hal_sta_feature.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief Defines a callback to listen for IWiFi asynchronous events. + * + * @param event Indicates the event type passed to the callback. + * @param data Indicates the pointer to the data passed to the callback. + * @param ifName The interface name. + * + * @return Returns 0 if the IWiFi callback is defined. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName); + +/** + * @brief Defines the basic WLAN features provided by the hardware abstraction layer (HAL). + * + * The basic features include creating and stopping a channel between the HAL and the WLAN driver, + * and creating, obtaining, and destroying WLAN features. + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFi { + /** + * @brief Creates a channel between the HAL and the WLAN driver and obtains the driver NIC information. + * + * @param iwifi Indicates the pointer to the {@link IWiFi} object. + * + * @return Returns 0 if the channel is created and the driver NIC information is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*start)(struct IWiFi *iwifi); + + /** + * @brief Stops the channel between the HAL and the WLAN driver. + * + * @param iwifi Indicates the pointer to the {@link IWiFi} object. + * + * @return Returns 0 if the channel is stopped. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*stop)(struct IWiFi *iwifi); + + /** + * @brief Obtains the WLAN features available for the device no matter whether it works as an AP, + * STA, or P2P server/client. + * + * @param supType Indicates the pointer to the WLAN features available for the device. + * @param size Indicates the length of the supType array. + * + * @return Returns 0 if the WLAN features are obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getSupportFeature)(uint8_t *supType, uint32_t size); + + /** + * @brief Obtains the WLAN features available for the device that plays different roles simultaneously + * (any combination of AP, STA, and P2P server/client). + * + * @param combo Indicates the pointer to WLAN features available for the device. + * @param size Indicates the length of the combo array. + * + * @return Returns 0 if the WLAN features are obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getSupportCombo)(uint64_t *combo, uint32_t size); + + /** + * @brief Creates an {@link IWiFiBaseFeature} object of a specified type. + * + * @param type Indicates the feature type. + * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object. + * + * @return Returns 0 if the {@link IWiFiBaseFeature} object is created. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*createFeature)(int32_t type, struct IWiFiBaseFeature **ifeature); + + /** + * @brief Obtains an {@link IWiFiBaseFeature} object based on a specified network interface name. + * + * @param ifName Indicates the pointer to the network interface name. + * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object. + * + * @return Returns 0 if the {@link IWiFiBaseFeature} object is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getFeatureByIfName)(const char *ifName, struct IWiFiBaseFeature **ifeature); + + /** + * @brief Registers a callback to listen for IWiFi asynchronous events. + * + * @param cbFunc Indicates the callback to register. + * @param ifName Indicates the pointer to the network interface name. + * + * @return Returns 0 if the callback is registered. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*registerEventCallback)(CallbackFunc cbFunc, const char *ifName); + + /** + * @brief Deregisters an IWiFi callback. + + * @param cbFunc Indicates the callback to register. + * @param ifName Indicates the pointer to the network interface name. + * + * @return Returns 0 if the IWiFi callback is deregistered. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*unregisterEventCallback)(CallbackFunc cbFunc, const char *ifName); + + /** + * @brief Destroys a specified {@link IWiFiBaseFeature} object. + * + * @param ifeature Indicates the pointer to the {@link IWiFiBaseFeature} object to destroy. + * + * @return Returns 0 if the {@link IWiFiBaseFeature} object is destroyed. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*destroyFeature)(struct IWiFiBaseFeature *ifeature); + + /** + * @brief Resets the WLAN driver with a specified chip ID. + * + * @param chipId Indicates the chip ID. + * + * @return Returns 0 if the WLAN driver is reset. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*resetDriver)(const uint8_t chipId, const char *ifName); + + /** + * @brief get net device infos. + * + * @param netDeviceInfoResult get net device infos. + * + * @return Returns 0 if get infos successful. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getNetDevInfo)(struct NetDeviceInfoResult *netDeviceInfoResult); + + /** + * @brief Obtains the power mode which is being used. + * + * @param ifName Indicates the pointer to the network interface name. + * @param mode Indicates the pointer to the power mode. + * + * @return Returns 0 if get infos successful. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getPowerMode)(const char *ifName, uint8_t *mode); + + /** + * @brief Set the power mode. + * + * @param ifName Indicates the pointer to the network interface name. + * @param mode The value set to power mode. + * + * @return Returns 0 if get infos successful. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setPowerMode)(const char *ifName, uint8_t mode); +}; + +/** + * @brief Creates an {@link IWiFi} structure. + * + * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +int32_t WifiConstruct(struct IWiFi **wifiInstance); + +/** + * @brief Destroys a specified {@link IWiFi} structure. + * + * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +int32_t WifiDestruct(struct IWiFi **wifiInstance); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/en/device_api/hdi/wlan/wifi_hal_ap_feature.h b/en/device_api/hdi/wlan/wifi_hal_ap_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..1c2f59a1c2548177122750d1030fbdf625e8c520 --- /dev/null +++ b/en/device_api/hdi/wlan/wifi_hal_ap_feature.h @@ -0,0 +1,124 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. + * + * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface + * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, + * network devices, and power, and applying for, releasing, and moving network data buffers. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_ap_feature.h + * + * @brief Declares WLAN access point (AP) features. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_AP_FEATURE_H +#define WIFI_HAL_AP_FEATURE_H + +#include "wifi_hal_base_feature.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief Describes an STA connected to an AP. + * + * @since 1.0 + * @version 1.0 + */ +struct StaInfo { + /**< MAC address of the STA */ + unsigned char mac[WIFI_MAC_ADDR_LENGTH]; +}; + +/** + * @brief Inherits the basic features of {@link IWiFiBaseFeature} and additionally provides the features of + * obtaining information about all the STAs connected to an AP and setting the country/region code. + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiAp { + /**< Basic features of {@link IWiFiBaseFeature} */ + struct IWiFiBaseFeature baseFeature; + + /** + * @brief Obtains information (MAC addresses only in the current version) about all the connected STAs. + * + * @param apFeature Indicates the pointer to the AP feature, as described in {@link IWiFiAp}. + * @param staInfo Indicates the pointer to the information about the STAs connected to the AP. + * @param count Indicates the number of elements in the staInfo structure array. + * @param num Indicates the pointer to the number of connected STAs. + * + * @return Returns 0 if the information is obtained. + * @return Returns a negative value if the operation fails. + * @since 1.0 + * @version 1.0 + */ + int32_t (*getAsscociatedStas)(const struct IWiFiAp *apFeature, struct StaInfo *staInfo, + uint32_t count, uint32_t *num); + + /** + * @brief Sets the country/region code. + * + * @param apFeature Indicates the pointer to the AP feature, as described in {@link IWiFiAp}. + * @param code Indicates the pointer to the country/region code to set. + * @param len Indicates the length of the country/region code. + * + * @return Returns 0 if the country/region code is set. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setCountryCode)(const struct IWiFiAp *apFeature, const char *code, uint32_t len); +}; + +/** + * @brief Initializes a specified AP feature. This function is called during AP {@link FeatureType} creation. + * + * @param fe Indicates the double pointer to the AP feature. + * + * @return Returns 0 if the operation is successful. + * @return Returns a negative value representing {@link HDF_STATUS} if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitApFeature(struct IWiFiAp **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/en/device_api/hdi/wlan/wifi_hal_base_feature.h b/en/device_api/hdi/wlan/wifi_hal_base_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..7e742d0fbbeeeef54a95b89f0db83e75243e7557 --- /dev/null +++ b/en/device_api/hdi/wlan/wifi_hal_base_feature.h @@ -0,0 +1,257 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. + * + * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface + * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, + * network devices, and power, and applying for, releasing, and moving network data buffers. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_base_feature.h + * + * @brief Declares basic WLAN features. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_BASE_FEATURE_H +#define WIFI_HAL_BASE_FEATURE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief Indicates the maximum length of the network interface name. + * + * @since 1.0 + * @version 1.0 + */ +#define IFNAME_MAX_LEN 16 +/** + * @brief Indicates the length of the MAC address. + * + * @since 1.0 + * @version 1.0 + */ +#define WIFI_MAC_ADDR_LENGTH 6 +/** + * @brief Defines the access failure error. + * + * @since 1.0 + * @version 1.0 + */ +#define ERR_UNAUTH_ACCESS (-6) + +/** + * @brief Enumerates feature types. + * + * @since 1.0 + * @version 1.0 + */ +typedef enum { + /**< Unspecified type */ + PROTOCOL_80211_IFTYPE_UNSPECIFIED, + /**< Ad hoc network */ + PROTOCOL_80211_IFTYPE_ADHOC, + /**< Station */ + PROTOCOL_80211_IFTYPE_STATION, + /**< Access point (AP) */ + PROTOCOL_80211_IFTYPE_AP, + /**< Virtual AP */ + PROTOCOL_80211_IFTYPE_AP_VLAN, + /**< Wireless distributed system */ + PROTOCOL_80211_IFTYPE_WDS, + /**< Listening */ + PROTOCOL_80211_IFTYPE_MONITOR, + /**< Mesh network */ + PROTOCOL_80211_IFTYPE_MESH_POINT, + /**< P2P client */ + PROTOCOL_80211_IFTYPE_P2P_CLIENT, + /**< P2P group owner */ + PROTOCOL_80211_IFTYPE_P2P_GO, + /**< P2P device */ + PROTOCOL_80211_IFTYPE_P2P_DEVICE, + /**< Number of network ports */ + PROTOCOL_80211_IFTYPE_NUM, +} FeatureType; + +/** + * @brief Defines basic WLAN features, such as obtaining the network interface name, setting the MAC address, + * and setting the transmit power. + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiBaseFeature { + /**< Network interface name */ + char ifName[IFNAME_MAX_LEN]; + /**< Feature type, as enumerated in {@link FeatureType} */ + int32_t type; + + /** + * @brief Obtains the name of a network interface. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * + * @return Returns 0 if the network interface name is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + const char *(*getNetworkIfaceName)(const struct IWiFiBaseFeature *baseFeature); + + /** + * @brief Obtains the type of a basic feature. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * + * @return Returns 0 if the feature type is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getFeatureType)(const struct IWiFiBaseFeature *baseFeature); + + /** + * @brief Sets the MAC address. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * @param mac Indicates the pointer to the MAC address. + * @param len Indicates the length of the MAC address. + * + * @return Returns 0 if the MAC address is set. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len); + + /** + * @brief Obtains the device MAC address. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * @param mac Indicates the pointer to the MAC address. + * @param len Indicates the length of the MAC address. + * + * @return Returns 0 if the MAC address is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getDeviceMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len); + + /** + * @brief Obtains the frequencies supported by the 2.4 GHz or 5 GHz band. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * @param band Indicates the frequency band, either 2.4 GHz or 5 GHz. + * @param freqs Indicates the pointer to the supported frequencies. + * @param count Indicates the number of elements in the frequency array. + * @param num Indicates the number of supported frequencies. + * + * @return Returns 0 if the supported frequencies are obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getValidFreqsWithBand)(const struct IWiFiBaseFeature *baseFeature, int32_t band, int32_t *freqs, + uint32_t count, uint32_t *num); + + /** + * @brief Sets the transmit power. + * + * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}. + * @param power Indicates the transmit power to set. + * + * @return Returns 0 if the transmit power is set. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setTxPower)(const struct IWiFiBaseFeature *baseFeature, int32_t power); + + /** + * @brief Obtains the chip ID of the current driver. + * + * @param baseFeature Indicates the pointer to the {@link IWiFiBaseFeature}. + * @param chipId Indicates the pointer to the chip ID. + * + * @return Returns 0 if the chip ID is obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getChipId)(const struct IWiFiBaseFeature *baseFeature, uint8_t *chipId); + + /** + * @brief Obtains names of all the NICs of the current chip based on the chip ID. + * + * @param chipId Indicates the chip ID. + * @param ifNames Indicates the pointer to the NIC names. + * @param num Indicates the pointer to the number of NICs. + * + * @return Returns 0 if the NIC names are obtained. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getIfNamesByChipId)(const uint8_t chipId, char **ifNames, uint32_t *num); +}; + +/** + * @brief Initializes a specified basic feature. This function is called during {@link FeatureType} creation. + * + * @param fe Indicates the double pointer to the basic feature. + * + * @return Returns 0 if the operation is successful; returns a negative value representing {@link HDF_STATUS} + * if the operation fails. + * @return Returns a negative value representing {@link HDF_STATUS} if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitBaseFeature(struct IWiFiBaseFeature **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/en/device_api/hdi/wlan/wifi_hal_sta_feature.h b/en/device_api/hdi/wlan/wifi_hal_sta_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..49426167765d88b767f90ff81bd5a4156291288c --- /dev/null +++ b/en/device_api/hdi/wlan/wifi_hal_sta_feature.h @@ -0,0 +1,112 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. + * + * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface + * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, + * network devices, and power, and applying for, releasing, and moving network data buffers. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_sta_feature.h + * + * @brief Declares WLAN station (STA) features. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_STA_FEATURE_H +#define WIFI_HAL_STA_FEATURE_H + +#include "wifi_hal_base_feature.h" +#include "wifi_driver_client.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief Inherits the basic features of {@link IWiFiBaseFeature} and additionally provides the feature of setting + * scanning for a single MAC address. + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiSta { + /**< Basic features of {@link IWiFiBaseFeature} */ + struct IWiFiBaseFeature baseFeature; + + /** + * @brief Sets scanning for a single MAC address. + * + * @param staFeature Indicates the pointer to the STA feature, as described in {@link IWiFiSta}. + * @param scanMac Indicates the pointer to the MAC address to scan for. + * @param len Indicates the length of the MAC address. + * + * @return Returns 0 if scanning for the MAC address is successfully set. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setScanningMacAddress)(const struct IWiFiSta *staFeature, unsigned char *scanMac, uint8_t len); + + /** + * @brief wlan hal start scan. + * + * @param ifName The interface name. + * @param scan start scan with param. + * + * @return Returns 0 if start scan is successfully. + * @return Returns a negative value if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*startScan)(const char *ifName, WifiScan *scan); +}; + +/** + * @brief Initializes a specified STA feature. This function is called during STA {@link FeatureType} creation. + * + * @param fe Indicates the double pointer to the STA feature. + * + * @return Returns 0 if the operation is successful; + * @return Returns a negative value representing {@link HDF_STATUS} if the operation fails. + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitStaFeature(struct IWiFiSta **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal.h b/zh-cn/device_api/hdi/wlan/wifi_hal.h new file mode 100644 index 0000000000000000000000000000000000000000..2c84f5f01aa2b385a2cb18166cba81b4eb2580ed --- /dev/null +++ b/zh-cn/device_api/hdi/wlan/wifi_hal.h @@ -0,0 +1,288 @@ +/* + * Copyright (c) 2021-2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * + * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 + * + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal.h + * + * @brief 提供给wifi service的WLAN基本能力接口。 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_H +#define WIFI_HAL_H + +#include "wifi_hal_ap_feature.h" +#include "wifi_hal_sta_feature.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief 定义IWiFi回调函数的原型，监听异步事件。 + * + * @param event 回调传入的事件类型标识 + * @param data 回调传入的数据 + * @param ifName 网卡名字 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName); + +/** + * @brief HAL对wifi service提供的基本能力。 + * + * 用于创建HAL与驱动的通道，创建/获取/销毁WLAN特性等。 + * + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFi { + /** + * @brief 创建HAL和驱动之间的通道及获取驱动网卡信息。 + * + * @param iwifi IWiFi对象{@link IWiFi} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*start)(struct IWiFi *iwifi); + + /** + * @brief 销毁通道。 + * + * @param iwifi IWiFi对象{@link IWiFi} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*stop)(struct IWiFi *iwifi); + + /** + * @brief 获取该设备支持的WLAN特性（不考虑当前的使用状态）。 + * + * + * @param supType 保存当前设备支持的特性 + * @param size supType数组的长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getSupportFeature)(uint8_t *supType, uint32_t size); + + /** + * @brief 获取多网卡共存情况。 + * + * + * @param combo 基于芯片的能力保存当前所有支持的多网卡共存情况（比如支持AP，STA，P2P等不同组合的共存） + * @param size combo数组的长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getSupportCombo)(uint64_t *combo, uint32_t size); + + /** + * @brief 根据输入类型创建对应的特性{@link IWiFiBaseFeature}。 + * + * @param type 创建的feature类型 + * @param ifeature 获取创建的feature对象 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*createFeature)(int32_t type, struct IWiFiBaseFeature **ifeature); + + /** + * @brief 通过网络接口名字获取对应的特性。 + * + * @param ifName 网络接口的名字 + * @param ifeature 获取该网络接口名字的feature对象 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getFeatureByIfName)(const char *ifName, struct IWiFiBaseFeature **ifeature); + + /** + * @brief 注册IWiFi的回调函数，监听异步事件。 + * + * @param cbFunc 注册的回调函数 + * @param ifName 网卡名字 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*registerEventCallback)(CallbackFunc cbFunc, const char *ifName); + + /** + * @brief 去注册IWiFi的回调函数。 + + * @param cbFunc 去注册的回调函数 + * @param ifName 网卡名字 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*unregisterEventCallback)(CallbackFunc cbFunc, const char *ifName); + + /** + * @brief 销毁对应的特性。 + * + * @param ifeature 销毁的feature对象 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*destroyFeature)(struct IWiFiBaseFeature *ifeature); + + /** + * @brief WLAN驱动进行重置。 + * + * @param chipId 驱动进行重置对应的芯片ID + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*resetDriver)(const uint8_t chipId, const char *ifName); + + /** + * @brief 获取网络设备信息 + * + * @param netDeviceInfoResult 得到的网络设备信息 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getNetDevInfo)(struct NetDeviceInfoResult *netDeviceInfoResult); + + /** + * @brief 获取正在使用的功率模式 + * + * @param ifName 网卡名字 + * @param mode 功率模式 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getPowerMode)(const char *ifName, uint8_t *mode); + + /** + * @brief 设置功率模式 + * + * @param ifName 网卡名字 + * @param mode 功率模式 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setPowerMode)(const char *ifName, uint8_t mode); +}; + +/** + * @brief 创建IWiFi结构体，挂接{@link IWiFi}中能力接口。 + * + * @param wifiInstance HAL服务对象{@link IWiFi} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +int32_t WifiConstruct(struct IWiFi **wifiInstance); + +/** + * @brief 销毁IWiFi结构体。 + * + * @param wifiInstance HAL服务对象{@link IWiFi} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +int32_t WifiDestruct(struct IWiFi **wifiInstance); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..d7bf6ba9ae0fe691f70afc213760eacc7c5de020 --- /dev/null +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h @@ -0,0 +1,121 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * + * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_ap_feature.h + * + * @brief 提供WLAN的AP特性能力。 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_AP_FEATURE_H +#define WIFI_HAL_AP_FEATURE_H + +#include "wifi_hal_base_feature.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief 描述与AP连接的STA的基本信息 + * + * @since 1.0 + * @version 1.0 + */ +struct StaInfo { + /**< STA的MAC地址 */ + unsigned char mac[WIFI_MAC_ADDR_LENGTH]; +}; + +/** + * @brief 继承了{@link IWiFiBaseFeature}基本特性，并包含AP模式下获取连接STA的信息和设置国家码的功能。 + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiAp { + /**< 基本特性{@link IWiFiBaseFeature} */ + struct IWiFiBaseFeature baseFeature; + + /** + * @brief 获取连接上的所有STA的信息（目前只包含MAC地址）。 + * + * @param apFeature AP特性{@link IWiFiAp} + * @param staInfo 保存与AP连接的STA的基本信息 + * @param count staInfo结构体数组的元素个数 + * @param num 实际连接的STA的个数 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * @since 1.0 + * @version 1.0 + */ + int32_t (*getAsscociatedStas)(const struct IWiFiAp *apFeature, struct StaInfo *staInfo, + uint32_t count, uint32_t *num); + + /** + * @brief 设置国家码。 + * + * @param apFeature apFeature AP特性{@link IWiFiAp} + * @param code 设置的国家码 + * @param len 国家码长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setCountryCode)(const struct IWiFiAp *apFeature, const char *code, uint32_t len); +}; + +/** + * @brief 初始化AP特性。wifi service在创建AP类型的特性{@link FeatureType}时调用。 + * + * @param fe AP特性{@link IWiFiAp} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitApFeature(struct IWiFiAp **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..3ca64065e5899f1be8e900028085066a6c69e163 --- /dev/null +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h @@ -0,0 +1,253 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief WLAN 可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * + * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_base_feature.h + * + * @brief 提供WLAN基本特性能力。 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_BASE_FEATURE_H +#define WIFI_HAL_BASE_FEATURE_H + +#include + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief 网卡名称最大长度。 + * + * @since 1.0 + * @version 1.0 + */ +#define IFNAME_MAX_LEN 16 +/** + * @brief WLAN的MAC地址长度。 + * + * @since 1.0 + * @version 1.0 + */ +#define WIFI_MAC_ADDR_LENGTH 6 +/** + * @brief 访问失败。 + * + * @since 1.0 + * @version 1.0 + */ +#define ERR_UNAUTH_ACCESS (-6) + +/** + * @brief 特性的类型{@link FeatureType}。 + * + * @since 1.0 + * @version 1.0 + */ +typedef enum { + /**< 未定义的类型 */ + PROTOCOL_80211_IFTYPE_UNSPECIFIED, + /**< 特设型网络 */ + PROTOCOL_80211_IFTYPE_ADHOC, + /**< 工作站 */ + PROTOCOL_80211_IFTYPE_STATION, + /**< 接入点 */ + PROTOCOL_80211_IFTYPE_AP, + /**< 虚拟接入点 */ + PROTOCOL_80211_IFTYPE_AP_VLAN, + /**< 无线分布式系统 */ + PROTOCOL_80211_IFTYPE_WDS, + /**< 网络监听器 */ + PROTOCOL_80211_IFTYPE_MONITOR, + /**< 组网 */ + PROTOCOL_80211_IFTYPE_MESH_POINT, + /**< 对等网络客户端 */ + PROTOCOL_80211_IFTYPE_P2P_CLIENT, + /**< 对等网络群组所有者 */ + PROTOCOL_80211_IFTYPE_P2P_GO, + /**< 对等网络设备 */ + PROTOCOL_80211_IFTYPE_P2P_DEVICE, + /**< 网口的数目 */ + PROTOCOL_80211_IFTYPE_NUM, +} FeatureType; + +/** + * @brief 基本特性，包含获取网络接口名称，设置MAC地址，设置发射功率等公共能力接口。 + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiBaseFeature { + /**< 网卡名称 */ + char ifName[IFNAME_MAX_LEN]; + /**< 特性的类型{@link FeatureType} */ + int32_t type; + + /** + * @brief 获取网络接口的名字。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + const char *(*getNetworkIfaceName)(const struct IWiFiBaseFeature *baseFeature); + + /** + * @brief 获取特性的类型。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getFeatureType)(const struct IWiFiBaseFeature *baseFeature); + + /** + * @brief 设置MAC地址。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param mac 设置的MAC地址 + * @param len 设置的MAC地址长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len); + + /** + * @brief 获取设备的MAC地址。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param mac 获得的MAC地址 + * @param len 获得的MAC地址长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getDeviceMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len); + + /** + * @brief 获取指定频段（2.4G或者5G）下支持的频率。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param band 指定的一个频段 + * @param freqs 保存支持的频率 + * @param count 频率数组的元素个数 + * @param num 实际支持的频率个数 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getValidFreqsWithBand)(const struct IWiFiBaseFeature *baseFeature, int32_t band, int32_t *freqs, + uint32_t count, uint32_t *num); + + /** + * @brief 设置发射功率。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param power 设置的发射功率 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setTxPower)(const struct IWiFiBaseFeature *baseFeature, int32_t power); + + /** + * @brief 获得当前驱动的芯片ID。 + * + * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param chipId 获得的芯片ID + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getChipId)(const struct IWiFiBaseFeature *baseFeature, uint8_t *chipId); + + /** + * @brief 通过芯片ID获得当前芯片所有的网卡名。 + * + * @param chipId 驱动进行重置对应的芯片ID + * @param ifNames 网卡名字 + * @param num 网卡的数量 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*getIfNamesByChipId)(const uint8_t chipId, char **ifNames, uint32_t *num); +}; + +/** + * @brief 初始化基本特性。用于wifi service在创建任何类型的特性{@link FeatureType}时。 + * + * @param fe 基本特性{@link IWiFiBaseFeature} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitBaseFeature(struct IWiFiBaseFeature **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */ diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h new file mode 100644 index 0000000000000000000000000000000000000000..3f54c692426a027ca7b5fe7d6058ab6837582055 --- /dev/null +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h @@ -0,0 +1,111 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup WLAN + * @{ + * + * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * + * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 + * + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file wifi_hal_sta_feature.h + * + * @brief 提供WLAN的sta特性能力。 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef WIFI_HAL_STA_FEATURE_H +#define WIFI_HAL_STA_FEATURE_H + +#include "wifi_hal_base_feature.h" +#include "wifi_driver_client.h" + +#ifdef __cplusplus +#if __cplusplus +extern "C" { +#endif +#endif + +/** + * @brief 继承了{@link IWiFiBaseFeature}基本特性，额外包含设置扫描单个MAC地址功能。 + * + * + * @since 1.0 + * @version 1.0 + */ +struct IWiFiSta { + /**< 基本特性{@link IWiFiBaseFeature} */ + struct IWiFiBaseFeature baseFeature; + + /** + * @brief 设置扫描单个MAC地址。 + * + * @param staFeature STA特性{@link IWiFiSta} + * @param scanMac 设置STA扫描的MAC地址 + * @param len MAC地址的长度 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*setScanningMacAddress)(const struct IWiFiSta *staFeature, unsigned char *scanMac, uint8_t len); + + /** + * @brief 启动扫描 + * + * @param ifName 网卡名字 + * @param scan 扫描参数 + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*startScan)(const char *ifName, WifiScan *scan); +}; + +/** + * @brief 初始化STA特性。wifi service在创建STA类型的特性{@link FeatureType}时调用。 + * + * @param fe STA特性{@link IWiFiSta} + * + * @return 如果操作成功，则返回0。 + * @return 如果操作失败，则返回负值。 + * + * @since 1.0 + * @version 1.0 + */ +int32_t InitStaFeature(struct IWiFiSta **fe); + +#ifdef __cplusplus +#if __cplusplus +} +#endif +#endif + +#endif +/** @} */