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。 529 530**系统接口**：此接口为系统接口。 531 532**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 533 534**系统能力**：SystemCapability.Communication.Bluetooth.Core 535 536**参数：** 537 538| 参数名 | 类型 | 必填 | 说明 | 539| -------- | ------ | ---- | --------------------------------- | 540| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 541 542**返回值：** 543 544| 类型 | 说明 | 545| ------ | ------------- | 546| string | 以字符串格式返回设备Product ID。 | 547 548**错误码**： 549 550以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 551 552| 错误码ID | 错误信息 | 553| -------- | ---------------------------- | 554|201 | Permission denied. | 555|202 | Non-system applications are not allowed to use system APIs. | 556|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 557|801 | Capability not supported. | 558|2900001 | Service stopped. | 559|2900003 | Bluetooth disabled. | 560|2900099 | Operation failed. | 561 562**示例：** 563 564```js 565try { 566 let remoteDeviceProductId = connection.getRemoteProductId('XX:XX:XX:XX:XX:XX'); 567} catch (err) { 568 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 569} 570``` 571 572## connection.on('discoveryResult')<sup>12+</sup> 573 574on(type: 'discoveryResult', callback: Callback<Array<DiscoveryResult>>): void 575 576订阅蓝牙设备发现上报事件。使用Callback异步回调。 577 578**系统接口**：此接口为系统接口。 579 580**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.GET_BLUETOOTH_PEERS_MAC 581 582**系统能力**：SystemCapability.Communication.Bluetooth.Core。 583 584**参数：** 585 586| 参数名 | 类型 | 必填 | 说明 | 587| -------- | ----------------------------------- | ---- | -------------------------------------- | 588| type | string | 是 | 填写"discoveryResult"字符串，表示蓝牙设备发现事件。 | 589| callback | Callback<Array<[DiscoveryResult](#discoveryresult12)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 590 591**错误码**： 592 593以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 594 595| 错误码ID | 错误信息 | 596| -------- | ---------------------------- | 597|201 | Permission denied. | 598|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 599|801 | Capability not supported. | 600|2900099 | Operation failed. | 601 602**示例：** 603 604```js 605import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 606let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合 607 console.info('bluetooth device find = '+ JSON.stringify(data)); 608} 609try { 610 connection.on('discoveryResult', onReceiveEvent); 611} catch (err) { 612 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 613} 614``` 615 616 617## connection.off('discoveryResult')<sup>12+</sup> 618 619off(type: 'discoveryResult', callback?: Callback<Array<DiscoveryResult>>): void 620 621取消订阅蓝牙设备发现上报事件。 622 623**系统接口**：此接口为系统接口。 624 625**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.GET_BLUETOOTH_PEERS_MAC 626 627**系统能力**：SystemCapability.Communication.Bluetooth.Core。 628 629**参数：** 630 631| 参数名 | 类型 | 必填 | 说明 | 632| -------- | ----------------------------------- | ---- | ---------------------------------------- | 633| type | string | 是 | 填写"discoveryResult"字符串，表示蓝牙设备发现事件。 | 634| callback | Callback<Array<[DiscoveryResult](#discoveryresult12)>> | 否 | 表示取消订阅蓝牙设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 635 636**错误码**： 637 638以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 639 640| 错误码ID | 错误信息 | 641| -------- | ---------------------------- | 642|201 | Permission denied. | 643|801 | Capability not supported. | 644|2900099 | Operation failed. | 645 646**示例：** 647 648```js 649import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 650let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合 651 console.info('bluetooth device find = '+ JSON.stringify(data)); 652} 653try { 654 connection.on('discoveryResult', onReceiveEvent); 655 connection.off('discoveryResult', onReceiveEvent); 656} catch (err) { 657 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 658} 659``` 660 661 662## connection.setRemoteDeviceType<sup>12+</sup> 663 664setRemoteDeviceType(deviceId: string, type: DeviceType): Promise<void> 665 666设置蓝牙远端设备自定义类型。使用Promise异步回调。 667 668**系统接口**：此接口为系统接口。 669 670**需要权限**：ohos.permission.ACCESS_BLUETOOTH 671 672**系统能力**：SystemCapability.Communication.Bluetooth.Core 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| ------ | ------- | ---- | -------------------------------- | 678| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 679| type | [DeviceType](#devicetype12) | 是 | 表示设备类型。 | 680 681**返回值：** 682 683| 类型 | 说明 | 684| ------------------- | ------------- | 685| Promise<void> | 以Promise形式返回设置蓝牙远端设备类型的结果，设置失败时返回错误码信息。 | 686 687**错误码**： 688 689以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 690 691| 错误码ID | 错误信息 | 692| -------- | ---------------------------- | 693|201 | Permission denied. | 694|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 695|2900001 | Service stopped. | 696|2900003 | Bluetooth disabled. | 697 698**示例：** 699 700```js 701import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 702// promise 703try { 704 connection.setRemoteDeviceType('11:22:33:44:55:66', connection.DeviceType.DEVICE_TYPE_HEADSET).then(() => { 705 console.info('setRemoteDeviceType success'); 706 }); 707} catch (err) { 708 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 709} 710``` 711 712 713## connection.getRemoteDeviceType<sup>12+</sup> 714 715getRemoteDeviceType(deviceId: string): Promise<DeviceType> 716 717获取蓝牙远端设备自定义类型。使用Promise异步回调。 718 719**系统接口**：此接口为系统接口。 720 721**需要权限**：ohos.permission.ACCESS_BLUETOOTH 722 723**系统能力**：SystemCapability.Communication.Bluetooth.Core 724 725**参数：** 726 727| 参数名 | 类型 | 必填 | 说明 | 728| ------ | ------- | ---- | -------------------------------- | 729| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 730 731**返回值：** 732 733| 类型 | 说明 | 734| ------------------- | ------------- | 735| Promise<[DeviceType](#devicetype12)> | 以Promise形式返回设置蓝牙远端设备类型的结果，返回值为设备类型。 | 736 737**错误码**： 738 739以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 740 741| 错误码ID | 错误信息 | 742| -------- | ---------------------------- | 743|201 | Permission denied. | 744|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 745|2900001 | Service stopped. | 746|2900003 | Bluetooth disabled. | 747 748**示例：** 749 750```js 751import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 752// promise 753try { 754 connection.getRemoteDeviceType('11:22:33:44:55:66').then((data: connection.DeviceType) => { 755 console.info('getRemoteDeviceType success, DeviceType:' + JSON.stringify(data)); 756 }); 757} catch (err) { 758 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 759} 760``` 761 762 763## connection.controlDeviceAction<sup>15+</sup> 764 765controlDeviceAction(controlDeviceActionParams: ControlDeviceActionParams): Promise<void> 766 767查找蓝牙耳机设备时，向耳机发送控制命令。使用Promise异步回调。 768 769**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请）。 770 771**系统能力**：SystemCapability.Communication.Bluetooth.Core 772 773**参数：** 774 775| 参数名 | 类型 | 必填 | 说明 | 776| ------ | ------- | ---- | -------------------------------- | 777| controlDeviceActionParams<sup>15+</sup> | [ControlDeviceActionParams](#controldeviceactionparams15) | 是 | 控制蓝牙外设的相关信息。 | 778 779**返回值：** 780 781| 类型 | 说明 | 782| ------------------- | ------------- | 783| Promise<void> | 返回promise对象。 | 784 785**错误码**： 786 787以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 788 789| 错误码ID | 错误信息 | 790| -------- | ---------------------------- | 791|201 | Permission denied. | 792|202 | Non-system applications are not allowed to use system APIs. | 793|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 794|801 | Capability not supported. | 795|2900001 | Service stopped. | 796|2900003 | Bluetooth disabled. | 797|2900099 | Operation failed. | 798 799**示例：** 800 801```js 802import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 803try { 804 let controlDeviceActionParams: connection.ControlDeviceActionParams = { 805 deviceId: '40:DC:A5:E5:75:C3', 806 type: connection.ControlType.PLAY, 807 typeValue: connection.ControlTypeValue.ENABLE, 808 controlObject: connection.ControlObject.LEFT_EAR 809 }; 810 connection.controlDeviceAction(controlDeviceActionParams).then(() => { 811 console.info('controlDeviceAction success'); 812 }, (err: BusinessError) => { 813 console.error('controlDeviceAction: errCode' + err.code + ', errMessage: ' + err.message); 814 }); 815} catch (err) { 816 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 817} 818``` 819 820 821## connection.updateCloudBluetoothDevice<sup>15+</sup> 822 823updateCloudBluetoothDevice(trustedPairedDevices: TrustedPairedDevices): Promise<void> 824 825更新云设备到蓝牙设置。使用Promise异步回调。 826 827**系统接口**：此接口为系统接口。 828 829**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 830 831**系统能力**：SystemCapability.Communication.Bluetooth.Core 832 833**参数：** 834 835| 参数名 | 类型 | 必填 | 说明 | 836| ------ | ------- | ---- | -------------------------------- | 837| trustedPairedDevices | [TrustedPairedDevices](#trustedpaireddevices15) | 是 | 表示云设备列表。 | 838 839**返回值：** 840 841| 类型 | 说明 | 842| ------------------- | ------------- | 843| Promise<void> | 以Promise形式返回设置云设备的结果。设置失败时返回错误码信息。 | 844 845**错误码**： 846 847以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 848 849| 错误码ID | 错误信息 | 850| -------- | ---------------------------- | 851|201 | Permission denied. | 852|202 | Non-system applications are not allowed to use system APIs. | 853|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 854|801 | Capability not supported. | 855|2900001 | Service stopped. | 856|2900003 | Bluetooth disabled. | 857|2900099 | Operation failed. | 858 859**示例：** 860 861```js 862import { connection } from '@kit.ConnectivityKit'; 863// promise 864/** 865 * 更新云设备到蓝牙设置项。 866 */ 867public updateCloudBluetoothDevice() { 868 const trustPairDeviceArr: connection.TrustedPairedDevice[] = []; 869 let descBuffer = new ArrayBuffer(1); 870 trustPairDeviceArr.push({ 871 sn: '', 872 deviceType: '', 873 modelId: '', 874 manufactory: '', 875 productId: '', 876 hiLinkVersion: '', 877 macAddress: '11:22:33:44:55:66', 878 serviceType: '', 879 serviceId: '', 880 deviceName: '', 881 uuids: '', 882 bluetoothClass: 0, 883 token: descBuffer, 884 deviceNameTime: 0, 885 secureAdvertisingInfo: descBuffer, 886 pairState: 0 887 }); 888 const trustPairDevices: connection.TrustedPairedDevices = { trustedPairedDevices: trustPairDeviceArr }; 889 try { 890 connection.updateCloudBluetoothDevice(trustPairDevices) 891 .then(() => { 892 console.info('updateCloudBluetoothDevice success!'); 893 }) 894 .catch((err: BusinessError) => { 895 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 896 }); 897 } catch (err) { 898 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 899 } 900} 901``` 902 903 904## PinRequiredParam 905 906描述配对请求参数。 907 908**系统能力**：SystemCapability.Communication.Bluetooth.Core 909 910| 名称 | 类型 | 可读 | 可写 | 说明 | 911| -------- | ------ | ---- | ---- | ----------- | 912| pinType | [PinType](#pintype) | 是 | 否 | 表示要配对的设备类型。<br/>此接口为系统接口。 | 913 914## ControlDeviceActionParams<sup>15+</sup> 915 916控制命令的配置参数。 917 918**系统能力**：SystemCapability.Communication.Bluetooth.Core 919 920| 名称 | 类型 | 可读 | 可写 | 说明 | 921| -------- | ------ | ---- | ---- | ----------- | 922| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 923| type | [ControlType](#controltype15) | 是 | 否 | 表示控制类型。 | 924| typeValue | [ControlTypeValue](#controltypevalue15) | 是 | 否 | 表示控制动作。 | 925| controlObject | [ControlObject](#controlobject15) | 是 | 否 | 表示控制对象。| 926 927## PinType 928 929枚举，蓝牙配对类型。 930 931**系统接口：** 此接口为系统接口。 932 933**系统能力**：SystemCapability.Communication.Bluetooth.Core 934 935| 名称 | 值 | 说明 | 936| -------------------------------- | ------ | --------------- | 937| PIN_TYPE_ENTER_PIN_CODE | 0 | 用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 938| PIN_TYPE_ENTER_PASSKEY | 1 | 用户需要输入对端设备上显示的PASSKEY。<br/>此接口为系统接口。 | 939| PIN_TYPE_CONFIRM_PASSKEY | 2 | 用户需要确认本地设备上显示的PASSKEY。<br/>此接口为系统接口。 | 940| PIN_TYPE_NO_PASSKEY_CONSENT | 3 | 无PASSKEY，用户需要接受或拒绝配对请求。<br/>此接口为系统接口。 | 941| PIN_TYPE_NOTIFY_PASSKEY | 4 | 本地设备显示PASSKEY，用户需要在对端设备上输入该PASSKEY。<br/>此接口为系统接口。 | 942| PIN_TYPE_DISPLAY_PIN_CODE | 5 | bluetooth 2.0设备，用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 943| PIN_TYPE_OOB_CONSENT | 6 | 用户需要接受或拒绝OOB配对请求。<br/>此接口为系统接口。 | 944| PIN_TYPE_PIN_16_DIGITS | 7 | 用户需要输入对端设备上显示的16位PIN码。<br/>此接口为系统接口。 | 945 946 947## DiscoveryResult<sup>12+</sup> 948 949描述扫描设备状态参数。 950 951**系统接口：** 此接口为系统接口。 952 953**系统能力**：SystemCapability.Communication.Bluetooth.Core。 954 955| 名称 | 类型 | 可读 | 可写 | 说明 | 956| -------- | ------ | ---- | ---- | ----------- | 957| deviceId<sup>12+</sup> | string | 是 | 否 | 表示扫描到的设备ID。<br/>此接口为系统接口。 | 958| rssi<sup>12+</sup> | number | 是 | 否 | 表示扫描到的设备的信号强度。<br/>此接口为系统接口。 | 959| deviceName<sup>12+</sup> | string | 是 | 否 | 表示扫描到的设备的设备名称。<br/>此接口为系统接口。 | 960| deviceClass<sup>12+</sup> | DeviceClass | 是 | 否 | 表示扫描到的设备的设备类别。<br/>此接口为系统接口。 | 961 962 963## DeviceType<sup>12+</sup> 964 965枚举，蓝牙远程设备的自定义类型。 966 967**系统接口：** 此接口为系统接口。 968 969**系统能力**：SystemCapability.Communication.Bluetooth.Core 970 971| 名称 | 值 | 说明 | 972| -------------------------------- | ------ | --------------- | 973| DEVICE_TYPE_DEFAULT<sup>12+</sup> | 0 | 默认设备类型，与原类型一致。<br/>此接口为系统接口。 | 974| DEVICE_TYPE_CAR<sup>12+</sup> | 1 | 汽车。<br/>此接口为系统接口。 | 975| DEVICE_TYPE_HEADSET<sup>12+</sup> | 2 | 耳机。<br/>此接口为系统接口。 | 976| DEVICE_TYPE_HEARING<sup>12+</sup> | 3 | 助听器<br/>此接口为系统接口。 | 977| DEVICE_TYPE_GLASSES<sup>12+</sup> | 4 | 眼镜。<br/>此接口为系统接口。 | 978| DEVICE_TYPE_WATCH<sup>12+</sup> | 5 | 手表。<br/>此接口为系统接口。 | 979| DEVICE_TYPE_SPEAKER<sup>12+</sup> | 6 | 音响。<br/>此接口为系统接口。 | 980| DEVICE_TYPE_OTHERS<sup>12+</sup> | 7 | 其他设备。<br/>此接口为系统接口。 | 981 982 983## BatteryInfo<sup>12+</sup> 984 985描述电量信息的内容。 986 987**系统能力**：SystemCapability.Communication.Bluetooth.Core 988 989| 名称 | 类型 | 可读 | 可写 | 说明 | 990| -------- | ------ | ---- | ---- | ----------- | 991| deviceId | string | 是 | 否 | 表示远端设备的MAC地址。<br/>此接口为系统接口。 | 992 993 994## ControlType<sup>15+</sup> 995 996枚举，控制类型。 997 998**系统能力**：SystemCapability.Communication.Bluetooth.Core 999 1000| 名称 | 值 | 说明 | 1001| -------------------------------- | ------ | --------------- | 1002| PLAY | 0 | 表示控制类型为播放。 | 1003| VIBRATE | 1 | 表示控制类型为振动。 | 1004| FLASH | 2 | 表示控制类型为闪光。 | 1005| LOCK | 3 | 表示控制类型为锁定。 | 1006 1007 1008## ControlTypeValue<sup>15+</sup> 1009 1010枚举，控制动作。 1011 1012**系统能力**：SystemCapability.Communication.Bluetooth.Core 1013 1014| 名称 | 值 | 说明 | 1015| ------- | ---- | ---------- | 1016| DISABLE | 0 | 表示禁用。 | 1017| ENABLE | 1 | 表示使能。 | 1018| QUERY | 2 | 表示查询。 | 1019 1020 1021## ControlObject<sup>15+</sup> 1022 1023枚举，控制对象。 1024 1025**系统能力**：SystemCapability.Communication.Bluetooth.Core 1026 1027| 名称 | 值 | 说明 | 1028| -------------- | ---- | -------------------- | 1029| LEFT_EAR | 0 | 表示控制对象是左耳。 | 1030| RIGHT_EAR | 1 | 表示控制对象是右耳。 | 1031| LEFT_RIGHT_EAR | 2 | 表示控制对象是双耳。 | 1032 1033 1034## TrustedPairedDevices<sup>15+</sup> 1035 1036云设备列表。 1037 1038**系统能力**：SystemCapability.Communication.Bluetooth.Core 1039 1040| 名称 | 类型 | 可读 | 可选 | 说明 | 1041| -------- | ------ | ---- | ---- | ----------- | 1042| trustedPairedDevices | Array<[TrustedPairedDevice](#trustedpaireddevice15)> | 是 | 否 | 表示云设备列表。 | 1043 1044## TrustedPairedDevice<sup>15+</sup> 1045 1046云设备信息。 1047 1048**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1049 1050| 名称 | 类型 | 可读 | 可选 | 说明 | 1051| -------- | ------ | ---- | ---- | ----------- | 1052| sn | string | 是 | 否 | 表示设备的序列号。 | 1053| deviceType | string | 是 | 否 | 表示设备类型。 | 1054| modelId | string | 是 | 否 | 表示左侧耳机的充电状态。 | 1055| manufactory | string | 是 | 否 | 表示制造商信息。 | 1056| productId | string | 是 | 否 | 表示设备产品信息。 | 1057| hiLinkVersion | string | 是 | 否 | 表示hilink版本信息。 | 1058| macAddress | string | 是 | 否 | 表示设备MAC地址。 | 1059| serviceType | string | 是 | 否 | 表示设备服务类型。 | 1060| serviceId | string | 是 | 否 | 表示设备id。 | 1061| deviceName | string | 是 | 否 | 表示设备名字。 | 1062| uuids | string | 是 | 否 | 表示设备的UUID。 | 1063| bluetoothClass | number | 是 | 否 | 表示远端设备类型。 | 1064| token | ArrayBuffer | 是 | 否 | 表示设备的token信息。 | 1065| deviceNameTime | number | 是 | 否 | 表示设备名字的修改时间。 | 1066| secureAdvertisingInfo | ArrayBuffer | 是 | 否 | 表示设备广播信息。 | 1067| pairState | number | 是 | 否 | 表示设备配对状态。 | 1068