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  * @file softbus_broadcast_manager.h
18  * @brief
19  *
20  * @since 4.1
21  * @version 1.0
22  */
23 
24 #ifndef SOFTBUS_BROADCAST_MANAGER_H
25 #define SOFTBUS_BROADCAST_MANAGER_H
26 
27 #include "softbus_broadcast_type.h"
28 
29 #ifdef __cplusplus
30 extern "C"{
31 #endif
32 
33 /**
34  * @brief Defines the broadcast callback function.
35  *
36  * @since 4.1
37  * @version 1.0
38  */
39 typedef struct {
40     void (*OnStartBroadcastingCallback)(int32_t bcId, int32_t status);
41     void (*OnStopBroadcastingCallback)(int32_t bcId, int32_t status);
42     void (*OnUpdateBroadcastingCallback)(int32_t bcId, int32_t status);
43     void (*OnSetBroadcastingCallback)(int32_t bcId, int32_t status);
44 } BroadcastCallback;
45 
46 /**
47  * @brief Defines the broadcast scan callback function.
48  *
49  * @since 4.1
50  * @version 1.0
51  */
52 typedef struct {
53     void (*OnStartScanCallback)(int32_t listenerId, int32_t status);
54     void (*OnStopScanCallback)(int32_t listenerId, int32_t status);
55     void (*OnReportScanDataCallback)(int32_t listenerId, const BroadcastReportInfo *reportInfo);
56     void (*OnScanStateChanged)(int32_t resultCode, bool isStartScan);
57     void (*OnLpDeviceInfoCallback)(const BroadcastUuid *uuid, int32_t type, uint8_t *data, uint32_t dataSize);
58 } ScanCallback;
59 
60 /**
61  * @brief init broadcast manager.
62  *
63  * @return Returns <b>0</b> If the broadcast management initialization fails;
64  * returns any other value if the request fails.
65  * @since 4.1
66  * @version 1.0
67  */
68 int32_t InitBroadcastMgr(void);
69 
70 /**
71  * @brief init broadcast manager.
72  *
73  * @return Returns <b>SOFTBUS_OK</b> If the broadcast management deinitialization fails;
74  * returns any other value if the request fails.
75  * @since 4.1
76  * @version 1.0
77  */
78 int32_t DeInitBroadcastMgr(void);
79 
80 /**
81  * @brief Register the service to the broadcast manager.
82  *
83  * @param type Indicates the service type {@link BaseServiceType}.
84  * @param bcId Indicates the service broadcast ID.
85  * @param cb Indicates the service broadcast callback {@link BroadcastCallback}.
86  *
87  * @return Returns <b>SOFTBUS_OK</b> if the service register is successful.
88  * returns any other value if the register fails.
89  *
90  * @since 4.1
91  * @version 1.0
92  */
93 int32_t RegisterBroadcaster(BaseServiceType type, int32_t *bcId, const BroadcastCallback *cb);
94 
95 /**
96  * @brief UnRegister the service to the broadcast manager.
97  *
98  * @param bcId Indicates the service broadcast ID.
99  *
100  * @return Returns <b>SOFTBUS_OK</b> if the service unregister is successful.
101  * returns any other value if the unregister fails.
102  *
103  * @since 4.1
104  * @version 1.0
105  */
106 int32_t UnRegisterBroadcaster(int32_t bcId);
107 
108 /**
109  * @brief Register the service listener to the broadcast manager.
110  *
111  * @param type Indicates the service type {@link BaseServiceType}.
112  * @param listenerId Indicates the service listener ID.
113  * @param cb Indicates the service listener callback {@link ScanCallback}.
114  *
115  * @return Returns <b>SOFTBUS_OK</b> if the service register is successful.
116  * returns any other value if the register fails.
117  *
118  * @since 4.1
119  * @version 1.0
120  */
121 int32_t RegisterScanListener(BaseServiceType type, int32_t *listenerId, const ScanCallback *cb);
122 
123 /**
124  * @brief UnRegister the service listener to the broadcast manager.
125  *
126  * @param listenerId Indicates the service listener ID.
127  *
128  * @return Returns <b>SOFTBUS_OK</b> if the service unregister is successful.
129  * returns any other value if the unregister fails.
130  *
131  * @since 4.1
132  * @version 1.0
133  */
134 int32_t UnRegisterScanListener(int32_t listenerId);
135 
136 /**
137  * @brief The service enable broadcast
138  *
139  * @param bcId Indicates the service broadcast ID.
140  * @param param Indicates the pointer to the service parameter information. For details, see {@link BroadcastParam}.
141  * @param packet Indicates the pointer to the service advertising data. For details, see {@link BroadcastPacket}.
142  *
143  * @return Returns <b>SOFTBUS_OK</b> if the service starts the broadcast successfully.
144  * returns any other value if the unregister fails.
145  *
146  * @since 4.1
147  * @version 1.0
148  */
149 int32_t StartBroadcasting(int32_t bcId, const BroadcastParam *param, const BroadcastPacket *packet);
150 
151 /**
152  * @brief The service update broadcast data and parameters.When the broadcast is updated,
153  * the broadcast is stopped and then started.
154  *
155  * @param bcId Indicates the service broadcast ID.
156  * @param param Indicates the pointer to the service parameter information. For details, see {@link BroadcastParam}.
157  * @param bcData Indicates the pointer to the service advertising data. For details, see {@link BroadcastPacket}.
158  *
159  * @return Returns <b>SOFTBUS_OK</b> if the service updates the broadcast successfully.
160  * returns any other value if the service fails to update the broadcast.
161  *
162  * @since 4.1
163  * @version 1.0
164  */
165 int32_t UpdateBroadcasting(int32_t bcId, const BroadcastParam *param, const BroadcastPacket *packet);
166 
167 /**
168  * @brief The service set broadcast data. Set broadcast data when broadcast is enabled.
169  *
170  * @param bcId Indicates the service broadcast ID.
171  * @param packet Indicates the pointer to the service advertising data. For details, see {@link BroadcastPacket}.
172  *
173  * @return Returns <b>SOFTBUS_OK</b> if the service starts the broadcast successfully.
174  * returns any other value if the unregister fails.
175  *
176  * @since 4.1
177  * @version 1.0
178  */
179 
180 int32_t SetBroadcastingData(int32_t bcId, const BroadcastPacket *packet);
181 /**
182  * @brief The service stop broadcast
183  *
184  * @param bcId Indicates the service broadcast ID.
185  *
186  * @return Returns <b>SOFTBUS_OK</b> if the service stop the broadcast successfully.
187  * returns any other value if the service fails to stop the broadcast.
188  *
189  * @since 4.1
190  * @version 1.0
191  */
192 int32_t StopBroadcasting(int32_t bcId);
193 
194 /**
195  * @brief The service enable broadcast scanning
196  *
197  * @param listenerId Indicates the service listener ID.
198  * @param param Indicates the broadcast scan parameter {@link BcScanParams}
199  *
200  * @return Returns <b>SOFTBUS_OK</b> if the service start to scan the broadcast successfully.
201  * returns any other value if the service fails to scan the broadcast.
202  *
203  * @since 4.1
204  * @version 1.0
205  */
206 int32_t StartScan(int32_t listenerId, const BcScanParams *param);
207 
208 /**
209  * @brief The service stop broadcast scanning
210  *
211  * @param listenerId Indicates the service listener ID.
212  *
213  * @return Returns <b>SOFTBUS_OK</b> if the service stop to scan the broadcast successfully.
214  * returns any other value if the service fails to stop scanning the broadcast.
215  *
216  * @since 4.1
217  * @version 1.0
218  */
219 int32_t StopScan(int32_t listenerId);
220 
221 /**
222  * @brief Set the Scan Filter object
223  *
224  * @param listenerId Indicates the service listener ID.
225  * @param scanFilter Indicates the broadcast scan filter parameter {@link BcScanFilter}
226  * @param filterNum Indicates the number of the filter parameter
227  *
228  * @return Returns <b>SOFTBUS_OK</b> if the service set the Scan Filter successfully.
229  * returns any other value if the service fails to set the Scan Filter.
230  *
231  * @since 4.1
232  * @version 1.0
233  */
234 int32_t SetScanFilter(int32_t listenerId, const BcScanFilter *scanFilter, uint8_t filterNum);
235 
236 /**
237  * @brief Get the Scan Filter object
238  *
239  * @param listenerId Indicates the service listener ID.
240  * @param scanFilter Indicates the broadcast scan filter parameter {@link BcScanFilter}
241  * @param filterNum Indicates the number of the filter parameter
242  *
243  * @return Returns <b>SOFTBUS_OK</b> if the service get the Scan Filter successfully.
244  * returns any other value if the service fails to get the Scan Filter.
245  *
246  * @since 4.1
247  * @version 1.0
248  */
249 int32_t GetScanFilter(int32_t listenerId, BcScanFilter **scanFilter, uint8_t *filterNum);
250 
251 /**
252  * @brief Check whether available resources are available by using the bcid
253  *
254  * @param bcId Indicates the service broadcast ID, when the service register successfully
255  * @param status Indicates the status of available broadcast resources
256  *
257  * @return Returns <b>SOFTBUS_OK</b> if the service query status successfully.
258  * returns any other value if the service fails to query status.
259  *
260  * @since 4.1
261  * @version 1.0
262  */
263 int32_t QueryBroadcastStatus(int32_t bcId, int32_t *status);
264 
265 /**
266  * @brief Check whether the device is a low-power device.
267  *
268  * @return Returns <b>true</b> if the device is a low-power device.
269  * @return returns false value if the service fails to query a low-power device.
270  *
271  * @since 4.1
272  * @version 1.0
273  */
274 bool BroadcastIsLpDeviceAvailable(void);
275 
276 /**
277  * @brief Set low-power chip broadcast parameters, scanning parameters, scanning filters, and broadcast data.
278  *
279  * @param bcParam Indicates low-power chip broadcast parameters and broadcast data.
280  * @param scanParam Indicates low power chip scan parameters and filters.
281  *
282  * @return Returns <b>true</b> if the service set parameters successfully.
283  * @return returns false value if the service fails set parameters.
284  *
285  * @since 4.1
286  * @version 1.0
287  */
288 bool BroadcastSetAdvDeviceParam(LpServerType type, const LpBroadcastParam *bcParam,
289     const LpScanParam *scanParam);
290 
291 /**
292  * @brief Obtain the advHandle using advId.
293  *
294  * @param bcId Indicates the service broadcast ID, when the service register successfully
295  * @param bcHandle Indicates Convert to bcHandle via advId,.
296  *
297  * @return Returns <b>SOFTBUS_OK</b> if the service get the handle successfully.
298  * returns any other value if the service fails to get the handle.
299  *
300  * @since 4.1
301  * @version 1.0
302  */
303 int32_t BroadcastGetBroadcastHandle(int32_t bcId, int32_t *bcHandle);
304 
305 /**
306  * @brief Enables data synchronization to a low-power chip.
307  *
308 * @return Returns <b>SOFTBUS_OK</b> if the service enable SyncData successfully.
309  * returns any other value if the service fails to enable SyncData.
310  *
311  * @since 4.1
312  * @version 1.0
313  */
314 int32_t BroadcastEnableSyncDataToLpDevice(void);
315 
316 /**
317  * @brief Disables data synchronization to a low-power chip.
318  *
319 * @return Returns <b>SOFTBUS_OK</b> if the service disable syncData successfully.
320  * returns any other value if the service fails to disable syncData.
321  *
322  * @since 4.1
323  * @version 1.0
324  */
325 int32_t BroadcastDisableSyncDataToLpDevice(void);
326 
327 /**
328  * @brief set scanReport channel to a low-power chip.
329  *
330 * @return Returns <b>SOFTBUS_OK</b> if the service set scanReport channel successfully.
331  * returns any other value if the service fails to set scanReport channel.
332  *
333  * @since 4.1
334  * @version 1.0
335  */
336 int32_t BroadcastSetScanReportChannelToLpDevice(int32_t listenerId, bool enable);
337 
338 /**
339  * @brief set low-power broadcast channel parameters.
340  *
341  * @param duration Indicates broadcast duration.
342  * @param maxExtAdvEvents Indicates maximum number of extended broadcast events.
343  * @param window Indicates work window.
344  * @param interval Indicates work interval.
345  * @param bcHandle Indicates the broadcast handle.
346  *
347  * @return Returns <b>SOFTBUS_OK</b> if the service set low power broadcast parameters successfully.
348  * returns any other value if the service fails to set low power broadcast parameters.
349  *
350  * @since 1.0
351  * @version 1.0
352  */
353 int32_t BroadcastSetLpAdvParam(int32_t duration, int32_t maxExtAdvEvents, int32_t window,
354     int32_t interval, int32_t bcHandle);
355 
356 #ifdef __cplusplus
357 }
358 #endif
359 
360 #endif /* SOFTBUS_BROADCAST_MANAGER_H */
361