1# @ohos.bluetooth.connection (蓝牙connection模块)(系统接口) 2 3connection模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.bluetooth.connection (蓝牙connection模块)](js-apis-bluetooth-connection.md) 9 10 11## 导入模块 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 22向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。使用Callback异步回调。 23 24**系统接口**：此接口为系统接口。 25 26**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 27 28**系统能力**：SystemCapability.Communication.Bluetooth.Core 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| -------- | ------ | ---- | ----------------------------------- | 34| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 35| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | 36| callback | AsyncCallback<void> | 是 | 回调函数。当发起配对成功，err为undefined，否则为错误对象。 | 37 38**错误码**： 39 40以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 41 42| 错误码ID | 错误信息 | 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**示例：** 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 75向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。使用Promise异步回调。 76 77**系统接口**：此接口为系统接口。 78 79**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 80 81**系统能力**：SystemCapability.Communication.Bluetooth.Core 82 83**参数：** 84 85| 参数名 | 类型 | 必填 | 说明 | 86| -------- | ------ | ---- | ----------------------------------- | 87| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 88| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | 是 | 表示设备类型，例如传统蓝牙设备或低功耗蓝牙设备。 | 89 90**返回值：** 91 92| 类型 | 说明 | 93| ------------------------------------------------- | ------------------- | 94| Promise<void> | 返回promise对象。 | 95 96**错误码**： 97 98以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 99 100| 错误码ID | 错误信息 | 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**示例：** 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 130删除配对的远程设备。使用Callback异步回调。 131 132**系统接口**：此接口为系统接口。 133 134**需要权限**：ohos.permission.ACCESS_BLUETOOTH 135 136**系统能力**：SystemCapability.Communication.Bluetooth.Core 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| -------- | ------ | ---- | ------------------------------------- | 142| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 143| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | 144 145**错误码**： 146 147以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 148 149| 错误码ID | 错误信息 | 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**示例：** 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 178删除配对的远程设备。使用Promise异步回调。 179 180**系统接口**：此接口为系统接口。 181 182**需要权限**：ohos.permission.ACCESS_BLUETOOTH 183 184**系统能力**：SystemCapability.Communication.Bluetooth.Core 185 186**参数：** 187 188| 参数名 | 类型 | 必填 | 说明 | 189| -------- | ------ | ---- | ------------------------------------- | 190| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 191 192**返回值：** 193 194| 类型 | 说明 | 195| ------------------- | ------------- | 196| Promise<void> | 返回promise对象。 | 197 198**错误码**： 199 200以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 201 202| 错误码ID | 错误信息 | 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**示例：** 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 234删除正在配对中的远程设备。使用Callback异步回调。 235 236**系统接口**：此接口为系统接口。 237 238**需要权限**：ohos.permission.ACCESS_BLUETOOTH 239 240**系统能力**：SystemCapability.Communication.Bluetooth.Core 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245| -------- | ------ | ---- | ------------------------------------- | 246| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 247| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | 248 249**错误码**： 250 251以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 252 253| 错误码ID | 错误信息 | 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**示例：** 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 279删除正在配对中的远程设备。使用Promise异步回调。 280 281**系统接口**：此接口为系统接口。 282 283**需要权限**：ohos.permission.ACCESS_BLUETOOTH 284 285**系统能力**：SystemCapability.Communication.Bluetooth.Core 286 287**参数：** 288 289| 参数名 | 类型 | 必填 | 说明 | 290| -------- | ------ | ---- | ------------------------------------- | 291| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 292 293**返回值：** 294 295| 类型 | 说明 | 296| ------------------- | ------------- | 297| Promise<void> | 返回promise对象。 | 298 299**错误码**： 300 301以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 302 303| 错误码ID | 错误信息 | 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**示例：** 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 329获取本地设备的profile UUID。使用Callback异步回调。 330 331**系统接口**：此接口为系统接口。 332 333**需要权限**：ohos.permission.ACCESS_BLUETOOTH 334 335**系统能力**：SystemCapability.Communication.Bluetooth.Core 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | ------ | ---- | ----------------------------------- | 341| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | 342 343**错误码**： 344 345以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 346 347| 错误码ID | 错误信息 | 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**示例：** 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 375获取本地设备的profile UUID。使用Promise异步回调。 376 377**系统接口**：此接口为系统接口。 378 379**需要权限**：ohos.permission.ACCESS_BLUETOOTH 380 381**系统能力**：SystemCapability.Communication.Bluetooth.Core 382 383**返回值：** 384 385| 类型 | 说明 | 386| ------------------- | ------------- | 387| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids)>> | 返回promise对象。 | 388 389**错误码**： 390 391以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 392 393| 错误码ID | 错误信息 | 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**示例：** 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 423断开远端设备所有连接的profiles。使用Callback异步回调。 424 425**系统接口**：此接口为系统接口。 426 427**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 428 429**系统能力**：SystemCapability.Communication.Bluetooth.Core 430 431**参数：** 432 433| 参数名 | 类型 | 必填 | 说明 | 434| -------- | ------ | ---- | ----------------------------------- | 435| deviceId | string | 是 | 表示断开的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 436| callback | AsyncCallback<void> | 是 | 以callback形式异步返回结果。当发起断开成功，err为undefined，否则为错误对象。 | 437 438**错误码**： 439 440以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 441 442| 错误码ID | 错误信息 | 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**示例：** 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 474断开远端设备所有连接的profiles。使用Promise异步回调。 475 476**系统接口**：此接口为系统接口。 477 478**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 479 480**系统能力**：SystemCapability.Communication.Bluetooth.Core 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| -------- | ------ | ---- | ----------------------------------- | 486| deviceId | string | 是 | 表示断开的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 487 488**返回值：** 489 490| 类型 | 说明 | 491| ------------------------------------------------- | ------------------- | 492| Promise<void> | 以Promise形式返回断开profiles的结果，返回true为成功，false为失败。 | 493 494**错误码**： 495 496以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 497 498| 错误码ID | 错误信息 | 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**示例：** 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 528获取对端蓝牙设备的Product ID。从API16开始不再校验ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH权限。 529 530**系统接口**：此接口为系统接口。 531 532**系统能力**：SystemCapability.Communication.Bluetooth.Core 533 534**参数：** 535 536| 参数名 | 类型 | 必填 | 说明 | 537| -------- | ------ | ---- | --------------------------------- | 538| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 539 540**返回值：** 541 542| 类型 | 说明 | 543| ------ | ------------- | 544| string | 以字符串格式返回设备Product ID。 | 545 546**错误码**： 547 548以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 549 550| 错误码ID | 错误信息 | 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**示例：** 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 573设置蓝牙远端设备自定义类型。使用Promise异步回调。 574 575**系统接口**：此接口为系统接口。 576 577**需要权限**：ohos.permission.ACCESS_BLUETOOTH 578 579**系统能力**：SystemCapability.Communication.Bluetooth.Core 580 581**参数：** 582 583| 参数名 | 类型 | 必填 | 说明 | 584| ------ | ------- | ---- | -------------------------------- | 585| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 586| type | [DeviceType](#devicetype12) | 是 | 表示设备类型。 | 587 588**返回值：** 589 590| 类型 | 说明 | 591| ------------------- | ------------- | 592| Promise<void> | 以Promise形式返回设置蓝牙远端设备类型的结果，设置失败时返回错误码信息。 | 593 594**错误码**： 595 596以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 597 598| 错误码ID | 错误信息 | 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**示例：** 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 624获取蓝牙远端设备自定义类型。使用Promise异步回调。从API18开始不再校验ohos.permission.ACCESS_BLUETOOTH权限。 625 626**系统接口**：此接口为系统接口。 627 628**系统能力**：SystemCapability.Communication.Bluetooth.Core 629 630**参数：** 631 632| 参数名 | 类型 | 必填 | 说明 | 633| ------ | ------- | ---- | -------------------------------- | 634| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 635 636**返回值：** 637 638| 类型 | 说明 | 639| ------------------- | ------------- | 640| Promise<[DeviceType](#devicetype12)> | 以Promise形式返回设置蓝牙远端设备类型的结果，返回值为设备类型。 | 641 642**错误码**： 643 644以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 645 646| 错误码ID | 错误信息 | 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**示例：** 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 672查找蓝牙耳机设备时，向耳机发送控制命令。使用Promise异步回调。 673 674**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请）。 675 676**系统能力**：SystemCapability.Communication.Bluetooth.Core 677 678**参数：** 679 680| 参数名 | 类型 | 必填 | 说明 | 681| ------ | ------- | ---- | -------------------------------- | 682| controlDeviceActionParams<sup>15+</sup> | [ControlDeviceActionParams](#controldeviceactionparams15) | 是 | 控制蓝牙外设的相关信息。 | 683 684**返回值：** 685 686| 类型 | 说明 | 687| ------------------- | ------------- | 688| Promise<void> | 返回promise对象。 | 689 690**错误码**： 691 692以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 693 694| 错误码ID | 错误信息 | 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**示例：** 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 730更新云设备到蓝牙设置。使用Promise异步回调。 731 732**系统接口**：此接口为系统接口。 733 734**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 735 736**系统能力**：SystemCapability.Communication.Bluetooth.Core 737 738**参数：** 739 740| 参数名 | 类型 | 必填 | 说明 | 741| ------ | ------- | ---- | -------------------------------- | 742| trustedPairedDevices | [TrustedPairedDevices](#trustedpaireddevices15) | 是 | 表示云设备列表。 | 743 744**返回值：** 745 746| 类型 | 说明 | 747| ------------------- | ------------- | 748| Promise<void> | 以Promise形式返回设置云设备的结果。设置失败时返回错误码信息。 | 749 750**错误码**： 751 752以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 753 754| 错误码ID | 错误信息 | 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**示例：** 765 766```js 767import { connection } from '@kit.ConnectivityKit'; 768// promise 769/** 770 * 更新云设备到蓝牙设置项。 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 811描述配对请求参数。 812 813**系统能力**：SystemCapability.Communication.Bluetooth.Core 814 815| 名称 | 类型 | 可读 | 可写 | 说明 | 816| -------- | ------ | ---- | ---- | ----------- | 817| pinType | [PinType](#pintype) | 是 | 否 | 表示要配对的设备类型。<br/>此接口为系统接口。 | 818 819## ControlDeviceActionParams<sup>15+</sup> 820 821控制命令的配置参数。 822 823**系统能力**：SystemCapability.Communication.Bluetooth.Core 824 825| 名称 | 类型 | 可读 | 可写 | 说明 | 826| -------- | ------ | ---- | ---- | ----------- | 827| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 828| type | [ControlType](#controltype15) | 是 | 否 | 表示控制类型。 | 829| typeValue | [ControlTypeValue](#controltypevalue15) | 是 | 否 | 表示控制动作。 | 830| controlObject | [ControlObject](#controlobject15) | 是 | 否 | 表示控制对象。| 831 832## PinType 833 834枚举，蓝牙配对类型。 835 836**系统接口：** 此接口为系统接口。 837 838**系统能力**：SystemCapability.Communication.Bluetooth.Core 839 840| 名称 | 值 | 说明 | 841| -------------------------------- | ------ | --------------- | 842| PIN_TYPE_ENTER_PIN_CODE | 0 | 用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 843| PIN_TYPE_ENTER_PASSKEY | 1 | 用户需要输入对端设备上显示的PASSKEY。<br/>此接口为系统接口。 | 844| PIN_TYPE_CONFIRM_PASSKEY | 2 | 用户需要确认本地设备上显示的PASSKEY。<br/>此接口为系统接口。 | 845| PIN_TYPE_NO_PASSKEY_CONSENT | 3 | 无PASSKEY，用户需要接受或拒绝配对请求。<br/>此接口为系统接口。 | 846| PIN_TYPE_NOTIFY_PASSKEY | 4 | 本地设备显示PASSKEY，用户需要在对端设备上输入该PASSKEY。<br/>此接口为系统接口。 | 847| PIN_TYPE_DISPLAY_PIN_CODE | 5 | bluetooth 2.0设备，用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 848| PIN_TYPE_OOB_CONSENT | 6 | 用户需要接受或拒绝OOB配对请求。<br/>此接口为系统接口。 | 849| PIN_TYPE_PIN_16_DIGITS | 7 | 用户需要输入对端设备上显示的16位PIN码。<br/>此接口为系统接口。 | 850 851 852 853## DeviceType<sup>12+</sup> 854 855枚举，蓝牙远程设备的自定义类型。 856 857**系统接口：** 此接口为系统接口。 858 859**系统能力**：SystemCapability.Communication.Bluetooth.Core 860 861| 名称 | 值 | 说明 | 862| -------------------------------- | ------ | --------------- | 863| DEVICE_TYPE_DEFAULT<sup>12+</sup> | 0 | 默认设备类型，与原类型一致。<br/>此接口为系统接口。 | 864| DEVICE_TYPE_CAR<sup>12+</sup> | 1 | 汽车。<br/>此接口为系统接口。 | 865| DEVICE_TYPE_HEADSET<sup>12+</sup> | 2 | 耳机。<br/>此接口为系统接口。 | 866| DEVICE_TYPE_HEARING<sup>12+</sup> | 3 | 助听器<br/>此接口为系统接口。 | 867| DEVICE_TYPE_GLASSES<sup>12+</sup> | 4 | 眼镜。<br/>此接口为系统接口。 | 868| DEVICE_TYPE_WATCH<sup>12+</sup> | 5 | 手表。<br/>此接口为系统接口。 | 869| DEVICE_TYPE_SPEAKER<sup>12+</sup> | 6 | 音响。<br/>此接口为系统接口。 | 870| DEVICE_TYPE_OTHERS<sup>12+</sup> | 7 | 其他设备。<br/>此接口为系统接口。 | 871 872 873## BatteryInfo<sup>12+</sup> 874 875描述电量信息的内容。 876 877**系统能力**：SystemCapability.Communication.Bluetooth.Core 878 879| 名称 | 类型 | 可读 | 可写 | 说明 | 880| -------- | ------ | ---- | ---- | ----------- | 881| deviceId | string | 是 | 否 | 表示远端设备的MAC地址。<br/>此接口为系统接口。 | 882 883 884## ControlType<sup>15+</sup> 885 886枚举，控制类型。 887 888**系统能力**：SystemCapability.Communication.Bluetooth.Core 889 890| 名称 | 值 | 说明 | 891| -------------------------------- | ------ | --------------- | 892| PLAY | 0 | 表示控制类型为播放。 | 893| VIBRATE | 1 | 表示控制类型为振动。 | 894| FLASH | 2 | 表示控制类型为闪光。 | 895| LOCK | 3 | 表示控制类型为锁定。 | 896 897 898## ControlTypeValue<sup>15+</sup> 899 900枚举，控制动作。 901 902**系统能力**：SystemCapability.Communication.Bluetooth.Core 903 904| 名称 | 值 | 说明 | 905| ------- | ---- | ---------- | 906| DISABLE | 0 | 表示禁用。 | 907| ENABLE | 1 | 表示使能。 | 908| QUERY | 2 | 表示查询。 | 909 910 911## ControlObject<sup>15+</sup> 912 913枚举，控制对象。 914 915**系统能力**：SystemCapability.Communication.Bluetooth.Core 916 917| 名称 | 值 | 说明 | 918| -------------- | ---- | -------------------- | 919| LEFT_EAR | 0 | 表示控制对象是左耳。 | 920| RIGHT_EAR | 1 | 表示控制对象是右耳。 | 921| LEFT_RIGHT_EAR | 2 | 表示控制对象是双耳。 | 922 923 924## TrustedPairedDevices<sup>15+</sup> 925 926云设备列表。 927 928**系统能力**：SystemCapability.Communication.Bluetooth.Core 929 930| 名称 | 类型 | 可读 | 可选 | 说明 | 931| -------- | ------ | ---- | ---- | ----------- | 932| trustedPairedDevices | Array<[TrustedPairedDevice](#trustedpaireddevice15)> | 是 | 否 | 表示云设备列表。 | 933 934## TrustedPairedDevice<sup>15+</sup> 935 936云设备信息。 937 938**系统能力**：SystemCapability.Communication.Bluetooth.Core。 939 940| 名称 | 类型 | 可读 | 可选 | 说明 | 941| -------- | ------ | ---- | ---- | ----------- | 942| sn | string | 是 | 否 | 表示设备的序列号。 | 943| deviceType | string | 是 | 否 | 表示设备类型。 | 944| modelId | string | 是 | 否 | 表示左侧耳机的充电状态。 | 945| manufactory | string | 是 | 否 | 表示制造商信息。 | 946| productId | string | 是 | 否 | 表示设备产品信息。 | 947| hiLinkVersion | string | 是 | 否 | 表示hilink版本信息。 | 948| macAddress | string | 是 | 否 | 表示设备MAC地址。 | 949| serviceType | string | 是 | 否 | 表示设备服务类型。 | 950| serviceId | string | 是 | 否 | 表示设备id。 | 951| deviceName | string | 是 | 否 | 表示设备名字。 | 952| uuids | string | 是 | 否 | 表示设备的UUID。 | 953| bluetoothClass | number | 是 | 否 | 表示远端设备类型。 | 954| token | ArrayBuffer | 是 | 否 | 表示设备的token信息。 | 955| deviceNameTime | number | 是 | 否 | 表示设备名字的修改时间。 | 956| secureAdvertisingInfo | ArrayBuffer | 是 | 否 | 表示设备广播信息。 | 957| pairState | number | 是 | 否 | 表示设备配对状态。 | 958