1 /*
2  * Copyright (c) 2021-2023 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.h
32  *
33  * @brief Declares APIs for basic WLAN features.
34  *
35  * @since 1.0
36  * @version 1.0
37  */
38 
39 #ifndef WIFI_HAL_H
40 #define WIFI_HAL_H
41 
42 #include "wifi_hal_ap_feature.h"
43 #include "wifi_hal_sta_feature.h"
44 #include "wifi_hal_p2p_feature.h"
45 
46 #ifdef __cplusplus
47 #if __cplusplus
48 extern "C" {
49 #endif
50 #endif
51 
52 /**
53  * @brief Defines a callback to listen for <b>IWiFi</b> asynchronous events.
54  *
55  * @param event Indicates the event type passed to the callback.
56  * @param data Indicates the pointer to the data passed to the callback.
57  * @param ifName The interface name.
58  *
59  * @return Returns <b>0</b> if the <b>IWiFi</b> callback is defined; returns a negative value otherwise.
60  *
61  * @since 1.0
62  * @version 1.0
63  */
64 typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName);
65 
66 /**
67  * @brief Defines a hid2d callback to listen for <b>IWiFi</b> asynchronous events.
68  *
69  * @param recvMsg Indicates message received.
70  * @param recvMsgLen Indicates the length of message.
71  *
72  * @return Returns <b>0</b> if the <b>IWiFi</b> hid2d callback is defined; returns a negative value otherwise.
73  *
74  * @since 1.0
75  * @version 1.0
76  */
77 typedef int32_t (*Hid2dCallbackFunc)(const uint8_t *recvMsg, uint32_t recvMsgLen);
78 
79 /**
80  * @brief Defines the basic WLAN features provided by the hardware abstraction layer (HAL).
81  *
82  * The basic features include creating and stopping a channel between the HAL and the WLAN driver,
83  * and creating, obtaining, and destroying WLAN features.
84  *
85  * @since 1.0
86  * @version 1.0
87  */
88 struct IWiFi {
89     /**
90      * @brief Creates a channel between the HAL and the WLAN driver and obtains the driver NIC information.
91      *
92      * @param iwifi Indicates the pointer to the {@link IWiFi} object.
93      *
94      * @return Returns <b>0</b> if the channel is created and the driver NIC information is obtained;
95      * returns a negative value otherwise.
96      *
97      * @since 1.0
98      * @version 1.0
99      */
100     int32_t (*start)(struct IWiFi *iwifi);
101 
102     /**
103      * @brief Stops the channel between the HAL and the WLAN driver.
104      *
105      * @param iwifi Indicates the pointer to the {@link IWiFi} object.
106      *
107      * @return Returns <b>0</b> if the channel is stopped; returns a negative value otherwise.
108      *
109      * @since 1.0
110      * @version 1.0
111      */
112     int32_t (*stop)(struct IWiFi *iwifi);
113 
114     /**
115      * @brief Obtains the WLAN features available for the device no matter whether it works as an AP,
116      * STA, or P2P server/client.
117      *
118      * @param supType Indicates the pointer to the WLAN features available for the device.
119      * @param size Indicates the length of the <b>supType</b> array.
120      *
121      * @return Returns <b>0</b> if the WLAN features are obtained; returns a negative value otherwise.
122      *
123      * @since 1.0
124      * @version 1.0
125      */
126     int32_t (*getSupportFeature)(uint8_t *supType, uint32_t size);
127 
128     /**
129      * @brief Obtains the WLAN features available for the device that plays different roles simultaneously
130      * (any combination of AP, STA, and P2P server/client).
131      *
132      * @param combo Indicates the pointer to WLAN features available for the device.
133      * @param size Indicates the length of the <b>combo</b> array.
134      *
135      * @return Returns <b>0</b> if the WLAN features are obtained; returns a negative value otherwise.
136      *
137      * @since 1.0
138      * @version 1.0
139      */
140     int32_t (*getSupportCombo)(uint64_t *combo, uint32_t size);
141 
142     /**
143      * @brief Creates an {@link IWiFiBaseFeature} object of a specified type.
144      *
145      * @param type Indicates the feature type.
146      * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object.
147      *
148      * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is created; returns a negative value otherwise.
149      *
150      * @since 1.0
151      * @version 1.0
152      */
153     int32_t (*createFeature)(int32_t type, struct IWiFiBaseFeature **ifeature);
154 
155     /**
156      * @brief Obtains an {@link IWiFiBaseFeature} object based on a specified network interface name.
157      *
158      * @param ifName Indicates the pointer to the network interface name.
159      * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object.
160      *
161      * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is obtained; returns a negative value otherwise.
162      *
163      * @since 1.0
164      * @version 1.0
165      */
166     int32_t (*getFeatureByIfName)(const char *ifName, struct IWiFiBaseFeature **ifeature);
167 
168     /**
169      * @brief Registers a callback to listen for <b>IWiFi</b> asynchronous events.
170      *
171      * @param cbFunc Indicates the callback to register.
172      * @param ifName Indicates the pointer to the network interface name.
173      *
174      * @return Returns <b>0</b> if the callback is registered; returns a negative value otherwise.
175      *
176      * @since 1.0
177      * @version 1.0
178      */
179     int32_t (*registerEventCallback)(CallbackFunc cbFunc, const char *ifName);
180 
181     /**
182      * @brief Deregisters an <b>IWiFi</b> callback.
183 
184      * @param cbFunc Indicates the callback to register.
185      * @param ifName Indicates the pointer to the network interface name.
186      *
187      * @return Returns <b>0</b> if the <b>IWiFi</b> callback is deregistered; returns a negative value otherwise.
188      *
189      * @since 1.0
190      * @version 1.0
191      */
192     int32_t (*unregisterEventCallback)(CallbackFunc cbFunc, const char *ifName);
193 
194     /**
195      * @brief Destroys a specified {@link IWiFiBaseFeature} object.
196      *
197      * @param ifeature Indicates the pointer to the {@link IWiFiBaseFeature} object to destroy.
198      *
199      * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is destroyed; returns a negative value otherwise.
200      *
201      * @since 1.0
202      * @version 1.0
203      */
204     int32_t (*destroyFeature)(struct IWiFiBaseFeature *ifeature);
205 
206     /**
207      * @brief Resets the WLAN driver with a specified chip ID.
208      *
209      * @param chipId Indicates the chip ID.
210      *
211      * @return Returns <b>0</b> if the WLAN driver is reset; returns a negative value otherwise.
212      *
213      * @since 1.0
214      * @version 1.0
215      */
216     int32_t (*resetDriver)(const uint8_t chipId, const char *ifName);
217 
218     /**
219      * @brief get net device infos.
220      *
221      * @param netDeviceInfoResult get net device infos.
222      *
223      * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise.
224      *
225      * @since 1.0
226      * @version 1.0
227      */
228     int32_t (*getNetDevInfo)(struct NetDeviceInfoResult *netDeviceInfoResult);
229 
230     /**
231      * @brief Obtains the power mode which is being used.
232      *
233      * @param ifName Indicates the pointer to the network interface name.
234      * @param mode Indicates the pointer to the power mode.
235      *
236      * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise.
237      *
238      * @since 1.0
239      * @version 1.0
240      */
241     int32_t (*getPowerMode)(const char *ifName, uint8_t *mode);
242 
243     /**
244      * @brief Set the power mode.
245      *
246      * @param ifName Indicates the pointer to the network interface name.
247      * @param mode The value set to power mode.
248      *
249      * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise.
250      *
251      * @since 1.0
252      * @version 1.0
253      */
254     int32_t (*setPowerMode)(const char *ifName, uint8_t mode);
255 
256     /**
257      * @brief Start channel measurement(asynchronous interface, need call getChannelMeasResult to
258      * get measurement results).
259      *
260      * @param ifName Indicates the pointer to the network interface name.
261      * @param measParam Parameters of the measurement channel.
262      *
263      * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise.
264      *
265      * @since 3.2
266      * @version 1.0
267      */
268     int32_t (*startChannelMeas)(const char *ifName, const struct MeasParam *measParam);
269 
270     /**
271      * @brief Obtaining channel measurement results.
272      *
273      * @param ifName Indicates the pointer to the network interface name.
274      * @param measResult Channel measurement result data.
275      *
276      * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise.
277      *
278      * @since 3.2
279      * @version 1.0
280      */
281     int32_t (*getChannelMeasResult)(const char *ifName, struct MeasResult *measResult);
282 
283     /**
284      * @brief Config projection screen parameters.
285      *
286      * @param ifName Indicates the pointer to the network interface name.
287      * @param param Indicates the parameters used to config projection screen.
288      *
289      * @return Returns <b>0</b> if  Config projection screen parameters successful; returns a negative value otherwise.
290      *
291      * @since 3.2
292      * @version 1.0
293      */
294     int32_t (*setProjectionScreenParam)(const char *ifName, const ProjectionScreenParam *param);
295 
296     /**
297      * @brief Send ioctl command to driver.
298      *
299      * @param ifName Indicates the pointer to the network interface name.
300      * @param cmdId Indicates the command identity document.
301      * @param paramBuf Indicates the paramter send to driver.
302      * @param paramBufLen Indicates the length of parameter.
303      *
304      * @return Returns <b>0</b> if  Send ioctl command successful; returns a negative value otherwise.
305      *
306      * @since 3.2
307      * @version 1.0
308      */
309     int32_t (*sendCmdIoctl)(const char *ifName, int32_t cmdId, const int8_t *paramBuf, uint32_t paramBufLen);
310 
311     /**
312      * @brief Registers a hid2d callback to listen for <b>IWiFi</b> asynchronous events.
313      *
314      * @param func Indicates the callback function to register.
315      * @param ifName Indicates the pointer to the network interface name.
316      *
317      * @return Returns <b>0</b> if the hid2d callback is registered; returns a negative value otherwise.
318      *
319      * @since 3.2
320      * @version 1.0
321      */
322     int32_t (*registerHid2dCallback)(Hid2dCallback func, const char *ifName);
323 
324     /**
325      * @brief Unegisters a hid2d callback to listen for <b>IWiFi</b> asynchronous events.
326      *
327      * @param func Indicates the callback function to unregister.
328      * @param ifName Indicates the pointer to the network interface name.
329      *
330      * @return Returns <b>0</b> if the hid2d callback is unregistered; returns a negative value otherwise.
331      *
332      * @since 3.2
333      * @version 1.0
334      */
335     int32_t (*unregisterHid2dCallback)(Hid2dCallback func, const char *ifName);
336 
337     /**
338      * @brief Get station information.
339      *
340      * @param ifName Indicates the pointer to the network interface name.
341      * @param info Indicates the Station information.
342      * @param mac Indicates the mac address of station.
343      * @param param Indicates the length of mac address.
344      *
345      * @return Returns <b>0</b> if get station information successful; returns a negative value otherwise.
346      *
347      * @since 3.2
348      * @version 1.0
349      */
350     int32_t (*getStationInfo)(const char *ifName, StationInfo *info, const uint8_t *mac, uint32_t macLen);
351 
352     /**
353      * @brief Send action frame data.
354      *
355      * @param ifName Indicates the NIC name.
356      * @param freq Indicates the send channel frequency.
357      * @param frameData Indicates the action frame data.
358      * @param frameDataLen Indicates the action frame data length.
359      *
360      * @return Returns <b>0</b> if get station information successful; returns a negative value otherwise.
361      *
362      * @since 4.1
363      * @version 1.2
364      */
365     int32_t (*sendActionFrame)(const char *ifName, uint32_t freq, const uint8_t *frameData,
366         uint32_t frameDataLen);
367 
368     /**
369      * @brief Register action frame receiver.
370      *
371      * @param ifName Indicates the NIC name.
372      * @param match Indicates the data matching action frame.
373      * @param matchLen Indicates the matching data length.
374      *
375      * @return Returns <b>0</b> if get station information successful; returns a negative value otherwise.
376      *
377      * @since 4.1
378      * @version 1.2
379      */
380     int32_t (*registerActionFrameReceiver)(const char *ifName, const uint8_t *match, uint32_t matchLen);
381 
382     /**
383      * @brief set power save manager mode.
384      *
385      * @param ifName Indicates the NIC name.
386      * @param frequency Indicates connected ap frequency.
387      * @param mode Indicates power save mode, 3(enable power save), 4(disable power save).
388      *
389      * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
390      *
391      * @since 4.1
392      * @version 1.2
393      */
394     int32_t (*setPowerSaveMode)(const char *ifName, int32_t frequency, int32_t mode);
395 
396     /**
397      * @brief set dpi mark rule.
398      *
399      * @param uid Indicates target app uid.
400      * @param protocol Indicates target protocol type, tcp/udp.
401      * @param enable Indicates enable/disable dpi mark rule.
402      *
403      * @return Returns <b>0</b> if the operation is successful; returns a negative value if the operation fails.
404      *
405      * @since 4.1
406      * @version 1.2
407      */
408     int32_t (*setDpiMarkRule)(int32_t uid, int32_t protocol, int32_t enable);
409 };
410 
411 /**
412  * @brief Creates an {@link IWiFi} structure.
413  *
414  * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure.
415  *
416  * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
417  *
418  * @since 1.0
419  * @version 1.0
420  */
421 int32_t WifiConstruct(struct IWiFi **wifiInstance);
422 
423 /**
424  * @brief Destroys a specified {@link IWiFi} structure.
425  *
426  * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure.
427  *
428  * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise.
429  *
430  * @since 1.0
431  * @version 1.0
432  */
433 int32_t WifiDestruct(struct IWiFi **wifiInstance);
434 
435 #ifdef __cplusplus
436 #if __cplusplus
437 }
438 #endif
439 #endif
440 
441 #endif
442 /** @} */
443