1# @ohos.bluetooth.connection (Bluetooth Connection Module) 2 3The **connection** module provides APIs for operating and managing Bluetooth. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10 11## Modules to Import 12 13```js 14import { connection } from '@kit.ConnectivityKit'; 15``` 16 17 18## connection.pairDevice 19 20pairDevice(deviceId: string, callback: AsyncCallback<void>): void 21 22Pairs a Bluetooth device. This API uses an asynchronous callback to return the result. 23 24**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 25 26**Atomic service API**: This API can be used in atomic services since API version 12. 27 28**System capability**: SystemCapability.Communication.Bluetooth.Core 29 30**Parameters** 31 32| Name | Type | Mandatory | Description | 33| -------- | ------ | ---- | ----------------------------------- | 34| deviceId | string | Yes | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.| 35| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the pairing is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 36 37**Error codes** 38 39For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 40 41| ID| Error Message| 42| -------- | ---------------------------- | 43|201 | Permission denied. | 44|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 45|801 | Capability not supported. | 46|2900001 | Service stopped. | 47|2900003 | Bluetooth disabled. | 48|2900099 | Operation failed. | 49 50**Example** 51 52```js 53import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 54//callback 55try { 56 connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => { 57 console.info('pairDevice, device name err:' + JSON.stringify(err)); 58 }); 59} catch (err) { 60 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 61} 62 63``` 64 65 66## connection.pairDevice 67 68pairDevice(deviceId: string): Promise<void> 69 70Pairs a Bluetooth device. This API uses a promise to return the result. 71 72**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 73 74**Atomic service API**: This API can be used in atomic services since API version 12. 75 76**System capability**: SystemCapability.Communication.Bluetooth.Core 77 78**Parameters** 79 80| Name | Type | Mandatory | Description | 81| -------- | ------ | ---- | ----------------------------------- | 82| deviceId | string | Yes | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.| 83 84**Return value** 85 86| Type | Description | 87| ------------------- | ------------- | 88| Promise<void> | Promise used to return the result.| 89 90**Error codes** 91 92For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 93 94| ID| Error Message| 95| -------- | ---------------------------- | 96|201 | Permission denied. | 97|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 98|801 | Capability not supported. | 99|2900001 | Service stopped. | 100|2900003 | Bluetooth disabled. | 101|2900099 | Operation failed. | 102 103**Example** 104 105```js 106import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 107//promise 108try { 109 connection.pairDevice('11:22:33:44:55:66').then(() => { 110 console.info('pairDevice'); 111 }, (error: BusinessError) => { 112 console.info('pairDevice: errCode:' + error.code + ',errMessage' + error.message); 113 }) 114 115} catch (err) { 116 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 117} 118``` 119 120 121## connection.getRemoteDeviceName 122 123getRemoteDeviceName(deviceId: string): string 124 125Obtains the name of a remote Bluetooth device. 126 127**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 128 129**Atomic service API**: This API can be used in atomic services since API version 12. 130 131**System capability**: SystemCapability.Communication.Bluetooth.Core 132 133**Parameters** 134 135| Name | Type | Mandatory | Description | 136| -------- | ------ | ---- | --------------------------------- | 137| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 138 139**Return value** 140 141| Type | Description | 142| ------ | ------------- | 143| string | Device name (a string) obtained.| 144 145**Error codes** 146 147For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 148 149| ID| Error Message| 150| -------- | ---------------------------- | 151|201 | Permission denied. | 152|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 153|801 | Capability not supported. | 154|2900001 | Service stopped. | 155|2900003 | Bluetooth disabled. | 156|2900099 | Operation failed. | 157 158**Example** 159 160```js 161import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 162try { 163 let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX'); 164} catch (err) { 165 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 166} 167``` 168 169 170## connection.getRemoteDeviceClass 171 172getRemoteDeviceClass(deviceId: string): DeviceClass 173 174Obtains the class of a remote Bluetooth device. 175 176**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 177 178**System capability**: SystemCapability.Communication.Bluetooth.Core 179 180**Parameters** 181 182| Name | Type | Mandatory | Description | 183| -------- | ------ | ---- | --------------------------------- | 184| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 185 186**Return value** 187 188| Type | Description | 189| --------------------------- | -------- | 190| [DeviceClass](#deviceclass) | Class of the remote device obtained.| 191 192**Error codes** 193 194For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 195 196| ID| Error Message| 197| -------- | ---------------------------- | 198|201 | Permission denied. | 199|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 200|801 | Capability not supported. | 201|2900001 | Service stopped. | 202|2900003 | Bluetooth disabled. | 203|2900099 | Operation failed. | 204 205**Example** 206 207```js 208import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 209try { 210 let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX'); 211} catch (err) { 212 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 213} 214``` 215 216 217## connection.getRemoteProfileUuids<sup>12+</sup> 218 219getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void 220 221Obtains the profile UUIDs of a remote Bluetooth device. This API uses an asynchronous callback to return the result. 222 223**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 224 225**System capability**: SystemCapability.Communication.Bluetooth.Core 226 227**Parameters** 228 229| Name | Type | Mandatory | Description | 230| -------- | ------ | ---- | ----------------------------------- | 231| deviceId | string | Yes | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.| 232| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 233 234**Error codes** 235 236For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 237 238| ID| Error Message| 239| -------- | ---------------------------- | 240|201 | Permission denied. | 241|401 | Invalid parameter. | 242|801 | Capability not supported. | 243|2900001 | Service stopped. | 244|2900003 | Bluetooth disabled. | 245|2900099 | Operation failed. | 246 247**Example** 248 249```js 250import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 251try { 252 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => { 253 console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); 254 }); 255} catch (err) { 256 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 257} 258 259``` 260 261 262## connection.getRemoteProfileUuids<sup>12+</sup> 263 264getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>> 265 266Obtains the profile UUIDs of a remote Bluetooth device. This API uses a promise to return the result. 267 268**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 269 270**System capability**: SystemCapability.Communication.Bluetooth.Core 271 272**Parameters** 273 274| Name | Type | Mandatory | Description | 275| -------- | ------ | ---- | ----------------------------------- | 276| deviceId | string | Yes | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.| 277 278**Return value** 279 280| Type | Description | 281| ------------------- | ------------- | 282| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | Promise used to return the result.| 283 284**Error codes** 285 286For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 287 288| ID| Error Message| 289| -------- | ---------------------------- | 290|201 | Permission denied. | 291|401 | Invalid parameter. | 292|801 | Capability not supported. | 293|2900001 | Service stopped. | 294|2900003 | Bluetooth disabled. | 295|2900099 | Operation failed. | 296 297**Example** 298 299```js 300import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 301try { 302 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => { 303 console.info('getRemoteProfileUuids'); 304 }, (err: BusinessError) => { 305 console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 306 }); 307} catch (err) { 308 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 309} 310``` 311 312 313## connection.getLocalName 314 315getLocalName(): string 316 317Obtains the name of the local Bluetooth device. 318 319**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 320 321**System capability**: SystemCapability.Communication.Bluetooth.Core 322 323**Return value** 324 325| Type | Description | 326| ------ | --------- | 327| string | Name of the local Bluetooth device obtained.| 328 329**Error codes** 330 331For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 332 333| ID| Error Message| 334| -------- | ---------------------------- | 335|201 | Permission denied. | 336|801 | Capability not supported. | 337|2900001 | Service stopped. | 338|2900099 | Operation failed. | 339 340**Example** 341 342```js 343import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 344try { 345 let localName: string = connection.getLocalName(); 346} catch (err) { 347 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 348} 349``` 350 351 352## connection.getPairedDevices 353 354getPairedDevices(): Array<string> 355 356Obtains the paired devices. 357 358**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 359 360**Atomic service API**: This API can be used in atomic services since API version 12. 361 362**System capability**: SystemCapability.Communication.Bluetooth.Core 363 364**Return value** 365 366| Type | Description | 367| ------------------- | ------------- | 368| Array<string> | Addresses of the paired Bluetooth devices. For security purposes, the device addresses obtained are random MAC addresses. The random MAC address remains unchanged after a device is paired successfully. It changes when the paired device is unpaired and scanned again or the Bluetooth service is turned off.| 369 370**Error codes** 371 372For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 373 374| ID| Error Message| 375| -------- | ---------------------------- | 376|201 | Permission denied. | 377|801 | Capability not supported. | 378|2900001 | Service stopped. | 379|2900003 | Bluetooth disabled. | 380|2900099 | Operation failed. | 381 382**Example** 383 384```js 385import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 386try { 387 let devices: Array<string> = connection.getPairedDevices(); 388} catch (err) { 389 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 390} 391``` 392 393 394## connection.getPairState<sup>11+</sup> 395 396getPairState(deviceId: string): BondState 397 398Obtains the Bluetooth pairing state. 399 400**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 401 402**Atomic service API**: This API can be used in atomic services since API version 12. 403 404**System capability**: SystemCapability.Communication.Bluetooth.Core 405 406**Parameters** 407 408| Name | Type | Mandatory | Description | 409| -------- | ------ | ---- | --------------------------------- | 410| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 411 412**Return value** 413 414| Type | Description | 415| --------------------------- | -------- | 416| [BondState](#bondstate) | Bluetooth pairing state obtained.| 417 418**Error codes** 419 420For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 421 422| ID| Error Message| 423| -------- | ---------------------------- | 424|201 | Permission denied. | 425|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 426|801 | Capability not supported. | 427|2900001 | Service stopped. | 428|2900003 | Bluetooth disabled. | 429|2900099 | Operation failed. | 430 431**Example** 432 433```js 434import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 435try { 436 let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX"); 437 console.info('getPairState: ' + res); 438} catch (err) { 439 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 440} 441``` 442 443 444## connection.getProfileConnectionState 445 446getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState 447 448Obtains the connection state of a Bluetooth profile. The **ProfileId** parameter is optional. If **ProfileId** is specified, the connection state of the specified profile is returned. If no **ProfileId** is specified, [STATE_CONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate) is returned by any connected profile. If no profile is connected, [STATE_DISCONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate) is returned. 449 450**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 451 452**System capability**: SystemCapability.Communication.Bluetooth.Core 453 454**Parameters** 455 456| Name | Type | Mandatory | Description | 457| --------- | --------- | ---- | ------------------------------------- | 458| profileId | [ProfileId](js-apis-bluetooth-constant.md#profileid) | No | ID of the target profile, for example, **PROFILE_A2DP_SOURCE**.| 459 460**Return value** 461 462| Type | Description | 463| ------------------------------------------------- | ------------------- | 464| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | Profile connection state obtained.| 465 466**Error codes** 467 468For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 469 470| ID| Error Message| 471| -------- | ---------------------------- | 472|201 | Permission denied. | 473|401 | Invalid parameter. Possible causes: 1. Incorrect parameter types. | 474|801 | Capability not supported. | 475|2900001 | Service stopped. | 476|2900003 | Bluetooth disabled. | 477|2900004 | Profile not supported. | 478|2900099 | Operation failed. | 479 480**Example** 481 482```js 483import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 484import { constant } from '@kit.ConnectivityKit'; 485try { 486 let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE); 487} catch (err) { 488 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 489} 490``` 491 492 493## connection.setDevicePairingConfirmation 494 495setDevicePairingConfirmation(deviceId: string, accept: boolean): void 496 497Sets the device pairing confirmation. 498 499**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH (available only for system applications) 500 501**System capability**: SystemCapability.Communication.Bluetooth.Core 502 503**Parameters** 504 505| Name | Type | Mandatory | Description | 506| ------ | ------- | ---- | -------------------------------- | 507| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 508| accept | boolean | Yes | Whether to accept the pairing request. The value **true** means to accept the pairing request, and the value **false** means the opposite. | 509 510**Error codes** 511 512For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 513 514| ID| Error Message| 515| -------- | ---------------------------- | 516|201 | Permission denied. | 517|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 518|801 | Capability not supported. | 519|2900001 | Service stopped. | 520|2900003 | Bluetooth disabled. | 521|2900099 | Operation failed. | 522 523**Example** 524 525```js 526import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 527// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the remote device. 528function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data is the input parameter for the pairing request. 529 console.info('pin required = '+ JSON.stringify(data)); 530 connection.setDevicePairingConfirmation(data.deviceId, true); 531} 532try { 533 connection.on('pinRequired', onReceivePinRequiredEvent); 534} catch (err) { 535 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 536} 537``` 538 539 540## connection.setDevicePinCode 541 542setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void 543 544Sets the PIN for the device when **PinType** is **PIN_TYPE_ENTER_PIN_CODE** or **PIN_TYPE_PIN_16_DIGITS**. This API uses an asynchronous callback to return the result. 545 546**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 547 548**System capability**: SystemCapability.Communication.Bluetooth.Core 549 550**Parameters** 551 552| Name | Type | Mandatory | Description | 553| ------ | ------- | ---- | -------------------------------- | 554| deviceId | string | Yes | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 555| code | string | Yes | PIN to set. | 556| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 557 558**Error codes** 559 560For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 561 562| ID| Error Message| 563| -------- | ---------------------------- | 564|201 | Permission denied. | 565|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 566|801 | Capability not supported. | 567|2900001 | Service stopped. | 568|2900003 | Bluetooth disabled. | 569|2900099 | Operation failed. | 570 571**Example** 572 573```js 574import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 575//callback 576try { 577 connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => { 578 console.info('setDevicePinCode,device name err:' + JSON.stringify(err)); 579 }); 580} catch (err) { 581 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 582} 583``` 584 585 586## connection.setDevicePinCode 587 588setDevicePinCode(deviceId: string, code: string): Promise<void> 589 590Sets the PIN for the device when **PinType** is **PIN_TYPE_ENTER_PIN_CODE** or **PIN_TYPE_PIN_16_DIGITS**. This API uses a promise to return the result. 591 592**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 593 594**System capability**: SystemCapability.Communication.Bluetooth.Core 595 596**Parameters** 597 598| Name | Type | Mandatory | Description | 599| ------ | ------- | ---- | -------------------------------- | 600| deviceId | string | Yes | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 601| code | string | Yes | PIN to set. | 602 603**Return value** 604 605| Type | Description | 606| ------------------- | ------------- | 607| Promise<void> | Promise used to return the result.| 608 609**Error codes** 610 611For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 612 613| ID| Error Message| 614| -------- | ---------------------------- | 615|201 | Permission denied. | 616|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 617|801 | Capability not supported. | 618|2900001 | Service stopped. | 619|2900003 | Bluetooth disabled. | 620|2900099 | Operation failed. | 621 622**Example** 623 624```js 625import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 626//promise 627try { 628 connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { 629 console.info('setDevicePinCode'); 630 }, (error: BusinessError) => { 631 console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); 632 }) 633 634} catch (err) { 635 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 636} 637``` 638 639 640## connection.setLocalName<sup>(deprecated)</sup> 641 642setLocalName(name: string): void 643 644Sets the name of the local Bluetooth device. 645 646> **NOTE**<br> 647> This API is supported since API version 10 and deprecated since API version 12. No substitute is provided. 648 649**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 650 651**System capability**: SystemCapability.Communication.Bluetooth.Core 652 653**Parameters** 654 655| Name | Type | Mandatory | Description | 656| ---- | ------ | ---- | --------------------- | 657| name | string | Yes | Bluetooth device name to set. It cannot exceed 248 bytes.| 658 659**Error codes** 660 661For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 662 663| ID| Error Message| 664| -------- | ---------------------------- | 665|201 | Permission denied. | 666|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 667|801 | Capability not supported. | 668|2900001 | Service stopped. | 669|2900003 | Bluetooth disabled. | 670|2900099 | Operation failed. | 671 672**Example** 673 674```js 675import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 676try { 677 connection.setLocalName('device_name'); 678} catch (err) { 679 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 680} 681``` 682 683 684## connection.setBluetoothScanMode 685 686setBluetoothScanMode(mode: ScanMode, duration: number): void 687 688Sets the Bluetooth scan mode so that the device can be discovered by a remote device. 689 690**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 691 692**System capability**: SystemCapability.Communication.Bluetooth.Core 693 694**Parameters** 695 696| Name | Type | Mandatory | Description | 697| -------- | --------------------- | ---- | ---------------------------- | 698| mode | [ScanMode](#scanmode) | Yes | Bluetooth scan mode to set. If the scan times out (**duration** is not **0**) when the scan mode is **SCAN_MODE_GENERAL_DISCOVERABLE**, the scan mode will be reset to **SCAN_MODE_CONNECTABLE**. | 699| duration | number | Yes | Duration (in ms) in which the device can be discovered. The value **0** indicates unlimited time.| 700 701**Error codes** 702 703For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 704 705| ID| Error Message| 706| -------- | ---------------------------- | 707|201 | Permission denied. | 708|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 709|801 | Capability not supported. | 710|2900001 | Service stopped. | 711|2900003 | Bluetooth disabled. | 712|2900099 | Operation failed. | 713 714**Example** 715 716```js 717import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 718try { 719 // The device can be discovered and connected only when the discoverable and connectable mode is used. 720 connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); 721} catch (err) { 722 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 723} 724``` 725 726 727## connection.getBluetoothScanMode 728 729getBluetoothScanMode(): ScanMode 730 731Obtains the Bluetooth scan mode. 732 733**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 734 735**System capability**: SystemCapability.Communication.Bluetooth.Core 736 737**Return value** 738 739| Type | Description | 740| --------------------- | ------- | 741| [ScanMode](#scanmode) | Bluetooth scan mode obtained.| 742 743**Error codes** 744 745For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 746 747| ID| Error Message| 748| -------- | ---------------------------- | 749|201 | Permission denied. | 750|801 | Capability not supported. | 751|2900001 | Service stopped. | 752|2900003 | Bluetooth disabled. | 753|2900099 | Operation failed. | 754 755**Example** 756 757```js 758import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 759try { 760 let scanMode: connection.ScanMode = connection.getBluetoothScanMode(); 761} catch (err) { 762 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 763} 764``` 765 766 767## connection.startBluetoothDiscovery 768 769startBluetoothDiscovery(): void 770 771Starts to discover Bluetooth devices. 772 773**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 774 775**Atomic service API**: This API can be used in atomic services since API version 12. 776 777**System capability**: SystemCapability.Communication.Bluetooth.Core 778 779**Error codes** 780 781For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 782 783| ID| Error Message| 784| -------- | ---------------------------- | 785|201 | Permission denied. | 786|801 | Capability not supported. | 787|2900001 | Service stopped. | 788|2900003 | Bluetooth disabled. | 789|2900099 | Operation failed. | 790 791**Example** 792 793```js 794import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 795function onReceiveEvent(data: Array<string>) { 796 console.info('data length' + data.length); 797} 798try { 799 connection.on('bluetoothDeviceFind', onReceiveEvent); 800 connection.startBluetoothDiscovery(); 801} catch (err) { 802 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 803} 804``` 805 806 807## connection.stopBluetoothDiscovery 808 809stopBluetoothDiscovery(): void 810 811Stops discovering Bluetooth devices. 812 813**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 814 815**Atomic service API**: This API can be used in atomic services since API version 12. 816 817**System capability**: SystemCapability.Communication.Bluetooth.Core 818 819**Error codes** 820 821For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 822 823| ID| Error Message| 824| -------- | ---------------------------- | 825|201 | Permission denied. | 826|801 | Capability not supported. | 827|2900001 | Service stopped. | 828|2900003 | Bluetooth disabled. | 829|2900099 | Operation failed. | 830 831**Example** 832 833```js 834import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 835try { 836 connection.stopBluetoothDiscovery(); 837} catch (err) { 838 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 839} 840``` 841 842 843## connection.isBluetoothDiscovering<sup>11+</sup> 844 845isBluetoothDiscovering(): boolean 846 847Checks whether Bluetooth discovery is enabled. 848 849**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 850 851**System capability**: SystemCapability.Communication.Bluetooth.Core 852 853**Return value** 854 855| Type | Description | 856| ------------------- | ------------- | 857| boolean | Returns **true** if Bluetooth discovery is enabled; returns **false** otherwise.| 858 859**Error codes** 860 861For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 862 863| ID| Error Message| 864| -------- | ---------------------------- | 865|201 | Permission denied. | 866|801 | Capability not supported. | 867|2900001 | Service stopped. | 868|2900003 | Bluetooth disabled. | 869|2900099 | Operation failed. | 870 871**Example** 872 873```js 874import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 875try { 876 let res: boolean = connection.isBluetoothDiscovering(); 877 console.info('isBluetoothDiscovering: ' + res); 878} catch (err) { 879 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 880} 881``` 882 883## connection.setRemoteDeviceName<sup>12+</sup> 884 885setRemoteDeviceName(deviceId: string, name: string): Promise<void> 886 887Sets the name of a remote Bluetooth device. This API uses a promise to return the result. 888 889**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 890 891**Atomic service API**: This API can be used in atomic services since API version 12. 892 893**System capability**: SystemCapability.Communication.Bluetooth.Core 894 895**Parameters** 896 897| Name | Type | Mandatory | Description | 898| -------- | ----------------------------------- | ---- | -------------------------------------- | 899| deviceId | string | Yes | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 900| name | string | Yes | Name of the remote device to set. The name cannot exceed 64 bytes. | 901 902**Return value** 903 904| Type | Description | 905| ------------------- | ------------- | 906| Promise<void> | Promise used to return the device name set. If the operation fails, an error code is returned.| 907 908**Error codes** 909 910For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 911 912| ID| Error Message| 913| -------- | ---------------------------- | 914|201 | Permission denied. | 915|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 916|2900001 | Service stopped. | 917|2900003 | Bluetooth disabled. | 918 919**Example** 920 921```js 922import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 923//promise 924try { 925 connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => { 926 console.info('setRemoteDeviceName success'); 927 }, (error: BusinessError) => { 928 console.error('setRemoteDeviceName: errCode:' + error.code + ',errMessage' + error.message); 929 }) 930 931} catch (err) { 932 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 933} 934``` 935 936 937## connection.getRemoteDeviceBatteryInfo<sup>12+</sup> 938 939getRemoteDeviceBatteryInfo(deviceId: string): Promise<BatteryInfo> 940 941obtains the battery information of a remote Bluetooth device. This API uses a promise to return the result. 942 943**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 944 945**System capability**: SystemCapability.Communication.Bluetooth.Core 946 947**Parameters** 948 949| Name | Type | Mandatory | Description | 950| ------ | ------- | ---- | -------------------------------- | 951| deviceId | string | Yes | MAC address of the remote device, for example, **11:22:33:AA:BB:FF**.| 952 953**Return value** 954 955| Type | Description | 956| ------------------- | ------------- | 957| Promise<[BatteryInfo](#batteryinfo12)> | Promise used to return the battery information obtained.| 958 959**Error codes** 960 961For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 962 963| ID| Error Message| 964| -------- | ---------------------------- | 965|201 | Permission denied. | 966|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 967|2900001 | Service stopped. | 968|2900003 | Bluetooth disabled. | 969 970**Example** 971 972```js 973import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 974// promise 975try { 976 connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => { 977 console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data)); 978 }); 979} catch (err) { 980 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 981} 982``` 983 984 985## connection.on('batteryChange')<sup>12+</sup> 986 987on(type: 'batteryChange', callback: Callback<BatteryInfo>): void 988 989Subscribes to the changes in the battery information of a remote Bluetooth device. This API uses an asynchronous callback to return the result. 990 991**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 992 993**System capability**: SystemCapability.Communication.Bluetooth.Core 994 995**Parameters** 996 997| Name | Type | Mandatory | Description | 998| -------- | ----------------------------------- | ---- | -------------------------------------- | 999| type | string | Yes | Event type. The value is **'batteryChange'**, which indicates the change in battery information of a remote Bluetooth device.| 1000| callback | Callback<[BatteryInfo](#batteryinfo12)> | Yes | Callback used to return the battery information. | 1001 1002**Error codes** 1003 1004For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1005 1006| ID| Error Message| 1007| -------- | ---------------------------- | 1008|201 | Permission denied. | 1009|2900099 | Operation failed. | 1010 1011**Example** 1012 1013```js 1014import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1015let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1016 console.info('BatteryInfo = '+ JSON.stringify(data)); 1017} 1018try { 1019 connection.on('batteryChange', onReceiveEvent); 1020} catch (err) { 1021 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1022} 1023``` 1024 1025 1026## connection.off('batteryChange')<sup>12+</sup> 1027 1028off(type: 'batteryChange', callback?: Callback<BatteryInfo>): void 1029 1030Unsubscribes from the changes in the battery information of a remote Bluetooth device. 1031 1032**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1033 1034**System capability**: SystemCapability.Communication.Bluetooth.Core 1035 1036**Parameters** 1037 1038| Name | Type | Mandatory | Description | 1039| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1040| type | string | Yes | Event type. The value is **'batteryChange'**, which indicates the change in battery information of a remote Bluetooth device. | 1041| callback | Callback<[BatteryInfo](#batteryinfo12)> | No | Callback to unregister.| 1042 1043**Error codes** 1044 1045For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1046 1047| ID| Error Message| 1048| -------- | ---------------------------- | 1049|201 | Permission denied. | 1050|2900099 | Operation failed. | 1051 1052**Example** 1053 1054```js 1055import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1056let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1057 console.info('BatteryInfo = '+ JSON.stringify(data)); 1058} 1059try { 1060 connection.on('batteryChange', onReceiveEvent); 1061 connection.off('batteryChange', onReceiveEvent); 1062} catch (err) { 1063 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1064} 1065``` 1066 1067 1068## connection.on('bluetoothDeviceFind') 1069 1070on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void 1071 1072Subscribes to the discovery of a Bluetooth device. This API uses an asynchronous callback to return the result. 1073 1074**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1075 1076**Atomic service API**: This API can be used in atomic services since API version 12. 1077 1078**System capability**: SystemCapability.Communication.Bluetooth.Core 1079 1080**Parameters** 1081 1082| Name | Type | Mandatory | Description | 1083| -------- | ----------------------------------- | ---- | -------------------------------------- | 1084| type | string | Yes | Event type. The value is **bluetoothDeviceFind**, which indicates an event of discovering a Bluetooth device.| 1085| callback | Callback<Array<string>> | Yes | Callback used to return the discovered devices. You need to implement this callback. For security purposes, the device addresses are random MAC addresses. The random MAC address remains unchanged after a device is paired successfully. It changes when the paired device is unpaired and scanned again or the Bluetooth service is turned off. | 1086 1087**Error codes** 1088 1089For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1090 1091| ID| Error Message| 1092| -------- | ---------------------------- | 1093|201 | Permission denied. | 1094|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1095|801 | Capability not supported. | 1096|2900099 | Operation failed. | 1097 1098**Example** 1099 1100```js 1101import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1102function onReceiveEvent(data: Array<string>) { // data is an array of Bluetooth device addresses. 1103 console.info('bluetooth device find = '+ JSON.stringify(data)); 1104} 1105try { 1106 connection.on('bluetoothDeviceFind', onReceiveEvent); 1107} catch (err) { 1108 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1109} 1110``` 1111 1112 1113## connection.off('bluetoothDeviceFind') 1114 1115off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void 1116 1117Unsubscribes from the discovery of a Bluetooth device. 1118 1119**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1120 1121**Atomic service API**: This API can be used in atomic services since API version 12. 1122 1123**System capability**: SystemCapability.Communication.Bluetooth.Core 1124 1125**Parameters** 1126 1127| Name | Type | Mandatory | Description | 1128| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1129| type | string | Yes | Event type. The value is **bluetoothDeviceFind**, which indicates an event of discovering a Bluetooth device. | 1130| callback | Callback<Array<string>> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| 1131 1132**Error codes** 1133 1134For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1135 1136| ID| Error Message| 1137| -------- | ---------------------------- | 1138|201 | Permission denied. | 1139|801 | Capability not supported. | 1140|2900099 | Operation failed. | 1141 1142**Example** 1143 1144```js 1145import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1146function onReceiveEvent(data: Array<string>) { 1147 console.info('bluetooth device find = '+ JSON.stringify(data)); 1148} 1149try { 1150 connection.on('bluetoothDeviceFind', onReceiveEvent); 1151 connection.off('bluetoothDeviceFind', onReceiveEvent); 1152} catch (err) { 1153 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1154} 1155``` 1156 1157 1158## connection.on('bondStateChange') 1159 1160on(type: 'bondStateChange', callback: Callback<BondStateParam>): void 1161 1162Subscribes to Bluetooth pairing state changes. This API uses an asynchronous callback to return the result. 1163 1164**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1165 1166**System capability**: SystemCapability.Communication.Bluetooth.Core 1167 1168**Parameters** 1169 1170| Name | Type | Mandatory | Description | 1171| -------- | ---------------------------------------- | ---- | ------------------------------------ | 1172| type | string | Yes | Event type. The value is **bondStateChange**, which indicates a Bluetooth pairing state change event.| 1173| callback | Callback<[BondStateParam](#bondstateparam)> | Yes | Callback used to return the pairing state. You need to implement this callback. | 1174 1175**Error codes** 1176 1177For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1178 1179| ID| Error Message| 1180| -------- | ---------------------------- | 1181|201 | Permission denied. | 1182|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1183|801 | Capability not supported. | 1184|2900099 | Operation failed. | 1185 1186**Example** 1187 1188```js 1189import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1190function onReceiveEvent(data: connection.BondStateParam) { // data, as the input parameter of the callback, indicates the pairing state. 1191 console.info('pair state = '+ JSON.stringify(data)); 1192} 1193try { 1194 connection.on('bondStateChange', onReceiveEvent); 1195} catch (err) { 1196 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1197} 1198``` 1199 1200 1201## connection.off('bondStateChange') 1202 1203off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void 1204 1205Unsubscribes from Bluetooth pairing state changes. 1206 1207**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1208 1209**System capability**: SystemCapability.Communication.Bluetooth.Core 1210 1211**Parameters** 1212 1213| Name | Type | Mandatory | Description | 1214| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1215| type | string | Yes | Event type. The value is **bondStateChange**, which indicates a Bluetooth pairing state change event. | 1216| callback | Callback<[BondStateParam](#bondstateparam)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| 1217 1218**Error codes** 1219 1220For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1221 1222| ID| Error Message| 1223| -------- | ---------------------------- | 1224|201 | Permission denied. | 1225|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1226|801 | Capability not supported. | 1227|2900099 | Operation failed. | 1228 1229**Example** 1230 1231```js 1232import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1233function onReceiveEvent(data: connection.BondStateParam) { 1234 console.info('bond state = '+ JSON.stringify(data)); 1235} 1236try { 1237 connection.on('bondStateChange', onReceiveEvent); 1238 connection.off('bondStateChange', onReceiveEvent); 1239} catch (err) { 1240 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1241} 1242``` 1243 1244 1245## connection.on('pinRequired') 1246 1247on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void 1248 1249Subscribes to the pairing request events of the remote Bluetooth device. This API uses an asynchronous callback to return the result. 1250 1251**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1252 1253**System capability**: SystemCapability.Communication.Bluetooth.Core 1254 1255**Parameters** 1256 1257| Name | Type | Mandatory | Description | 1258| -------- | ---------------------------------------- | ---- | -------------------------------- | 1259| type | string | Yes | Event type. The value **pinRequired** indicates a pairing request event. | 1260| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | Yes | Callback used to return the pairing request. You need to implement this callback.| 1261 1262**Error codes** 1263 1264For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1265 1266| ID| Error Message| 1267| -------- | ---------------------------- | 1268|201 | Permission denied. | 1269|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1270|801 | Capability not supported. | 1271|2900099 | Operation failed. | 1272 1273**Example** 1274 1275```js 1276import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1277function onReceiveEvent(data: connection.PinRequiredParam) { // data is the pairing request parameter. 1278 console.info('pin required = '+ JSON.stringify(data)); 1279} 1280try { 1281 connection.on('pinRequired', onReceiveEvent); 1282} catch (err) { 1283 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1284} 1285``` 1286 1287 1288## connection.off('pinRequired') 1289 1290off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void 1291 1292Unsubscribes from the pairing request events of the remote Bluetooth device. 1293 1294**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1295 1296**System capability**: SystemCapability.Communication.Bluetooth.Core 1297 1298**Parameters** 1299 1300| Name | Type | Mandatory | Description | 1301| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1302| type | string | Yes | Event type. The value **pinRequired** indicates a pairing request event. | 1303| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | No | Callback to unregister. The input parameter is the pairing request parameter. If this parameter is not set, this API unregisters all callbacks for the specified **type**.| 1304 1305**Error codes** 1306 1307For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 1308 1309| ID| Error Message| 1310| -------- | ---------------------------- | 1311|201 | Permission denied. | 1312|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1313|801 | Capability not supported. | 1314|2900099 | Operation failed. | 1315 1316**Example** 1317 1318```js 1319import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1320function onReceiveEvent(data: connection.PinRequiredParam) { 1321 console.info('pin required = '+ JSON.stringify(data)); 1322} 1323try { 1324 connection.on('pinRequired', onReceiveEvent); 1325 connection.off('pinRequired', onReceiveEvent); 1326} catch (err) { 1327 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1328} 1329``` 1330 1331 1332## BondStateParam 1333 1334Represents the pairing state parameters. 1335 1336**System capability**: SystemCapability.Communication.Bluetooth.Core 1337 1338| Name | Type | Readable | Writable | Description | 1339| -------- | ------ | ---- | ---- | ----------- | 1340| deviceId | string | Yes | No | ID of the device to pair.| 1341| state | BondState | Yes | No | State of the device.| 1342| cause<sup>12+</sup>| [UnbondCause](#unbondcause12) | Yes| No| Cause of the pairing failure.| 1343 1344 1345## PinRequiredParam 1346 1347Represents the pairing request parameters. 1348 1349**System capability**: SystemCapability.Communication.Bluetooth.Core 1350 1351| Name | Type | Readable | Writable | Description | 1352| -------- | ------ | ---- | ---- | ----------- | 1353| deviceId | string | Yes | No | ID of the device to pair.| 1354| pinCode | string | Yes | No | Key for the device pairing. | 1355 1356 1357 1358## DeviceClass 1359 1360Represents the class of a Bluetooth device. 1361 1362**System capability**: SystemCapability.Communication.Bluetooth.Core 1363 1364| Name | Type | Readable | Writable | Description | 1365| --------------- | ----------------------------------- | ---- | ---- | ---------------- | 1366| majorClass | [MajorClass](js-apis-bluetooth-constant.md#majorclass) | Yes | No | Major class of the Bluetooth device. | 1367| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | Yes | No | Major and minor classes of the Bluetooth device.| 1368| classOfDevice | number | Yes | No | Class of the device. | 1369 1370 1371## BatteryInfo<sup>12+</sup> 1372 1373Represents the battery information. 1374 1375**System capability**: SystemCapability.Communication.Bluetooth.Core 1376 1377| Name | Type | Readable | Writable | Description | 1378| -------- | ------ | ---- | ---- | ----------- | 1379| batteryLevel | number | Yes | No | Battery level of the remote device. If the value is **-1**, there is no battery information. | 1380| leftEarBatteryLevel | number | Yes | No | Battery level of the left earphone. If the value is **-1**, there is no battery information. | 1381| leftEarChargeState | [DeviceChargeState](#devicechargestate12) | Yes | No | Charging state of the left earphone. | 1382| rightEarBatteryLevel | number | Yes | No | Battery level of the right earphone. If the value is **-1**, there is no battery information. | 1383| rightEarChargeState | [DeviceChargeState](#devicechargestate12) | Yes | No | Charging state of the right earphone. | 1384| boxBatteryLevel | number | Yes | No | Battery level of the earbud compartment. If the value is **-1**, there is no battery information. | 1385| boxChargeState | [DeviceChargeState](#devicechargestate12) | Yes | No | Charging state of the earbud compartment. | 1386 1387 1388## BluetoothTransport 1389 1390Enumerates the device types. The default device type is **TRANSPORT_BR_EDR**. 1391 1392**System capability**: SystemCapability.Communication.Bluetooth.Core 1393 1394| Name | Value | Description | 1395| -------------------------------- | ------ | --------------- | 1396| TRANSPORT_BR_EDR | 0 | Classic Bluetooth (BR/EDR) device.| 1397| TRANSPORT_LE | 1 | BLE device. | 1398 1399 1400## ScanMode 1401 1402Enumerates the scan modes. 1403 1404**System capability**: SystemCapability.Communication.Bluetooth.Core 1405 1406| Name | Value | Description | 1407| ---------------------------------------- | ---- | --------------- | 1408| SCAN_MODE_NONE | 0 | No scan mode. | 1409| SCAN_MODE_CONNECTABLE | 1 | Connectable mode. | 1410| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | General discoverable mode. | 1411| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | Limited discoverable mode. | 1412| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | General connectable and discoverable mode.| 1413| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | Limited connectable and discoverable mode.| 1414 1415 1416## BondState 1417 1418Enumerates the pairing states. 1419 1420**Atomic service API**: This API can be used in atomic services since API version 12. 1421 1422**System capability**: SystemCapability.Communication.Bluetooth.Core 1423 1424| Name | Value | Description | 1425| ------------------ | ---- | ------ | 1426| BOND_STATE_INVALID | 0 | Invalid pairing.| 1427| BOND_STATE_BONDING | 1 | Pairing. | 1428| BOND_STATE_BONDED | 2 | Paired. | 1429 1430 1431## UnbondCause<sup>12+</sup> 1432 1433Enumerates the possible causes of a pairing failure. 1434 1435**System capability**: SystemCapability.Communication.Bluetooth.Core 1436 1437| Name | Value | Description | 1438| ------------------ | ---- | ------ | 1439| USER_REMOVED | 0 | The user proactively removes the device.| 1440| REMOTE_DEVICE_DOWN | 1 | The remote device is shut down.| 1441| AUTH_FAILURE | 2 | The PIN is incorrect.| 1442| AUTH_REJECTED | 3 | The remote device authentication is rejected.| 1443| INTERNAL_ERROR | 4 | Internal error.| 1444 1445 1446## DeviceChargeState<sup>12+</sup> 1447 1448Enumerates the charging states. 1449 1450**System capability**: SystemCapability.Communication.Bluetooth.Core 1451 1452| Name | Value | Description | 1453| ------------------ | ---- | ------ | 1454| DEVICE_NORMAL_CHARGE_NOT_CHARGED | 0 | The device is not charged and does not support supercharging.| 1455| DEVICE_NORMAL_CHARGE_IN_CHARGING | 1 | The device is being charged and does not support supercharging.| 1456| DEVICE_SUPER_CHARGE_NOT_CHARGED | 2 | The device is not charged and supports supercharging.| 1457| DEVICE_SUPER_CHARGE_IN_CHARGING | 3 | The device is being charged and supports supercharging.| 1458