1/*
2 * Copyright (c) 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 APIs for the upper-layer WLAN service.
21 *
22 * You can use the APIs to enable or disable a WLAN hotspot, scan for hotspots, connect to a WLAN hotspot,
23 * manage WLAN chips, network devices, and power, and apply for, release, and move network data buffers.
24 *
25 * @since 3.2
26 * @version 1.1
27 */
28
29/**
30 * @file IWlanInterface.idl
31 *
32 * @brief Provides APIs to enable or disable a WLAN hotspot, scan for hotspots, connect to or disconnect from a WLAN hotspot,
33 * set the country code, and manage network devices.
34 *
35 * @since 3.2
36 * @version 1.1
37 */
38
39/**
40 * @brief Defines the package path of the WLAN module interface.
41 *
42 * @since 3.2
43 * @version 1.1
44 */
45package ohos.hdi.wlan.v1_1;
46
47import ohos.hdi.wlan.v1_1.WlanTypes;
48import ohos.hdi.wlan.v1_1.IWlanCallback;
49
50/**
51 * @brief Defines an interface for the upper-layer WLAN service.
52 *
53 * @since 3.2
54 * @version 1.1
55 */
56
57interface IWlanInterface {
58    /**
59     * @brief Creates a channel between the HAL and the WLAN driver and obtains the driver network interface card (NIC)
60     * information. This function must be called after an <b>IWiFi</b> instance is created.
61     *
62     * @return Returns <b>0</b> if the operation is successful.
63     * @return Returns a negative value if the operation fails.
64     *
65     * @since 3.2
66     * @version 1.1
67     */
68    Start();
69
70    /**
71     * @brief Destroys the channel between the HAL and the WLAN driver. This function must be called before an <b>IWiFi</b>
72     * instance is destroyed.
73     *
74     * @return Returns <b>0</b> if the operation is successful.
75     * @return Returns a negative value if the operation fails.
76     *
77     * @since 3.2
78     * @version 1.1
79     */
80    Stop();
81
82    /**
83     * @brief Creates a <b>Feature</b> object based on the specified type.
84     *
85     * @param type Indicates the type of the <b>Feature</b> object to create, 2:Station, 3:AP.
86     * @param ifeature Indicates the <b>Feature</b> object created.
87     *
88     * @return Returns <b>0</b> if the operation is successful.
89     * @return Returns a negative value if the operation fails.
90     *
91     * @since 3.2
92     * @version 1.1
93     */
94    CreateFeature([in] int type, [out] struct HdfFeatureInfo ifeature);
95
96    /**
97     * @brief Destroys a <b>Feature</b> object.
98     *
99     * @param ifeature Indicates the <b>Feature</b> object to destroy.
100     *
101     * @return Returns <b>0</b> if the operation is successful.
102     * @return Returns a negative value if the operation fails.
103     *
104     * @since 3.2
105     * @version 1.1
106     */
107    DestroyFeature([in] struct HdfFeatureInfo ifeature);
108
109    /**
110     * @brief Obtains information about all STAs connected to this AP. Currently, the STA information contains only the MAC address.
111     *
112     * @param ifeature Indicates the <b>Feature</b> object.
113     * @param staInfo Indicates the basic information about the STAs connected to the AP.
114     * @param num Indicates the number of connected STAs.
115     *
116     * @return Returns <b>0</b> if the operation is successful.
117     * @return Returns a negative value if the operation fails.
118     *
119     * @since 3.2
120     * @version 1.1
121     */
122    GetAssociatedStas([in] struct HdfFeatureInfo ifeature, [out] struct HdfStaInfo[] staInfo, [out] unsigned int num);
123
124    /**
125     * @brief Obtains the chip ID of the current driver.
126     *
127     * @param ifeature Indicates the <b>Feature</b> object.
128     * @param chipId Indicates the chip ID obtained.
129     *
130     * @return Returns <b>0</b> if the operation is successful.
131     * @return Returns a negative value if the operation fails.
132     *
133     * @since 3.2
134     * @version 1.1
135     */
136    GetChipId([in] struct HdfFeatureInfo ifeature, [out] unsigned char chipId);
137
138    /**
139     * @brief Obtains the device MAC address.
140     *
141     * @param ifeature Indicates the <b>Feature</b> object.
142     * @param mac Indicates the MAC address obtained.
143     * @param len Indicates the length of the MAC address, the value is fiexed to 6.
144     *
145     * @return Returns <b>0</b> if the operation is successful.
146     * @return Returns a negative value if the operation fails.
147     *
148     * @since 3.2
149     * @version 1.1
150     */
151    GetDeviceMacAddress([in] struct HdfFeatureInfo ifeature, [out] unsigned char[] mac, [in] unsigned char len);
152
153    /**
154     * @brief Obtains the <b>Feature</b> object based on the specified NIC name.
155     *
156     * @param ifName Indicates the NIC name.
157     * @param ifeature Indicates the <b>Feature</b> object obtained.
158     *
159     * @return Returns <b>0</b> if the operation is successful.
160     * @return Returns a negative value if the operation fails.
161     *
162     * @since 3.2
163     * @version 1.1
164     */
165    GetFeatureByIfName([in] String ifName, [out] struct HdfFeatureInfo ifeature);
166
167    /**
168     * @brief Obtains the type of a <b>Feature</b> object.
169     *
170     * @param ifeature Indicates the <b>Feature</b> object.
171     * @param featureType Indicates the type of the <b>Feature</b> object obtained.
172     *
173     * @return Returns <b>0</b> if the operation is successful.
174     * @return Returns a negative value if the operation fails.
175     *
176     * @since 3.2
177     * @version 1.1
178     */
179    GetFeatureType([in] struct HdfFeatureInfo ifeature, [out] int featureType);
180
181    /**
182     * @brief Obtains the frequencies supported by the specified frequency band.
183     *
184     * @param ifeature Indicates the <b>Feature</b> object.
185     * @param wifiInfo Indicates the frequency info, wifiInfo.band, 0:2.4 GHz; 1:5 GHz. wifiInfo.size, minimum is 14.
186     * @param freq Indicates the supported frequencies obtained.
187     *
188     * @return Returns <b>0</b> if the operation is successful.
189     * @return Returns a negative value if the operation fails.
190     *
191     * @since 3.2
192     * @version 1.1
193     */
194    GetFreqsWithBand([in] struct HdfFeatureInfo ifeature, [in] struct HdfWifiInfo wifiInfo, [out] int[] freq);
195
196    /**
197     * @brief Obtains all the NIC names of a chip.
198     *
199     * @param chipId Indicates the ID of the target chip.
200     * @param ifNames Indicates the NIC names obtained.
201     * @param num Indicates the number of NICs.
202     *
203     * @return Returns <b>0</b> if the operation is successful.
204     * @return Returns a negative value if the operation fails.
205     *
206     * @since 3.2
207     * @version 1.1
208     */
209    GetIfNamesByChipId([in] unsigned char chipId, [out] String ifName, [out] unsigned int num);
210
211    /**
212     * @brief Obtains the NIC name based on the <b>Feature</b> object.
213     *
214     * @param ifeature Indicates the <b>Feature</b> object.
215     * @param ifName Indicates the NIC name.
216     *
217     * @return Returns <b>0</b> if the operation is successful.
218     * @return Returns a negative value if the operation fails.
219     *
220     * @since 3.2
221     * @version 1.1
222     */
223    GetNetworkIfaceName([in] struct HdfFeatureInfo ifeature, [out] String ifName);
224
225    /**
226     * @brief Obtains information about the coexistence of multiple NICs.
227     *
228     * @param combo Indicates the information obtained, for example, different combinations of the AP, STA, and P2P.
229     *
230     * @return Returns <b>0</b> if the operation is successful.
231     * @return Returns a negative value if the operation fails.
232     *
233     * @since 3.2
234     * @version 1.1
235     */
236    GetSupportCombo([out] unsigned long combo);
237
238    /**
239     * @brief Obtains the WLAN features supported by the device, regardless of the device status.
240     *
241     * @param supType Indicates the features obtained.
242     *
243     * @return Returns <b>0</b> if the operation is successful.
244     * @return Returns a negative value if the operation fails.
245     *
246     * @since 3.2
247     * @version 1.1
248     */
249    GetSupportFeature([out] unsigned char[] supType);
250
251    /**
252     * @brief Registers a callback to listen for asynchronous events.
253     *
254     * @param cbFunc Indicates the callback to register.
255     * @param ifName Indicates the NIC name.
256     *
257     * @return Returns <b>0</b> if the operation is successful.
258     * @return Returns a negative value if the operation fails.
259     *
260     * @since 3.2
261     * @version 1.1
262     */
263    RegisterEventCallback([in] IWlanCallback cbFunc, [in] String ifName);
264
265    /**
266     * @brief Unregisters a callback.
267     *
268     * @param cbFunc Indicates the callback to unregister.
269     * @param ifName Indicates the NIC name.
270     *
271     * @return Returns <b>0</b> if the operation is successful.
272     * @return Returns a negative value if the operation fails.
273     *
274     * @since 3.2
275     * @version 1.1
276     */
277    UnregisterEventCallback([in] IWlanCallback cbFunc, [in] String ifName);
278
279    /**
280     * @brief Restarts the WLAN driver based on the specified chip ID.
281     *
282     * @param chipId Indicates the ID of the chip whose driver is to be restarted.
283     * @param ifName Indicates the NIC name.
284     *
285     * @return Returns <b>0</b> if the operation is successful.
286     * @return Returns a negative value if the operation fails.
287     *
288     * @since 3.2
289     * @version 1.1
290     */
291    ResetDriver([in] unsigned char chipId, [in] String ifName);
292
293    /**
294     * @brief Sets a country code.
295     *
296     * The country code indicates the country where the AP radio is located. It specifies the AP radio features,
297     * including the transmit power and supported channels of the AP, ensuring that radio attributes of APs comply
298     * with local laws and regulations.
299     *
300     * @param ifeature Indicates the <b>Feature</b> object.
301     * @param code Indicates the country code to set.
302     * @param len Indicates the length of the country code.
303     *
304     * @return Returns <b>0</b> if the operation is successful.
305     * @return Returns a negative value if the operation fails.
306     *
307     * @since 3.2
308     * @version 1.1
309     */
310    SetCountryCode([in] struct HdfFeatureInfo ifeature, [in] String code, [in] unsigned int len);
311
312    /**
313     * @brief Sets a MAC address for an NIC.
314     *
315     * @param ifeature Indicates the <b>Feature</b> object.
316     * @param mac Indicates the MAC address to set.
317     *
318     * @return Returns <b>0</b> if the operation is successful.
319     * @return Returns a negative value if the operation fails.
320     *
321     * @since 3.2
322     * @version 1.1
323     */
324    SetMacAddress([in] struct HdfFeatureInfo ifeature, [in] unsigned char[] mac);
325
326    /**
327     * @brief Scans a single MAC address.
328     *
329     * @param ifeature Indicates the <b>Feature</b> object.
330     * @param scanMac Indicates the MAC address to be scanned by the STA.
331     *
332     * @return Returns <b>0</b> if the operation is successful.
333     * @return Returns a negative value if the operation fails.
334     *
335     * @since 3.2
336     * @version 1.1
337     */
338    SetScanningMacAddress([in] struct HdfFeatureInfo ifeature, [in] unsigned char[] scanMac);
339
340    /**
341     * @brief Sets the transmit power.
342     *
343     * @param ifeature Indicates the <b>Feature</b> object.
344     * @param power Indicates the transmit power to set.
345     *
346     * @return Returns <b>0</b> if the operation is successful.
347     * @return Returns a negative value if the operation fails.
348     *
349     * @since 3.2
350     * @version 1.1
351     */
352    SetTxPower([in] struct HdfFeatureInfo ifeature, [in] int power);
353
354    /**
355     * @brief Obtains network device information, such as the device index, NIC name, and MAC address.
356     *
357     * @param netDeviceInfoResult Indicates the network device information obtained.
358     *
359     * @return Returns <b>0</b> if the operation is successful.
360     * @return Returns a negative value if the operation fails.
361     *
362     * @since 3.2
363     * @version 1.1
364     */
365    GetNetDevInfo([out] struct HdfNetDeviceInfoResult netDeviceInfoResult);
366
367    /**
368     * @brief Starts scanning.
369     *
370     * @param ifeature Indicates the <b>Feature</b> object.
371     * @param scan Indicates the scan parameters.
372     *
373     * @return Returns <b>0</b> if the operation is successful.
374     * @return Returns a negative value if the operation fails.
375     *
376     * @since 3.2
377     * @version 1.1
378     */
379    StartScan([in] struct HdfFeatureInfo ifeature, [in] struct HdfWifiScan scan);
380
381    /**
382     * @brief Obtains the power mode in use.
383     *
384     * @param ifeature Indicates the <b>Feature</b> object.
385     * @param mode Indicates the power mode obtained. The power mode can be <b>sleeping</b> (running in standby mode),
386     * <b>general</b> (running at normal rated power),
387     * and <b>through-wall</b> (running at the maximum power to improve the signal strength and coverage).
388     *
389     * @return Returns <b>0</b> if the operation is successful.
390     * @return Returns a negative value if the operation fails.
391     *
392     * @since 3.2
393     * @version 1.1
394     */
395    GetPowerMode([in] struct HdfFeatureInfo ifeature, [out] unsigned char mode);
396
397    /**
398     * @brief Sets the power mode.
399     *
400     * @param ifeature Indicates the <b>Feature</b> object.
401     * @param mode Indicates the power mode to set. The power mode can be <b>sleeping</b> (running in standby mode),
402     * <b>general</b> (running at normal rated power),
403     * and <b>through-wall</b> (running at the maximum power to improve the signal strength and coverage).
404     *
405     * @return Returns <b>0</b> if the operation is successful.
406     * @return Returns a negative value if the operation fails.
407     *
408     * @since 3.2
409     * @version 1.1
410     */
411    SetPowerMode([in] struct HdfFeatureInfo ifeature, [in] unsigned char mode);
412
413    /**
414     * @brief Starts channel measurement.
415     *
416     * @param ifName Indicates the NIC name.
417     * @param measChannelParam Indicates the channel measurement parameters (channel ID and measurement time).
418     *
419     * @return Returns <b>0</b> if the operation is successful.
420     * @return Returns a negative value if the operation fails.
421     *
422     * @since 3.2
423     * @version 1.1
424     */
425    [oneway] StartChannelMeas([in] String ifName, [in] struct MeasChannelParam measChannelParam);
426
427    /**
428     * @brief Obtains the channel measurement result.
429     *
430     * @param ifName Indicates the NIC name.
431     * @param measChannelResult Indicates the channel measurement result (including the channel ID, load, and noise).
432     *
433     * @return Returns <b>0</b> if the operation is successful.
434     * @return Returns a negative value if the operation fails.
435     *
436     * @since 3.2
437     * @version 1.1
438     */
439    GetChannelMeasResult([in] String ifName, [out] struct MeasChannelResult measChannelResult);
440
441    /**
442     * @brief Sets the projection parameters.
443     *
444     * @param ifName Indicates the NIC name.
445     * @param param Indicates the projection parameters to set.
446     *
447     * @return Returns <b>0</b> if the operation is successful.
448     * @return Returns a negative value if the operation fails.
449     *
450     * @since 3.2
451     * @version 1.1
452     */
453    SetProjectionScreenParam([in] String ifName, [in] struct ProjectionScreenCmdParam param);
454
455    /**
456     * @brief Sends an I/O control command to the driver.
457     *
458     * @param ifName Indicates the NIC name.
459     * @param cmdId Indicates the ID of the command to send.
460     * @param paramBuf Indicates the command content.
461     *
462     * @return Returns <b>0</b> if the operation is successful.
463     * @return Returns a negative value if the operation fails.
464     *
465     * @since 3.2
466     * @version 1.1
467     */
468    WifiSendCmdIoctl([in] String ifName, [in] int cmdId, [in] byte[] paramBuf);
469
470    /**
471     * @brief Obtains the STA information of the specified NIC.
472     *
473     * @param ifName Indicates the NIC name.
474     * @param info Indicates the STA information obtained. For details, see {@link WifiStationInfo}.
475     * @param mac Indicates the MAC address of the STA.
476     *
477     * @return Returns <b>0</b> if the operation is successful.
478     * @return Returns a negative value if the operation fails.
479     *
480     * @since 3.2
481     * @version 1.1
482     */
483    GetStaInfo([in] String ifName, [out] struct WifiStationInfo info, [in] unsigned char[] mac);
484
485    /**
486     * @brief Start Pno scan.
487     *
488     * @param interfaceName Indicates the NIC name.
489     * @param pnoSettings Indicates the pno scan parameters.
490     *
491     * @return Returns <b>0</b> if the operation is successful.
492     * @return Returns a negative value if the operation fails.
493     *
494     * @since 4.0
495     * @version 1.1
496     */
497    StartPnoScan([in] String interfaceName, [in] struct PnoSettings pnoSettings);
498
499    /**
500     * @brief Stop Pno scan.
501     *
502     * @param interfaceName Indicates the NIC name.
503     *
504     * @return Returns <b>0</b> if the operation is successful.
505     * @return Returns a negative value if the operation fails.
506     *
507     * @since 4.0
508     * @version 1.1
509     */
510    StopPnoScan([in] String interfaceName);
511
512    /**
513     * @brief Obtain signal information of the associated link. This function must be called in STA mode.
514     *
515     * @param ifName Indicates the NIC name.
516     * @param signalResult Indicates the signal infornation.
517     *
518     * @return Returns <b>0</b> if the operation is successful.
519     * @return Returns a negative value if the operation fails.
520     *
521     * @since 4.0
522     * @version 1.1
523     */
524    GetSignalPollInfo([in] String ifName, [out] struct SignalPollResult signalResult);
525}
526/** @} */
527