1/* 2 * Copyright (C) 2023-2024 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 18 * @kit ConnectivityKit 19 */ 20 21import type { AsyncCallback, Callback } from './@ohos.base'; 22 23/** 24 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state. 25 * 26 * @namespace access 27 * @syscap SystemCapability.Communication.Bluetooth.Core 28 * @since 10 29 */ 30/** 31 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state. 32 * 33 * @namespace access 34 * @syscap SystemCapability.Communication.Bluetooth.Core 35 * @atomicservice 36 * @since 11 37 */ 38/** 39 * Provides methods for enabling/disabling bluetooth or monitoring bluetooth state. 40 * 41 * @namespace access 42 * @syscap SystemCapability.Communication.Bluetooth.Core 43 * @crossplatform 44 * @atomicservice 45 * @since 13 46 */ 47declare namespace access { 48 /** 49 * Enables Bluetooth on a device. 50 * 51 * @permission ohos.permission.ACCESS_BLUETOOTH 52 * @throws { BusinessError } 201 - Permission denied. 53 * @throws { BusinessError } 801 - Capability not supported. 54 * @throws { BusinessError } 2900001 - Service stopped. 55 * @throws { BusinessError } 2900099 - Operation failed. 56 * @syscap SystemCapability.Communication.Bluetooth.Core 57 * @since 10 58 */ 59 /** 60 * Enables Bluetooth on a device. 61 * 62 * @permission ohos.permission.ACCESS_BLUETOOTH 63 * @throws { BusinessError } 201 - Permission denied. 64 * @throws { BusinessError } 801 - Capability not supported. 65 * @throws { BusinessError } 2900001 - Service stopped. 66 * @throws { BusinessError } 2900099 - Operation failed. 67 * @syscap SystemCapability.Communication.Bluetooth.Core 68 * @atomicservice 69 * @since 12 70 */ 71 /** 72 * Enables Bluetooth on a device. 73 * 74 * @permission ohos.permission.ACCESS_BLUETOOTH 75 * @throws { BusinessError } 201 - Permission denied. 76 * @throws { BusinessError } 801 - Capability not supported. 77 * @throws { BusinessError } 2900001 - Service stopped. 78 * @throws { BusinessError } 2900099 - Operation failed. 79 * @syscap SystemCapability.Communication.Bluetooth.Core 80 * @crossplatform 81 * @atomicservice 82 * @since 13 83 */ 84 function enableBluetooth(): void; 85 86 /** 87 * Disables Bluetooth on a device. 88 * 89 * @permission ohos.permission.ACCESS_BLUETOOTH 90 * @throws { BusinessError } 201 - Permission denied. 91 * @throws { BusinessError } 801 - Capability not supported. 92 * @throws { BusinessError } 2900001 - Service stopped. 93 * @throws { BusinessError } 2900099 - Operation failed. 94 * @syscap SystemCapability.Communication.Bluetooth.Core 95 * @since 10 96 */ 97 /** 98 * Disables Bluetooth on a device. 99 * 100 * @permission ohos.permission.ACCESS_BLUETOOTH 101 * @throws { BusinessError } 201 - Permission denied. 102 * @throws { BusinessError } 801 - Capability not supported. 103 * @throws { BusinessError } 2900001 - Service stopped. 104 * @throws { BusinessError } 2900099 - Operation failed. 105 * @syscap SystemCapability.Communication.Bluetooth.Core 106 * @atomicservice 107 * @since 12 108 */ 109 /** 110 * Disables Bluetooth on a device. 111 * 112 * @permission ohos.permission.ACCESS_BLUETOOTH 113 * @throws { BusinessError } 201 - Permission denied. 114 * @throws { BusinessError } 801 - Capability not supported. 115 * @throws { BusinessError } 2900001 - Service stopped. 116 * @throws { BusinessError } 2900099 - Operation failed. 117 * @syscap SystemCapability.Communication.Bluetooth.Core 118 * @crossplatform 119 * @atomicservice 120 * @since 13 121 */ 122 function disableBluetooth(): void; 123 124 /** 125 * Restrict Bluetooth BR/EDR ability on a device. 126 * 127 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 128 * @returns { Promise<void> } Promise that returns no value. 129 * @throws { BusinessError } 201 - Permission denied. 130 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 131 * @throws { BusinessError } 801 - Capability not supported. 132 * @throws { BusinessError } 2900001 - Service stopped. 133 * @throws { BusinessError } 2900099 - Operation failed. 134 * @syscap SystemCapability.Communication.Bluetooth.Core 135 * @systemapi 136 * @since 12 137 */ 138 function restrictBluetooth(): Promise<void>; 139 140 /** 141 * Obtains the Bluetooth status of a device. 142 * 143 * @permission ohos.permission.ACCESS_BLUETOOTH 144 * @returns { BluetoothState } Returns the Bluetooth status. 145 * @throws { BusinessError } 201 - Permission denied. 146 * @throws { BusinessError } 801 - Capability not supported. 147 * @throws { BusinessError } 2900001 - Service stopped. 148 * @throws { BusinessError } 2900099 - Operation failed. 149 * @syscap SystemCapability.Communication.Bluetooth.Core 150 * @since 10 151 */ 152 /** 153 * Obtains the Bluetooth status of a device. 154 * 155 * @permission ohos.permission.ACCESS_BLUETOOTH 156 * @returns { BluetoothState } Returns the Bluetooth status. 157 * @throws { BusinessError } 201 - Permission denied. 158 * @throws { BusinessError } 801 - Capability not supported. 159 * @throws { BusinessError } 2900001 - Service stopped. 160 * @throws { BusinessError } 2900099 - Operation failed. 161 * @syscap SystemCapability.Communication.Bluetooth.Core 162 * @atomicservice 163 * @since 11 164 */ 165 /** 166 * Obtains the Bluetooth status of a device. 167 * 168 * @returns { BluetoothState } Returns the Bluetooth status. 169 * @throws { BusinessError } 801 - Capability not supported. 170 * @throws { BusinessError } 2900001 - Service stopped. 171 * @throws { BusinessError } 2900099 - Operation failed. 172 * @syscap SystemCapability.Communication.Bluetooth.Core 173 * @crossplatform 174 * @atomicservice 175 * @since 13 176 */ 177 function getState(): BluetoothState; 178 179 /** 180 * Restoring bluetooth settings. 181 * 182 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 183 * @param { AsyncCallback<void> } callback - Callback used to return the result. 184 * @throws { BusinessError } 201 - Permission denied. 185 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 186 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 187 * <br>2. Incorrect parameter types. 188 * @throws { BusinessError } 801 - Capability not supported. 189 * @throws { BusinessError } 2900001 - Service stopped. 190 * @throws { BusinessError } 2900099 - Operation failed. 191 * @syscap SystemCapability.Communication.Bluetooth.Core 192 * @systemapi 193 * @since 11 194 */ 195 function factoryReset(callback: AsyncCallback<void>): void; 196 197 /** 198 * Restoring bluetooth settings. 199 * 200 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 201 * @returns { Promise<void> } Promise that returns no value. 202 * @throws { BusinessError } 201 - Permission denied. 203 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 204 * @throws { BusinessError } 801 - Capability not supported. 205 * @throws { BusinessError } 2900001 - Service stopped. 206 * @throws { BusinessError } 2900099 - Operation failed. 207 * @syscap SystemCapability.Communication.Bluetooth.Core 208 * @systemapi 209 * @since 11 210 */ 211 function factoryReset(): Promise<void>; 212 213 /** 214 * Obtaining the MAC address of the local device. 215 * 216 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.GET_BLUETOOTH_LOCAL_MAC 217 * @returns { string } The local MAC address. For example, "11:22:33:AA:BB:FF". 218 * @throws { BusinessError } 201 - Permission denied. 219 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 220 * @throws { BusinessError } 801 - Capability not supported. 221 * @throws { BusinessError } 2900001 - Service stopped. 222 * @throws { BusinessError } 2900099 - Operation failed. 223 * @syscap SystemCapability.Communication.Bluetooth.Core 224 * @systemapi 225 * @since 11 226 */ 227 function getLocalAddress(): string; 228 229 /** 230 * Subscribe the event reported when the Bluetooth state changes. 231 * 232 * @permission ohos.permission.ACCESS_BLUETOOTH 233 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 234 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 235 * @throws { BusinessError } 201 - Permission denied. 236 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 237 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 238 * @throws { BusinessError } 801 - Capability not supported. 239 * @throws { BusinessError } 2900099 - Operation failed. 240 * @syscap SystemCapability.Communication.Bluetooth.Core 241 * @since 10 242 */ 243 /** 244 * Subscribe the event reported when the Bluetooth state changes. 245 * 246 * @permission ohos.permission.ACCESS_BLUETOOTH 247 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 248 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 249 * @throws { BusinessError } 201 - Permission denied. 250 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 251 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 252 * @throws { BusinessError } 801 - Capability not supported. 253 * @throws { BusinessError } 2900099 - Operation failed. 254 * @syscap SystemCapability.Communication.Bluetooth.Core 255 * @atomicservice 256 * @since 12 257 */ 258 /** 259 * Subscribe the event reported when the Bluetooth state changes. 260 * 261 * @permission ohos.permission.ACCESS_BLUETOOTH 262 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 263 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 264 * @throws { BusinessError } 201 - Permission denied. 265 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 266 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 267 * @throws { BusinessError } 801 - Capability not supported. 268 * @throws { BusinessError } 2900099 - Operation failed. 269 * @syscap SystemCapability.Communication.Bluetooth.Core 270 * @crossplatform 271 * @atomicservice 272 * @since 13 273 */ 274 /** 275 * Subscribe the event reported when the Bluetooth state changes. 276 * 277 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 278 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 279 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 280 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 281 * @throws { BusinessError } 801 - Capability not supported. 282 * @throws { BusinessError } 2900099 - Operation failed. 283 * @syscap SystemCapability.Communication.Bluetooth.Core 284 * @crossplatform 285 * @atomicservice 286 * @since 18 287 */ 288 function on(type: 'stateChange', callback: Callback<BluetoothState>): void; 289 290 /** 291 * Unsubscribe the event reported when the Bluetooth state changes. 292 * 293 * @permission ohos.permission.ACCESS_BLUETOOTH 294 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 295 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 296 * @throws { BusinessError } 201 - Permission denied. 297 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 298 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 299 * @throws { BusinessError } 801 - Capability not supported. 300 * @throws { BusinessError } 2900099 - Operation failed. 301 * @syscap SystemCapability.Communication.Bluetooth.Core 302 * @since 10 303 */ 304 /** 305 * Unsubscribe the event reported when the Bluetooth state changes. 306 * 307 * @permission ohos.permission.ACCESS_BLUETOOTH 308 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 309 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 310 * @throws { BusinessError } 201 - Permission denied. 311 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 312 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 313 * @throws { BusinessError } 801 - Capability not supported. 314 * @throws { BusinessError } 2900099 - Operation failed. 315 * @syscap SystemCapability.Communication.Bluetooth.Core 316 * @atomicservice 317 * @since 12 318 */ 319 /** 320 * Unsubscribe the event reported when the Bluetooth state changes. 321 * 322 * @permission ohos.permission.ACCESS_BLUETOOTH 323 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 324 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 325 * @throws { BusinessError } 201 - Permission denied. 326 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 327 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 328 * @throws { BusinessError } 801 - Capability not supported. 329 * @throws { BusinessError } 2900099 - Operation failed. 330 * @syscap SystemCapability.Communication.Bluetooth.Core 331 * @crossplatform 332 * @atomicservice 333 * @since 13 334 */ 335 /** 336 * Unsubscribe the event reported when the Bluetooth state changes. 337 * 338 * @param { 'stateChange' } type - Type of the Bluetooth state changes event to listen for. 339 * @param { Callback<BluetoothState> } callback - Callback used to listen for the Bluetooth state event. 340 * @throws { BusinessError } 401 - Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 341 * <br>2. Incorrect parameter types. 3. Parameter verification failed. 342 * @throws { BusinessError } 801 - Capability not supported. 343 * @throws { BusinessError } 2900099 - Operation failed. 344 * @syscap SystemCapability.Communication.Bluetooth.Core 345 * @crossplatform 346 * @atomicservice 347 * @since 18 348 */ 349 function off(type: 'stateChange', callback?: Callback<BluetoothState>): void; 350 351 /** 352 * Add a persistent random device address. Once the randomized address is successfully added, 353 * the application can save it for an extended period of time. 354 * 355 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 356 * @param { string } deviceId - the randomized address of remote device. 357 * @returns { Promise<void> } Returns the promise object. 358 * @throws { BusinessError } 201 - Permission denied. 359 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 360 * 2. Incorrect parameter types. 3. Parameter verification failed. 361 * @throws { BusinessError } 801 - Capability not supported. 362 * @throws { BusinessError } 2900003 - Bluetooth disabled. 363 * @throws { BusinessError } 2900010 - The number of supported device addresses has reached the upper limit. 364 * @throws { BusinessError } 2900099 - Add persistent device address failed. 365 * @syscap SystemCapability.Communication.Bluetooth.Core 366 * @atomicservice 367 * @since 16 368 */ 369 function addPersistentDeviceId(deviceId: string): Promise<void>; 370 371 /** 372 * Delete a persistent random device address. 373 * 374 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 375 * @param { string } deviceId - the randomized address of remote device. 376 * @returns { Promise<void> } Returns the promise object. 377 * @throws { BusinessError } 201 - Permission denied. 378 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 379 * 2. Incorrect parameter types. 3. Parameter verification failed. 380 * @throws { BusinessError } 801 - Capability not supported. 381 * @throws { BusinessError } 2900003 - Bluetooth disabled. 382 * @throws { BusinessError } 2900099 - delete persistent device address failed. 383 * @syscap SystemCapability.Communication.Bluetooth.Core 384 * @atomicservice 385 * @since 16 386 */ 387 function deletePersistentDeviceId(deviceId: string): Promise<void>; 388 389 /** 390 * Obtains the persistent randomized device address of the application. 391 * 392 * @permission ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 393 * @returns { string[] } Returns the list of persistent random device addresses. 394 * @throws { BusinessError } 201 - Permission denied. 395 * @throws { BusinessError } 801 - Capability not supported. 396 * @throws { BusinessError } 2900003 - Bluetooth disabled. 397 * @throws { BusinessError } 2900099 - Get persistent device address failed. 398 * @syscap SystemCapability.Communication.Bluetooth.Core 399 * @atomicservice 400 * @since 16 401 */ 402 function getPersistentDeviceIds(): string[]; 403 404 /** 405 * Determine whether the randomized device address application can still be used. 406 * 407 * @permission ohos.permission.ACCESS_BLUETOOTH 408 * @param { string } deviceId - the randomized address of remote device. 409 * @returns { boolean } Returns whether the randomized device address is valid. 410 * @throws { BusinessError } 201 - Permission denied. 411 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 412 * 2. Incorrect parameter types. 3. Parameter verification failed. 413 * @throws { BusinessError } 801 - Capability not supported. 414 * @throws { BusinessError } 2900003 - Bluetooth disabled. 415 * @throws { BusinessError } 2900099 - Check persistent device address failed. 416 * @syscap SystemCapability.Communication.Bluetooth.Core 417 * @atomicservice 418 * @since 16 419 */ 420 function isValidRandomDeviceId(deviceId: string): boolean; 421 422 /** 423 * The enum of bluetooth state. 424 * 425 * @enum { number } 426 * @syscap SystemCapability.Communication.Bluetooth.Core 427 * @since 10 428 */ 429 /** 430 * The enum of bluetooth state. 431 * 432 * @enum { number } 433 * @syscap SystemCapability.Communication.Bluetooth.Core 434 * @atomicservice 435 * @since 11 436 */ 437 /** 438 * The enum of bluetooth state. 439 * 440 * @enum { number } 441 * @syscap SystemCapability.Communication.Bluetooth.Core 442 * @crossplatform 443 * @atomicservice 444 * @since 13 445 */ 446 export enum BluetoothState { 447 /** 448 * Indicates the local Bluetooth is off 449 * 450 * @syscap SystemCapability.Communication.Bluetooth.Core 451 * @since 10 452 */ 453 /** 454 * Indicates the local Bluetooth is off 455 * 456 * @syscap SystemCapability.Communication.Bluetooth.Core 457 * @atomicservice 458 * @since 11 459 */ 460 /** 461 * Indicates the local Bluetooth is off 462 * 463 * @syscap SystemCapability.Communication.Bluetooth.Core 464 * @crossplatform 465 * @atomicservice 466 * @since 13 467 */ 468 STATE_OFF = 0, 469 /** 470 * Indicates the local Bluetooth is turning on 471 * 472 * @syscap SystemCapability.Communication.Bluetooth.Core 473 * @since 10 474 */ 475 /** 476 * Indicates the local Bluetooth is turning on 477 * 478 * @syscap SystemCapability.Communication.Bluetooth.Core 479 * @atomicservice 480 * @since 11 481 */ 482 /** 483 * Indicates the local Bluetooth is turning on 484 * 485 * @syscap SystemCapability.Communication.Bluetooth.Core 486 * @crossplatform 487 * @atomicservice 488 * @since 13 489 */ 490 STATE_TURNING_ON = 1, 491 /** 492 * Indicates the local Bluetooth is on, and ready for use 493 * 494 * @syscap SystemCapability.Communication.Bluetooth.Core 495 * @since 10 496 */ 497 /** 498 * Indicates the local Bluetooth is on, and ready for use 499 * 500 * @syscap SystemCapability.Communication.Bluetooth.Core 501 * @atomicservice 502 * @since 11 503 */ 504 /** 505 * Indicates the local Bluetooth is on, and ready for use 506 * 507 * @syscap SystemCapability.Communication.Bluetooth.Core 508 * @crossplatform 509 * @atomicservice 510 * @since 13 511 */ 512 STATE_ON = 2, 513 /** 514 * Indicates the local Bluetooth is turning off 515 * 516 * @syscap SystemCapability.Communication.Bluetooth.Core 517 * @since 10 518 */ 519 /** 520 * Indicates the local Bluetooth is turning off 521 * 522 * @syscap SystemCapability.Communication.Bluetooth.Core 523 * @atomicservice 524 * @since 11 525 */ 526 /** 527 * Indicates the local Bluetooth is turning off 528 * 529 * @syscap SystemCapability.Communication.Bluetooth.Core 530 * @crossplatform 531 * @atomicservice 532 * @since 13 533 */ 534 STATE_TURNING_OFF = 3, 535 /** 536 * Indicates the local Bluetooth is turning LE mode on 537 * 538 * @syscap SystemCapability.Communication.Bluetooth.Core 539 * @since 10 540 */ 541 /** 542 * Indicates the local Bluetooth is turning LE mode on 543 * 544 * @syscap SystemCapability.Communication.Bluetooth.Core 545 * @atomicservice 546 * @since 11 547 */ 548 STATE_BLE_TURNING_ON = 4, 549 /** 550 * Indicates the local Bluetooth is in LE only mode 551 * 552 * @syscap SystemCapability.Communication.Bluetooth.Core 553 * @since 10 554 */ 555 /** 556 * Indicates the local Bluetooth is in LE only mode 557 * 558 * @syscap SystemCapability.Communication.Bluetooth.Core 559 * @atomicservice 560 * @since 11 561 */ 562 STATE_BLE_ON = 5, 563 /** 564 * Indicates the local Bluetooth is turning off LE only mode 565 * 566 * @syscap SystemCapability.Communication.Bluetooth.Core 567 * @since 10 568 */ 569 /** 570 * Indicates the local Bluetooth is turning off LE only mode 571 * 572 * @syscap SystemCapability.Communication.Bluetooth.Core 573 * @atomicservice 574 * @since 11 575 */ 576 STATE_BLE_TURNING_OFF = 6 577 } 578} 579 580export default access;