1/*
2 * Copyright (c) 2021 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup WLAN
18 * @{
19 *
20 * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation.
21 *
22 * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface
23 * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips,
24 * network devices, and power, and applying for, releasing, and moving network data buffers.
25 *
26 * @since 1.0
27 * @version 1.0
28 */
29
30/**
31 * @file wifi_hal_base_feature.h
32 *
33 * @brief Declares basic WLAN features.
34 *
35 * @since 1.0
36 * @version 1.0
37 */
38
39#ifndef WIFI_HAL_BASE_FEATURE_H
40#define WIFI_HAL_BASE_FEATURE_H
41
42#include <stdint.h>
43
44#ifdef __cplusplus
45#if __cplusplus
46extern "C" {
47#endif
48#endif
49
50/**
51 * @brief Indicates the maximum length of the network interface name.
52 *
53 * @since 1.0
54 * @version 1.0
55 */
56#define IFNAME_MAX_LEN 16
57/**
58 * @brief Indicates the length of the MAC address.
59 *
60 * @since 1.0
61 * @version 1.0
62 */
63#define WIFI_MAC_ADDR_LENGTH 6
64/**
65 * @brief Defines the access failure error.
66 *
67 * @since 1.0
68 * @version 1.0
69 */
70#define ERR_UNAUTH_ACCESS (-6)
71
72/**
73 * @brief Enumerates feature types.
74 *
75 * @since 1.0
76 * @version 1.0
77 */
78typedef enum {
79    PROTOCOL_80211_IFTYPE_UNSPECIFIED,                         /**< Unspecified type */
80    PROTOCOL_80211_IFTYPE_ADHOC,                               /**< Ad hoc network */
81    PROTOCOL_80211_IFTYPE_STATION,                             /**< Station */
82    PROTOCOL_80211_IFTYPE_AP,                                  /**< Access point (AP) */
83    PROTOCOL_80211_IFTYPE_AP_VLAN,                             /**< Virtual AP */
84    PROTOCOL_80211_IFTYPE_WDS,                                 /**< Wireless distributed system */
85    PROTOCOL_80211_IFTYPE_MONITOR,                             /**< Listening */
86    PROTOCOL_80211_IFTYPE_MESH_POINT,                          /**< Mesh network */
87    PROTOCOL_80211_IFTYPE_P2P_CLIENT,                          /**< P2P client */
88    PROTOCOL_80211_IFTYPE_P2P_GO,                              /**< P2P group owner */
89    PROTOCOL_80211_IFTYPE_P2P_DEVICE,                          /**< P2P device */
90    PROTOCOL_80211_IFTYPE_NUM,                                 /**< Number of network ports */
91} FeatureType;
92
93/**
94 * @brief Defines basic WLAN features, such as obtaining the network interface name, setting the MAC address,
95 * and setting the transmit power.
96 *
97 * @since 1.0
98 * @version 1.0
99 */
100struct IWiFiBaseFeature {
101    char ifName[IFNAME_MAX_LEN];  /**< Network interface name */
102    int32_t type;                 /**< Feature type, as enumerated in {@link FeatureType} */
103
104    /**
105     * @brief Obtains the name of a network interface.
106     *
107     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
108     *
109     * @return Returns network interface name if the network interface name is obtained;
110     *         returns NULL otherwise.
111     *
112     * @since 1.0
113     * @version 1.0
114     */
115    const char *(*getNetworkIfaceName)(const struct IWiFiBaseFeature *baseFeature);
116
117    /**
118     * @brief Obtains the type of a basic feature.
119     *
120     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
121     *
122     * @return Returns feature type if the feature type is obtained; returns a negative value otherwise.
123     *
124     * @since 1.0
125     * @version 1.0
126     */
127    int32_t (*getFeatureType)(const struct IWiFiBaseFeature *baseFeature);
128
129    /**
130     * @brief Sets the MAC address.
131     *
132     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
133     * @param mac Indicates the pointer to the MAC address.
134     * @param len Indicates the length of the MAC address.
135     *
136     * @return Returns <b>0</b> if the MAC address is set; returns a negative value otherwise.
137     *
138     * @since 1.0
139     * @version 1.0
140     */
141    int32_t (*setMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len);
142
143    /**
144     * @brief Obtains the device MAC address.
145     *
146     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
147     * @param mac Indicates the pointer to the MAC address.
148     * @param len Indicates the length of the MAC address.
149     *
150     * @return Returns <b>0</b> if the MAC address is obtained; returns a negative value otherwise.
151     *
152     * @since 1.0
153     * @version 1.0
154     */
155    int32_t (*getDeviceMacAddress)(const struct IWiFiBaseFeature *baseFeature, unsigned char *mac, uint8_t len);
156
157    /**
158     * @brief Obtains the frequencies supported by the 2.4 GHz or 5 GHz band.
159     *
160     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
161     * @param band Indicates the frequency band, either 2.4 GHz or 5 GHz.
162     * @param freqs Indicates the pointer to the supported frequencies.
163     * @param count Indicates the number of elements in the frequency array.
164     * @param num Indicates the number of supported frequencies.
165     *
166     * @return Returns <b>0</b> if the supported frequencies are obtained; returns a negative value otherwise.
167     *
168     * @since 1.0
169     * @version 1.0
170     */
171    int32_t (*getValidFreqsWithBand)(const struct IWiFiBaseFeature *baseFeature, int32_t band, int32_t *freqs,
172        uint32_t count, uint32_t *num);
173
174    /**
175     * @brief Sets the transmit power.
176     *
177     * @param baseFeature Indicates the pointer to the basic feature, as described in {@link IWiFiBaseFeature}.
178     * @param power Indicates the transmit power to set.
179     *
180     * @return Returns <b>0</b> if the transmit power is set; returns a negative value otherwise.
181     *
182     * @since 1.0
183     * @version 1.0
184     */
185    int32_t (*setTxPower)(const struct IWiFiBaseFeature *baseFeature, int32_t power);
186
187    /**
188     * @brief Obtains the chip ID of the current driver.
189     *
190     * @param baseFeature Indicates the pointer to the {@link IWiFiBaseFeature}.
191     * @param chipId Indicates the pointer to the chip ID.
192     *
193     * @return Returns <b>0</b> if the chip ID is obtained; returns a negative value otherwise.
194     *
195     * @since 1.0
196     * @version 1.0
197     */
198    int32_t (*getChipId)(const struct IWiFiBaseFeature *baseFeature, uint8_t *chipId);
199
200    /**
201     * @brief Obtains names of all the NICs of the current chip based on the chip ID.
202     *
203     * @param chipId Indicates the chip ID.
204     * @param ifNames Indicates the pointer to the NIC names.
205     * @param num Indicates the pointer to the number of NICs.
206     *
207     * @return Returns <b>0</b> if the NIC names are obtained; returns a negative value otherwise.
208     *
209     * @since 1.0
210     * @version 1.0
211     */
212    int32_t (*getIfNamesByChipId)(const uint8_t chipId, char **ifNames, uint32_t *num);
213
214    /**
215     * @brief reset to factory mac address(permanent hardware address).
216     *
217     * @param ifName Indicates the NIC name.
218     *
219     * @return Returns <b>0</b> if the operation is successful.
220     * @return Returns a negative value if the operation fails.
221     *
222     * @since 4.1
223     * @version 1.2
224     */
225    int32_t (*resetToFactoryMacAddress)(const char *ifNames);
226};
227
228/**
229 * @brief Initializes a specified basic feature. This function is called during {@link FeatureType} creation.
230 *
231 * @param fe Indicates the double pointer to the basic feature.
232 *
233 * @return Returns <b>0</b> if the operation is successful; returns a negative value representing {@link HDF_STATUS}
234 * if the operation fails.
235 *
236 * @since 1.0
237 * @version 1.0
238 */
239int32_t InitBaseFeature(struct IWiFiBaseFeature **fe);
240
241#ifdef __cplusplus
242#if __cplusplus
243}
244#endif
245#endif
246
247#endif
248/** @} */
249