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