1# @ohos.bluetooth.connection (Bluetooth Connection Module) (System API) 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> This topic describes only the system APIs provided by the module. For details about its public APIs, see [@ohos.bluetooth.connection (Bluetooth Connection Module)](js-apis-bluetooth-connection.md). 9 10 11## Modules to Import 12 13```js 14import { connection } from '@kit.ConnectivityKit'; 15``` 16 17 18## connection.pairCredibleDevice 19 20pairCredibleDevice(deviceId: string, transport: BluetoothTransport, callback: AsyncCallback<void>): void 21 22Pairs a trusted device whose address is obtained in a non-Bluetooth scan mode (such as using NFC). This API uses an asynchronous callback to return the result. 23 24**System API**: This is a system API. 25 26**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 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| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | Yes | Device type, for example, a classic Bluetooth device or a Bluetooth low energy (BLE) device.| 36| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 37 38**Error codes** 39 40For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 41 42| ID| Error Message| 43| -------- | ---------------------------- | 44|201 | Permission denied. | 45|202 | Non-system applications are not allowed to use system APIs. | 46|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 47|801 | Capability not supported. | 48|2900001 | Service stopped. | 49|2900003 | Bluetooth disabled. | 50|2900099 | Operation failed. | 51 52**Example** 53 54```js 55import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 56try { 57 connection.pairCredibleDevice('68:13:24:79:4C:8C', connection.BluetoothTransport 58 .TRANSPORT_BR_EDR, (err: BusinessError) => { 59 if (err) { 60 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 61 return; 62 } 63 console.info('pairCredibleDevice, err: ' + JSON.stringify(err)); 64 }); 65} catch (err) { 66 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 67} 68``` 69 70 71## connection.pairCredibleDevice 72 73pairCredibleDevice(deviceId: string, transport: BluetoothTransport): Promise<void> 74 75Pairs a trusted device whose address is obtained in a non-Bluetooth scan mode (such as using NFC). This API uses a promise to return the result. 76 77**System API**: This is a system API. 78 79**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 80 81**System capability**: SystemCapability.Communication.Bluetooth.Core 82 83**Parameters** 84 85| Name | Type | Mandatory | Description | 86| -------- | ------ | ---- | ----------------------------------- | 87| deviceId | string | Yes | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.| 88| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | Yes | Device type, for example, a classic Bluetooth device or a BLE device.| 89 90**Return value** 91 92| Type | Description | 93| ------------------------------------------------- | ------------------- | 94| Promise<void> | Promise used to return the result.| 95 96**Error codes** 97 98For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 99 100| ID| Error Message| 101| -------- | ---------------------------- | 102|201 | Permission denied. | 103|202 | Non-system applications are not allowed to use system APIs. | 104|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 105|801 | Capability not supported. | 106|2900001 | Service stopped. | 107|2900003 | Bluetooth disabled. | 108|2900099 | Operation failed. | 109 110**Example** 111 112```js 113import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 114try { 115 connection.pairCredibleDevice('68:13:24:79:4C:8C', 0).then(() => { 116 console.info('PairCredibleDevice'); 117 }, (err: BusinessError) => { 118 console.error('PairCredibleDevice:errCode' + err.code + ', errMessage: ' + err.message); 119 }); 120} catch (err) { 121 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 122} 123``` 124 125 126## connection.cancelPairedDevice 127 128cancelPairedDevice(deviceId: string, callback: AsyncCallback<void>): void 129 130Cancels a paired device. This API uses an asynchronous callback to return the result. 131 132**System API**: This is a system API. 133 134**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 135 136**System capability**: SystemCapability.Communication.Bluetooth.Core 137 138**Parameters** 139 140| Name | Type | Mandatory | Description | 141| -------- | ------ | ---- | ------------------------------------- | 142| deviceId | string | Yes | Address of the device to cancel, for example, XX:XX:XX:XX:XX:XX.| 143| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 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|202 | Non-system applications are not allowed to use system APIs. | 153|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 154|801 | Capability not supported. | 155|2900001 | Service stopped. | 156|2900003 | Bluetooth disabled. | 157|2900099 | Operation failed. | 158 159**Example** 160 161```js 162import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 163// callback 164try { 165 connection.cancelPairedDevice('11:22:33:44:55:66', (err: BusinessError) => { 166 console.info('cancelPairedDevice, device name err:' + JSON.stringify(err)); 167 }); 168} catch (err) { 169 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 170} 171``` 172 173 174## connection.cancelPairedDevice 175 176cancelPairedDevice(deviceId: string): Promise<void> 177 178Cancels a paired device. This API uses a promise to return the result. 179 180**System API**: This is a system API. 181 182**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 183 184**System capability**: SystemCapability.Communication.Bluetooth.Core 185 186**Parameters** 187 188| Name | Type | Mandatory | Description | 189| -------- | ------ | ---- | ------------------------------------- | 190| deviceId | string | Yes | Address of the device to cancel, for example, XX:XX:XX:XX:XX:XX.| 191 192**Return value** 193 194| Type | Description | 195| ------------------- | ------------- | 196| Promise<void> | Promise used to return the result.| 197 198**Error codes** 199 200For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 201 202| ID| Error Message| 203| -------- | ---------------------------- | 204|201 | Permission denied. | 205|202 | Non-system applications are not allowed to use system APIs. | 206|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 207|801 | Capability not supported. | 208|2900001 | Service stopped. | 209|2900003 | Bluetooth disabled. | 210|2900099 | Operation failed. | 211 212**Example** 213 214```js 215import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 216// promise 217try { 218 connection.cancelPairedDevice('11:22:33:44:55:66').then(() => { 219 console.info('cancelPairedDevice'); 220 }, (error: BusinessError) => { 221 console.info('cancelPairedDevice: errCode:' + error.code + ',errMessage' + error.message); 222 }) 223 224} catch (err) { 225 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 226} 227``` 228 229 230## connection.cancelPairingDevice 231 232cancelPairingDevice(deviceId: string, callback: AsyncCallback<void>): void 233 234Cancels the pairing of a device. This API uses an asynchronous callback to return the result. 235 236**System API**: This is a system API. 237 238**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 239 240**System capability**: SystemCapability.Communication.Bluetooth.Core 241 242**Parameters** 243 244| Name | Type | Mandatory | Description | 245| -------- | ------ | ---- | ------------------------------------- | 246| deviceId | string | Yes | Address of the device to cancel, for example, XX:XX:XX:XX:XX:XX.| 247| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 248 249**Error codes** 250 251For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 252 253| ID| Error Message| 254| -------- | ---------------------------- | 255|201 | Permission denied. | 256|202 | Non-system applications are not allowed to use system APIs. | 257|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 258|801 | Capability not supported. | 259|2900001 | Service stopped. | 260|2900003 | Bluetooth disabled. | 261|2900099 | Operation failed. | 262 263**Example** 264 265```js 266import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 267try { 268 connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX'); 269} catch (err) { 270 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 271} 272``` 273 274 275## connection.cancelPairingDevice 276 277cancelPairingDevice(deviceId: string): Promise<void> 278 279Cancels the pairing of a device. This API uses a promise to return the result. 280 281**System API**: This is a system API. 282 283**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 284 285**System capability**: SystemCapability.Communication.Bluetooth.Core 286 287**Parameters** 288 289| Name | Type | Mandatory | Description | 290| -------- | ------ | ---- | ------------------------------------- | 291| deviceId | string | Yes | Address of the device to cancel, for example, XX:XX:XX:XX:XX:XX.| 292 293**Return value** 294 295| Type | Description | 296| ------------------- | ------------- | 297| Promise<void> | Promise used to return the result.| 298 299**Error codes** 300 301For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 302 303| ID| Error Message| 304| -------- | ---------------------------- | 305|201 | Permission denied. | 306|202 | Non-system applications are not allowed to use system APIs. | 307|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 308|801 | Capability not supported. | 309|2900001 | Service stopped. | 310|2900003 | Bluetooth disabled. | 311|2900099 | Operation failed. | 312 313**Example** 314 315```js 316import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 317try { 318 connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX'); 319} catch (err) { 320 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 321} 322``` 323 324 325## connection.getLocalProfileUuids 326 327getLocalProfileUuids(callback: AsyncCallback<Array<ProfileUuids>>): void 328 329Obtains the profile UUIDs of the local device. This API uses an asynchronous callback to return the result. 330 331**System API**: This is a system API. 332 333**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 334 335**System capability**: SystemCapability.Communication.Bluetooth.Core 336 337**Parameters** 338 339| Name | Type | Mandatory | Description | 340| -------- | ------ | ---- | ----------------------------------- | 341| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | Yes | Callback used to return the profile UUIDs obtained. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 342 343**Error codes** 344 345For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 346 347| ID| Error Message| 348| -------- | ---------------------------- | 349|201 | Permission denied. | 350|202 | Non-system applications are not allowed to use system APIs. | 351|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 352|801 | Capability not supported. | 353|2900001 | Service stopped. | 354|2900003 | Bluetooth disabled. | 355|2900099 | Operation failed. | 356 357**Example** 358 359```js 360import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 361try { 362 connection.getLocalProfileUuids((err: BusinessError, data: Array<connection.ProfileUuids>) => { 363 console.info('getLocalProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); 364 }); 365} catch (err) { 366 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 367} 368``` 369 370 371## connection.getLocalProfileUuids 372 373getLocalProfileUuids(): Promise<Array<ProfileUuids>> 374 375Obtains the profile UUIDs of the local device. This API uses a promise to return the result. 376 377**System API**: This is a system API. 378 379**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 380 381**System capability**: SystemCapability.Communication.Bluetooth.Core 382 383**Return value** 384 385| Type | Description | 386| ------------------- | ------------- | 387| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | Promise used to return the result.| 388 389**Error codes** 390 391For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 392 393| ID| Error Message| 394| -------- | ---------------------------- | 395|201 | Permission denied. | 396|202 | Non-system applications are not allowed to use system APIs. | 397|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 398|801 | Capability not supported. | 399|2900001 | Service stopped. | 400|2900003 | Bluetooth disabled. | 401|2900099 | Operation failed. | 402 403**Example** 404 405```js 406import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 407try { 408 connection.getLocalProfileUuids().then(() => { 409 console.info('getLocalProfileUuids'); 410 }, (err: BusinessError) => { 411 console.error('getLocalProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 412 }); 413} catch (err) { 414 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 415} 416``` 417 418 419## connection.disconnectAllowedProfiles<sup>11+</sup> 420 421disconnectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void 422 423Disconnects all connected profiles for a remote device. This API uses an asynchronous callback to return the result. 424 425**System API**: This is a system API. 426 427**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 428 429**System capability**: SystemCapability.Communication.Bluetooth.Core 430 431**Parameters** 432 433| Name | Type | Mandatory | Description | 434| -------- | ------ | ---- | ----------------------------------- | 435| deviceId | string | Yes | Address of the target remote device, for example, XX:XX:XX:XX:XX.| 436| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. | 437 438**Error codes** 439 440For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 441 442| ID| Error Message| 443| -------- | ---------------------------- | 444|201 | Permission denied. | 445|202 | Non-system applications are not allowed to use system APIs. | 446|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 447|801 | Capability not supported. | 448|2900001 | Service stopped. | 449|2900003 | Bluetooth disabled. | 450|2900099 | Operation failed. | 451 452**Example** 453 454```js 455import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 456try { 457 connection.disconnectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => { 458 if (err) { 459 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 460 return; 461 } 462 console.info('disconnectAllowedProfiles, err: ' + JSON.stringify(err)); 463 }); 464} catch (err) { 465 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 466} 467``` 468 469 470## connection.disconnectAllowedProfiles<sup>11+</sup> 471 472disconnectAllowedProfiles(deviceId: string): Promise<void> 473 474Disconnects all connected profiles for a remote device. This API uses a promise to return the result. 475 476**System API**: This is a system API. 477 478**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 479 480**System capability**: SystemCapability.Communication.Bluetooth.Core 481 482**Parameters** 483 484| Name | Type | Mandatory | Description | 485| -------- | ------ | ---- | ----------------------------------- | 486| deviceId | string | Yes | Address of the target remote device, for example, XX:XX:XX:XX:XX.| 487 488**Return value** 489 490| Type | Description | 491| ------------------------------------------------- | ------------------- | 492| Promise<void> | Promise used to return the result. If the operation is successful, **true** is returned; otherwise, **false** is returned.| 493 494**Error codes** 495 496For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 497 498| ID| Error Message| 499| -------- | ---------------------------- | 500|201 | Permission denied. | 501|202 | Non-system applications are not allowed to use system APIs. | 502|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 503|801 | Capability not supported. | 504|2900001 | Service stopped. | 505|2900003 | Bluetooth disabled. | 506|2900099 | Operation failed. | 507 508**Example** 509 510```js 511import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 512try { 513 connection.disconnectAllowedProfiles('68:13:24:79:4C:8C').then(() => { 514 console.info('disconnectAllowedProfiles'); 515 }, (err: BusinessError) => { 516 console.error('disconnectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message); 517 }); 518} catch (err) { 519 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 520} 521``` 522 523 524## connection.getRemoteProductId<sup>11+</sup> 525 526getRemoteProductId(deviceId: string): string 527 528Obtains the product ID of a remote Bluetooth device. Since API version 16, the **ohos.permission.ACCESS_BLUETOOTH** and **ohos.permission.MANAGE_BLUETOOTH** permissions are no longer verified. 529 530**System API**: This is a system API. 531 532**System capability**: SystemCapability.Communication.Bluetooth.Core 533 534**Parameters** 535 536| Name | Type | Mandatory | Description | 537| -------- | ------ | ---- | --------------------------------- | 538| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 539 540**Return value** 541 542| Type | Description | 543| ------ | ------------- | 544| string | Product ID obtained.| 545 546**Error codes** 547 548For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 549 550| ID| Error Message| 551| -------- | ---------------------------- | 552|202 | Non-system applications are not allowed to use system APIs. | 553|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 554|801 | Capability not supported. | 555|2900001 | Service stopped. | 556|2900003 | Bluetooth disabled. | 557|2900099 | Operation failed. | 558 559**Example** 560 561```js 562try { 563 let remoteDeviceProductId = connection.getRemoteProductId('XX:XX:XX:XX:XX:XX'); 564} catch (err) { 565 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 566} 567``` 568 569## connection.setRemoteDeviceType<sup>12+</sup> 570 571setRemoteDeviceType(deviceId: string, type: DeviceType): Promise<void> 572 573Sets the type of a remote Bluetooth device. This API uses a promise to return the result. 574 575**System API**: This is a system API. 576 577**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 578 579**System capability**: SystemCapability.Communication.Bluetooth.Core 580 581**Parameters** 582 583| Name | Type | Mandatory | Description | 584| ------ | ------- | ---- | -------------------------------- | 585| deviceId | string | Yes | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 586| type | [DeviceType](#devicetype12) | Yes | Device type to set. | 587 588**Return value** 589 590| Type | Description | 591| ------------------- | ------------- | 592| Promise<void> | Promise used to return the device type set. If the operation fails, an error code is returned.| 593 594**Error codes** 595 596For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 597 598| ID| Error Message| 599| -------- | ---------------------------- | 600|201 | Permission denied. | 601|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 602|2900001 | Service stopped. | 603|2900003 | Bluetooth disabled. | 604 605**Example** 606 607```js 608import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 609// promise 610try { 611 connection.setRemoteDeviceType('11:22:33:44:55:66', connection.DeviceType.DEVICE_TYPE_HEADSET).then(() => { 612 console.info('setRemoteDeviceType success'); 613 }); 614} catch (err) { 615 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 616} 617``` 618 619 620## connection.getRemoteDeviceType<sup>12+</sup> 621 622getRemoteDeviceType(deviceId: string): Promise<DeviceType> 623 624Obtains the type of a remote Bluetooth device. This API uses a promise to return the result. Since API version 18, the **ohos.permission.ACCESS_BLUETOOTH** permission is no longer verified. 625 626**System API**: This is a system API. 627 628**System capability**: SystemCapability.Communication.Bluetooth.Core 629 630**Parameters** 631 632| Name | Type | Mandatory | Description | 633| ------ | ------- | ---- | -------------------------------- | 634| deviceId | string | Yes | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 635 636**Return value** 637 638| Type | Description | 639| ------------------- | ------------- | 640| Promise<[DeviceType](#devicetype12)> | Promise used to return the device type obtained.| 641 642**Error codes** 643 644For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md). 645 646| ID| Error Message| 647| -------- | ---------------------------- | 648|202 | Non-system applications are not allowed to use system APIs. | 649|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 650|2900001 | Service stopped. | 651|2900003 | Bluetooth disabled. | 652 653**Example** 654 655```js 656import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 657// promise 658try { 659 connection.getRemoteDeviceType('11:22:33:44:55:66').then((data: connection.DeviceType) => { 660 console.info('getRemoteDeviceType success, DeviceType:' + JSON.stringify(data)); 661 }); 662} catch (err) { 663 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 664} 665``` 666 667 668## connection.controlDeviceAction<sup>15+</sup> 669 670controlDeviceAction(controlDeviceActionParams: ControlDeviceActionParams): Promise<void> 671 672Sends a control command to Bluetooth headsets during scanning. This API uses a promise to return the result. 673 674**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH (available only for system applications) 675 676**System capability**: SystemCapability.Communication.Bluetooth.Core 677 678**Parameters** 679 680| Name | Type | Mandatory | Description | 681| ------ | ------- | ---- | -------------------------------- | 682| controlDeviceActionParams<sup>15+</sup> | [ControlDeviceActionParams](#controldeviceactionparams15) | Yes | Bluetooth peripheral control information.| 683 684**Return value** 685 686| Type | Description | 687| ------------------- | ------------- | 688| Promise<void> | Promise used to return the result.| 689 690**Error codes** 691 692For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 693 694| ID| Error Message| 695| -------- | ---------------------------- | 696|201 | Permission denied. | 697|202 | Non-system applications are not allowed to use system APIs. | 698|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 699|801 | Capability not supported. | 700|2900001 | Service stopped. | 701|2900003 | Bluetooth disabled. | 702|2900099 | Operation failed. | 703 704**Example** 705 706```js 707import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 708try { 709 let controlDeviceActionParams: connection.ControlDeviceActionParams = { 710 deviceId: '40:DC:A5:E5:75:C3', 711 type: connection.ControlType.PLAY, 712 typeValue: connection.ControlTypeValue.ENABLE, 713 controlObject: connection.ControlObject.LEFT_EAR 714 }; 715 connection.controlDeviceAction(controlDeviceActionParams).then(() => { 716 console.info('controlDeviceAction success'); 717 }, (err: BusinessError) => { 718 console.error('controlDeviceAction: errCode' + err.code + ', errMessage: ' + err.message); 719 }); 720} catch (err) { 721 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 722} 723``` 724 725 726## connection.updateCloudBluetoothDevice<sup>15+</sup> 727 728updateCloudBluetoothDevice(trustedPairedDevices: TrustedPairedDevices): Promise<void> 729 730Updates cloud devices in Bluetooth settings. This API uses a promise to return the result. 731 732**System API**: This is a system API. 733 734**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 735 736**System capability**: SystemCapability.Communication.Bluetooth.Core 737 738**Parameters** 739 740| Name | Type | Mandatory | Description | 741| ------ | ------- | ---- | -------------------------------- | 742| trustedPairedDevices | [TrustedPairedDevices](#trustedpaireddevices15) | Yes | Cloud device list. | 743 744**Return value** 745 746| Type | Description | 747| ------------------- | ------------- | 748| Promise<void> | Promise used to return the result. If the setting fails, an error code is returned.| 749 750**Error codes** 751 752For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 753 754| ID| Error Message| 755| -------- | ---------------------------- | 756|201 | Permission denied. | 757|202 | Non-system applications are not allowed to use system APIs. | 758|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 759|801 | Capability not supported. | 760|2900001 | Service stopped. | 761|2900003 | Bluetooth disabled. | 762|2900099 | Operation failed. | 763 764**Example** 765 766```js 767import { connection } from '@kit.ConnectivityKit'; 768// promise 769/** 770 * Update cloud devices in Bluetooth settings. 771 */ 772public updateCloudBluetoothDevice() { 773 const trustPairDeviceArr: connection.TrustedPairedDevice[] = []; 774 let descBuffer = new ArrayBuffer(1); 775 trustPairDeviceArr.push({ 776 sn: '', 777 deviceType: '', 778 modelId: '', 779 manufactory: '', 780 productId: '', 781 hiLinkVersion: '', 782 macAddress: '11:22:33:44:55:66', 783 serviceType: '', 784 serviceId: '', 785 deviceName: '', 786 uuids: '', 787 bluetoothClass: 0, 788 token: descBuffer, 789 deviceNameTime: 0, 790 secureAdvertisingInfo: descBuffer, 791 pairState: 0 792 }); 793 const trustPairDevices: connection.TrustedPairedDevices = { trustedPairedDevices: trustPairDeviceArr }; 794 try { 795 connection.updateCloudBluetoothDevice(trustPairDevices) 796 .then(() => { 797 console.info('updateCloudBluetoothDevice success!'); 798 }) 799 .catch((err: BusinessError) => { 800 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 801 }); 802 } catch (err) { 803 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 804 } 805} 806``` 807 808 809## PinRequiredParam 810 811Represents the pairing request parameters. 812 813**System capability**: SystemCapability.Communication.Bluetooth.Core 814 815| Name | Type | Readable | Writable | Description | 816| -------- | ------ | ---- | ---- | ----------- | 817| pinType | [PinType](#pintype) | Yes | No | Type of the device to pair.<br>This is a system API. | 818 819## ControlDeviceActionParams<sup>15+</sup> 820 821Defines the configuration parameters of the control command. 822 823**System capability**: SystemCapability.Communication.Bluetooth.Core 824 825| Name | Type | Readable | Writable | Description | 826| -------- | ------ | ---- | ---- | ----------- | 827| deviceId | string | Yes | No| Device ID.| 828| type | [ControlType](#controltype15) | Yes | No | Control type.| 829| typeValue | [ControlTypeValue](#controltypevalue15) | Yes| No| Control action.| 830| controlObject | [ControlObject](#controlobject15) | Yes| No| Control object.| 831 832## PinType 833 834Enumerates the Bluetooth pairing types. 835 836**System API**: This is a system API. 837 838**System capability**: SystemCapability.Communication.Bluetooth.Core 839 840| Name | Value | Description | 841| -------------------------------- | ------ | --------------- | 842| PIN_TYPE_ENTER_PIN_CODE | 0 | The user needs to enter the PIN displayed on the peer device.<br>This is a system API.| 843| PIN_TYPE_ENTER_PASSKEY | 1 | The user needs to enter the PASSKEY displayed on the peer device.<br>This is a system API. | 844| PIN_TYPE_CONFIRM_PASSKEY | 2 | The user needs to confirm the PASSKEY displayed on the local device.<br>This is a system API. | 845| PIN_TYPE_NO_PASSKEY_CONSENT | 3 | There is no PASSKEY, and the user needs to accept or reject the pairing request.<br>This is a system API. | 846| PIN_TYPE_NOTIFY_PASSKEY | 4 | The user needs to enter the PASSKEY displayed on the local device on the peer device.<br>This is a system API. | 847| PIN_TYPE_DISPLAY_PIN_CODE | 5 | The user needs to enter the PIN displayed on the peer device for Bluetooth 2.0 devices.<br>This is a system API. | 848| PIN_TYPE_OOB_CONSENT | 6 | The user needs to accept or reject the out of band (OOB) pairing request.<br>This is a system API. | 849| PIN_TYPE_PIN_16_DIGITS | 7 | The user needs to enter the 16-digit PIN displayed on the peer device.<br>This is a system API. | 850 851 852 853## DeviceType<sup>12+</sup> 854 855Enumerates the custom types of a remote Bluetooth device. 856 857**System API**: This is a system API. 858 859**System capability**: SystemCapability.Communication.Bluetooth.Core 860 861| Name | Value | Description | 862| -------------------------------- | ------ | --------------- | 863| DEVICE_TYPE_DEFAULT<sup>12+</sup> | 0 | Default device type, which is the same as the original type.<br>This is a system API.| 864| DEVICE_TYPE_CAR<sup>12+</sup> | 1 | Car.<br>This is a system API. | 865| DEVICE_TYPE_HEADSET<sup>12+</sup> | 2 | Headset.<br>This is a system API. | 866| DEVICE_TYPE_HEARING<sup>12+</sup> | 3 | Hearing aid.<br>This is a system API. | 867| DEVICE_TYPE_GLASSES<sup>12+</sup> | 4 | Glasses. <br>This is a system API. | 868| DEVICE_TYPE_WATCH<sup>12+</sup> | 5 | Watch.<br>This is a system API. | 869| DEVICE_TYPE_SPEAKER<sup>12+</sup> | 6 | Speaker.<br>This is a system API. | 870| DEVICE_TYPE_OTHERS<sup>12+</sup> | 7 | Other device.<br>This is a system API. | 871 872 873## BatteryInfo<sup>12+</sup> 874 875Represents the battery information. 876 877**System capability**: SystemCapability.Communication.Bluetooth.Core 878 879| Name | Type | Readable | Writable | Description | 880| -------- | ------ | ---- | ---- | ----------- | 881| deviceId | string | Yes | No | MAC address of the remote device.<br>This is a system API.| 882 883 884## ControlType<sup>15+</sup> 885 886Enumerates control types. 887 888**System capability**: SystemCapability.Communication.Bluetooth.Core 889 890| Name | Value | Description | 891| -------------------------------- | ------ | --------------- | 892| PLAY | 0 | Play| 893| VIBRATE | 1 | Vibration| 894| FLASH | 2 | Flash| 895| LOCK | 3 | Lock| 896 897 898## ControlTypeValue<sup>15+</sup> 899 900Enumerates control actions. 901 902**System capability**: SystemCapability.Communication.Bluetooth.Core 903 904| Name | Value | Description | 905| ------- | ---- | ---------- | 906| DISABLE | 0 | Disable| 907| ENABLE | 1 | Enable| 908| QUERY | 2 | Query| 909 910 911## ControlObject<sup>15+</sup> 912 913Enumerates control objects. 914 915**System capability**: SystemCapability.Communication.Bluetooth.Core 916 917| Name | Value | Description | 918| -------------- | ---- | -------------------- | 919| LEFT_EAR | 0 | Left earbud.| 920| RIGHT_EAR | 1 | Right earbud.| 921| LEFT_RIGHT_EAR | 2 | Left and right earbuds.| 922 923 924## TrustedPairedDevices<sup>15+</sup> 925 926Defines the cloud device list. 927 928**System capability**: SystemCapability.Communication.Bluetooth.Core 929 930| Name | Type | Readable | Optional | Description | 931| -------- | ------ | ---- | ---- | ----------- | 932| trustedPairedDevices | Array<[TrustedPairedDevice](#trustedpaireddevice15)> | Yes | No | Cloud device list. | 933 934## TrustedPairedDevice<sup>15+</sup> 935 936Defines the cloud device information. 937 938**System capability**: SystemCapability.Communication.Bluetooth.Core 939 940| Name | Type | Readable | Optional | Description | 941| -------- | ------ | ---- | ---- | ----------- | 942| sn | string | Yes | No | Device SN. | 943| deviceType | string | Yes | No | Device type to set. | 944| modelId | string | Yes | No | Charging state of the left earbud. | 945| manufactory | string | Yes | No | Manufacturer information. | 946| productId | string | Yes | No | Product information. | 947| hiLinkVersion | string | Yes | No | HiLink version. | 948| macAddress | string | Yes | No | MAC address. | 949| serviceType | string | Yes | No | Service type. | 950| serviceId | string | Yes | No | Device ID. | 951| deviceName | string | Yes | No | Device name. | 952| uuids | string | Yes | No | Device UUID. | 953| bluetoothClass | number | Yes | No | Peer device type. | 954| token | ArrayBuffer | Yes | No | Device token information. | 955| deviceNameTime | number | Yes | No | Device name modification time. | 956| secureAdvertisingInfo | ArrayBuffer | Yes | No | Device advertising information. | 957| pairState | number | Yes | No | Device pairing status. | 958