1# @ohos.bluetooth.connection (蓝牙connection模块) 2 3<!--Kit: Connectivity Kit--> 4<!--Subsystem: Communication--> 5<!--Owner: @enjoy_sunshine--> 6<!--Designer: @chengguohong; @tangjia15--> 7<!--Tester: @wangfeng517--> 8<!--Adviser: @zhang_yixin13--> 9 10connection模块提供了蓝牙设备的配对、连接及状态查询等能力。 11 12> **说明：** 13> 14> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16 17 18## 导入模块 19 20```js 21import { connection } from '@kit.ConnectivityKit'; 22``` 23 24 25## ProfileConnectionState 26 27type ProfileConnectionState = constant.ProfileConnectionState 28 29蓝牙设备的Profile协议连接状态。Profile协议包括A2DP（Advanced Audio Distribution Profile）、HFP（Hands-Free Profile）和HID（Human Interface Device）等。 30 31**系统能力**：SystemCapability.Communication.Bluetooth.Core 32 33| 类型 | 说明 | 34| ------------------- | ------------------- | 35| [constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 蓝牙设备的Profile协议连接状态。 | 36 37 38## ProfileId 39 40type ProfileId = constant.ProfileId 41 42枚举，蓝牙Profile协议。 43 44**系统能力**：SystemCapability.Communication.Bluetooth.Core 45 46| 类型 | 说明 | 47| ------------------- | ------------------- | 48| [constant.ProfileId](js-apis-bluetooth-constant.md#profileid) | 蓝牙Profile协议的枚举。 | 49 50 51## ProfileUuids<sup>12+</sup> 52 53type ProfileUuids = constant.ProfileUuids 54 55蓝牙Profile协议的UUID。 56 57**系统能力**：SystemCapability.Communication.Bluetooth.Core 58 59| 类型 | 说明 | 60| ------------------- | ------------------- | 61| [constant.ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12) | 蓝牙Profile协议的UUID。 | 62 63 64## MajorClass 65 66type MajorClass = constant.MajorClass 67 68蓝牙设备的主要类型。蓝牙标准协议字段。 69 70**系统能力**：SystemCapability.Communication.Bluetooth.Core 71 72| 类型 | 说明 | 73| ------------------- | ------------------- | 74| [constant.MajorClass](js-apis-bluetooth-constant.md#majorclass) | 蓝牙设备的主要类型。 | 75 76 77## MajorMinorClass 78 79type MajorMinorClass = constant.MajorMinorClass 80 81蓝牙设备的子类型，在[MajorClass](js-apis-bluetooth-constant.md#majorclass)基础上进一步细分的类型。蓝牙标准协议字段。 82 83**系统能力**：SystemCapability.Communication.Bluetooth.Core 84 85| 类型 | 说明 | 86| ------------------- | ------------------- | 87| [constant.MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 蓝牙设备的子类型。 | 88 89 90## connection.pairDevice 91 92pairDevice(deviceId: string, callback: AsyncCallback<void>): void 93 94主动发起与对端蓝牙设备的配对流程。使用Callback异步回调。 95- 蓝牙配对状态通过[on('bondStateChange')](#connectiononbondstatechange)的回调结果获取。 96 97**需要权限**：ohos.permission.ACCESS_BLUETOOTH 98 99**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 100 101**系统能力**：SystemCapability.Communication.Bluetooth.Core 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| -------- | ------ | ---- | ----------------------------------- | 107| deviceId | string | 是 | 需要配对的对端蓝牙设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 108| callback | AsyncCallback<void> | 是 | 回调函数。当配对成功，err为undefined，否则为错误对象。 | 109 110**错误码**： 111 112以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 113 114| 错误码ID | 错误信息 | 115| -------- | ---------------------------- | 116|201 | Permission denied. | 117|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 118|801 | Capability not supported. | 119|2900001 | Service stopped. | 120|2900003 | Bluetooth disabled. | 121|2900099 | Operation failed. | 122 123**示例：** 124 125```js 126import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 127// callback 128try { 129 connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => { 130 console.info('pairDevice, device name err:' + JSON.stringify(err)); 131 }); 132} catch (err) { 133 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 134} 135 136``` 137 138 139## connection.pairDevice 140 141pairDevice(deviceId: string): Promise<void> 142 143主动发起与对端蓝牙设备的配对流程。使用Promise异步回调。 144- 蓝牙配对状态通过[on('bondStateChange')](#connectiononbondstatechange)的回调结果获取。 145 146**需要权限**：ohos.permission.ACCESS_BLUETOOTH 147 148**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力**：SystemCapability.Communication.Bluetooth.Core 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| -------- | ------ | ---- | ----------------------------------- | 156| deviceId | string | 是 | 需要配对的对端蓝牙设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 157 158**返回值：** 159 160| 类型 | 说明 | 161| ------------------- | ------------- | 162| Promise<void> | Promise对象。无返回结果的Promise对象。 | 163 164**错误码**： 165 166以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 167 168| 错误码ID | 错误信息 | 169| -------- | ---------------------------- | 170|201 | Permission denied. | 171|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 172|801 | Capability not supported. | 173|2900001 | Service stopped. | 174|2900003 | Bluetooth disabled. | 175|2900099 | Operation failed. | 176 177**示例：** 178 179```js 180import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 181// promise 182try { 183 connection.pairDevice('11:22:33:44:55:66').then(() => { 184 console.info('pairDevice'); 185 }, (error: BusinessError) => { 186 console.error('pairDevice: errCode:' + error.code + ',errMessage' + error.message); 187 }) 188 189} catch (err) { 190 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 191} 192``` 193 194 195## connection.getRemoteDeviceName 196 197getRemoteDeviceName(deviceId: string): string 198 199获取对端蓝牙设备的名称。 200 201**需要权限**：ohos.permission.ACCESS_BLUETOOTH 202 203**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 204 205**系统能力**：SystemCapability.Communication.Bluetooth.Core 206 207**参数：** 208 209| 参数名 | 类型 | 必填 | 说明 | 210| -------- | ------ | ---- | --------------------------------- | 211| deviceId | string | 是 | 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 212 213**返回值：** 214 215| 类型 | 说明 | 216| ------ | ------------- | 217| string | 以字符串格式返回设备名称。 | 218 219**错误码**： 220 221以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 222 223| 错误码ID | 错误信息 | 224| -------- | ---------------------------- | 225|201 | Permission denied. | 226|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 227|801 | Capability not supported. | 228|2900001 | Service stopped. | 229|2900003 | Bluetooth disabled. | 230|2900099 | Operation failed. | 231 232**示例：** 233 234```js 235import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 236try { 237 let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX'); 238} catch (err) { 239 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 240} 241``` 242 243 244## connection.getRemoteDeviceName<sup>16+</sup> 245 246getRemoteDeviceName(deviceId: string, alias?: boolean): string 247 248获取对端蓝牙设备的名称，其中alias为可选参数。 249 250**需要权限**：ohos.permission.ACCESS_BLUETOOTH 251 252**原子化服务API**：从API version 16开始，该接口支持在原子化服务中使用。 253 254**系统能力**：SystemCapability.Communication.Bluetooth.Core 255 256**参数：** 257 258| 参数名 | 类型 | 必填 | 说明 | 259| -------- | ------ | ---- | --------------------------------- | 260| deviceId | string | 是 | 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 261| alias | boolean | 否 | 表示是否获取对端蓝牙设备别名。<br>- 如果携带alias，则根据alias判断是否获取对端蓝牙设备别名：true表示获取对端蓝牙设备别名，false表示获取对端蓝牙设备原始名称。<br>- 如果未携带alias，则默认值为true，返回对端蓝牙设备别名。 | 262 263**返回值：** 264 265| 类型 | 说明 | 266| ------ | ------------- | 267| string | 以字符串格式返回设备名称。 | 268 269**错误码**： 270 271以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 272 273| 错误码ID | 错误信息 | 274| -------- | ---------------------------- | 275|201 | Permission denied. | 276|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 277|801 | Capability not supported. | 278|2900001 | Service stopped. | 279|2900003 | Bluetooth disabled. | 280|2900099 | Failed to obtain the name or alias of the peer Bluetooth device. | 281 282**示例：** 283 284```js 285import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 286try { 287 let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX', true); 288} catch (err) { 289 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 290} 291``` 292 293 294## connection.getRemoteDeviceClass 295 296getRemoteDeviceClass(deviceId: string): DeviceClass 297 298获取对端蓝牙设备的类别。从API18开始不再校验ohos.permission.ACCESS_BLUETOOTH权限。 299 300**系统能力**：SystemCapability.Communication.Bluetooth.Core 301 302**参数：** 303 304| 参数名 | 类型 | 必填 | 说明 | 305| -------- | ------ | ---- | --------------------------------- | 306| deviceId | string | 是 | 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 307 308**返回值：** 309 310| 类型 | 说明 | 311| --------------------------- | -------- | 312| [DeviceClass](#deviceclass) | 对端设备的类别。 | 313 314**错误码**： 315 316以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 317 318| 错误码ID | 错误信息 | 319| -------- | ---------------------------- | 320|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 321|801 | Capability not supported. | 322|2900001 | Service stopped. | 323|2900003 | Bluetooth disabled. | 324|2900099 | Operation failed. | 325 326**示例：** 327 328```js 329import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 330try { 331 let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX'); 332} catch (err) { 333 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 334} 335``` 336 337## connection.getRemoteDeviceTransport<sup>20+</sup> 338 339getRemoteDeviceTransport(deviceId: string): BluetoothTransport 340 341获取对端蓝牙设备的传输类型。 342 343**系统能力**：SystemCapability.Communication.Bluetooth.Core 344 345**参数：** 346 347| 参数名 | 类型 | 必填 | 说明 | 348| -------- | ------ | ---- | --------------------------------- | 349| deviceId | string | 是 | 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 350 351**返回值：** 352 353| 类型 | 说明 | 354| --------------------------- | -------- | 355| [BluetoothTransport](#bluetoothtransport) | 对端设备的传输类型。 | 356 357**错误码**： 358 359以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 360 361| 错误码ID | 错误信息 | 362| -------- | ---------------------------- | 363|801 | Capability not supported. | 364|2900001 | Service stopped. | 365|2900003 | Bluetooth disabled. | 366|2900099 | Get transport failed. | 367 368**示例：** 369 370```js 371import { BusinessError } from '@kit.BasicServicesKit'; 372try { 373 let transport: connection.BluetoothTransport = connection.getRemoteDeviceTransport('XX:XX:XX:XX:XX:XX'); 374} catch (err) { 375 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 376} 377``` 378 379## connection.getRemoteProfileUuids<sup>12+</sup> 380 381getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void 382 383获取对端蓝牙设备的Profile协议能力，通过UUID区分。使用Callback异步回调。 384- 建议仅对已配对的设备调用该方法。 385 386**需要权限**：ohos.permission.ACCESS_BLUETOOTH 387 388**系统能力**：SystemCapability.Communication.Bluetooth.Core 389 390**参数：** 391 392| 参数名 | 类型 | 必填 | 说明 | 393| -------- | ------ | ---- | ----------------------------------- | 394| deviceId | string | 是 | 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 395| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | 是 | 回调函数。当获取UUID成功，err为undefined，获取到的是Profile协议能力集合；否则为错误对象。 | 396 397**错误码**： 398 399以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 400 401| 错误码ID | 错误信息 | 402| -------- | ---------------------------- | 403|201 | Permission denied. | 404|401 | Invalid parameter. | 405|801 | Capability not supported. | 406|2900001 | Service stopped. | 407|2900003 | Bluetooth disabled. | 408|2900099 | Operation failed. | 409 410**示例：** 411 412```js 413import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 414try { 415 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => { 416 console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); 417 }); 418} catch (err) { 419 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 420} 421 422``` 423 424 425## connection.getRemoteProfileUuids<sup>12+</sup> 426 427getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>> 428 429获取对端蓝牙设备的Profile协议能力，通过UUID区分。使用Promise异步回调。 430- 建议仅对已配对的设备调用该方法。 431 432**需要权限**：ohos.permission.ACCESS_BLUETOOTH 433 434**系统能力**：SystemCapability.Communication.Bluetooth.Core 435 436**参数：** 437 438| 参数名 | 类型 | 必填 | 说明 | 439| -------- | ------ | ---- | ----------------------------------- | 440| deviceId | string | 是 | 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 441 442**返回值：** 443 444| 类型 | 说明 | 445| ------------------- | ------------- | 446| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | Promise对象，返回支持的Profile协议能力集合。 | 447 448**错误码**： 449 450以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 451 452| 错误码ID | 错误信息 | 453| -------- | ---------------------------- | 454|201 | Permission denied. | 455|401 | Invalid parameter. | 456|801 | Capability not supported. | 457|2900001 | Service stopped. | 458|2900003 | Bluetooth disabled. | 459|2900099 | Operation failed. | 460 461**示例：** 462 463```js 464import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 465try { 466 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => { 467 console.info('getRemoteProfileUuids'); 468 }, (err: BusinessError) => { 469 console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 470 }); 471} catch (err) { 472 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 473} 474``` 475 476 477## connection.getLocalName 478 479getLocalName(): string 480 481获取本机蓝牙设备的名称。 482 483**需要权限**：ohos.permission.ACCESS_BLUETOOTH 484 485**系统能力**：SystemCapability.Communication.Bluetooth.Core 486 487**返回值：** 488 489| 类型 | 说明 | 490| ------ | --------- | 491| string | 本机蓝牙设备名称。 | 492 493**错误码**： 494 495以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 496 497| 错误码ID | 错误信息 | 498| -------- | ---------------------------- | 499|201 | Permission denied. | 500|801 | Capability not supported. | 501|2900001 | Service stopped. | 502|2900099 | Operation failed. | 503 504**示例：** 505 506```js 507import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 508try { 509 let localName: string = connection.getLocalName(); 510} catch (err) { 511 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 512} 513``` 514 515 516## connection.getPairedDevices 517 518getPairedDevices(): Array<string> 519 520获取已配对蓝牙设备的地址集合。 521 522**需要权限**：ohos.permission.ACCESS_BLUETOOTH 523 524**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 525 526**系统能力**：SystemCapability.Communication.Bluetooth.Core 527 528**返回值：** 529 530| 类型 | 说明 | 531| ------------------- | ------------- | 532| Array<string> | 已配对蓝牙设备的地址集合。<br>基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。<br>- 已配对的地址不会变更。<br>- 若取消配对该设备或蓝牙关闭后，再次重新获取，该虚拟地址会变更。<br>- 若要持久化保存该地址，可使用[access.addPersistentDeviceId](js-apis-bluetooth-access.md#accessaddpersistentdeviceid16)方法。 | 533 534**错误码**： 535 536以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 537 538| 错误码ID | 错误信息 | 539| -------- | ---------------------------- | 540|201 | Permission denied. | 541|801 | Capability not supported. | 542|2900001 | Service stopped. | 543|2900003 | Bluetooth disabled. | 544|2900099 | Operation failed. | 545 546**示例：** 547 548```js 549import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 550try { 551 let devices: Array<string> = connection.getPairedDevices(); 552} catch (err) { 553 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 554} 555``` 556 557 558## connection.getPairState<sup>11+</sup> 559 560getPairState(deviceId: string): BondState 561 562获取对端蓝牙设备的配对状态信息。 563 564**需要权限**：ohos.permission.ACCESS_BLUETOOTH 565 566**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 567 568**系统能力**：SystemCapability.Communication.Bluetooth.Core 569 570**参数：** 571 572| 参数名 | 类型 | 必填 | 说明 | 573| -------- | ------ | ---- | --------------------------------- | 574| deviceId | string | 是 | 表示对端设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 575 576**返回值：** 577 578| 类型 | 说明 | 579| --------------------------- | -------- | 580| [BondState](#bondstate) | 表示设备的蓝牙配对状态。 | 581 582**错误码**： 583 584以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 585 586| 错误码ID | 错误信息 | 587| -------- | ---------------------------- | 588|201 | Permission denied. | 589|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 590|801 | Capability not supported. | 591|2900001 | Service stopped. | 592|2900003 | Bluetooth disabled. | 593|2900099 | Operation failed. | 594 595**示例：** 596 597```js 598import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 599try { 600 let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX"); 601 console.info('getPairState: ' + res); 602} catch (err) { 603 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 604} 605``` 606 607 608## connection.getProfileConnectionState 609 610getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState 611 612获取蓝牙Profile协议的连接状态，其中ProfileId为可选参数。 613 614**需要权限**：ohos.permission.ACCESS_BLUETOOTH 615 616**系统能力**：SystemCapability.Communication.Bluetooth.Core 617 618**参数：** 619 620| 参数名 | 类型 | 必填 | 说明 | 621| --------- | --------- | ---- | ------------------------------------- | 622| profileId | [ProfileId](js-apis-bluetooth-constant.md#profileid) | 否 | 表示Profile协议的枚举值。如果携带ProfileId，则返回指定Profile协议的连接状态。如果未携带ProfileId，则检查所有支持的Profile连接状态，按如下优先级顺序检查并返回：<br>- 存在已连接的Profile协议，则返回[STATE_CONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)。<br>- 存在正在连接的Profile协议，则返回[STATE_CONNECTING](js-apis-bluetooth-constant.md#profileconnectionstate)。<br>- 存在正在断连的Profile协议，则返回[STATE_DISCONNECTING](js-apis-bluetooth-constant.md#profileconnectionstate)。<br>- 以上条件均不满足，则返回[STATE_DISCONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)。 | 623 624**返回值：** 625 626| 类型 | 说明 | 627| ------------------------------------------------- | ------------------- | 628| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | Profile协议的连接状态。 | 629 630**错误码**： 631 632以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 633 634| 错误码ID | 错误信息 | 635| -------- | ---------------------------- | 636|201 | Permission denied. | 637|401 | Invalid parameter. Possible causes: 1. Incorrect parameter types. | 638|801 | Capability not supported. | 639|2900001 | Service stopped. | 640|2900003 | Bluetooth disabled. | 641|2900004 | Profile not supported. | 642|2900099 | Operation failed. | 643 644**示例：** 645 646```js 647import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 648import { constant } from '@kit.ConnectivityKit'; 649try { 650 let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE); 651} catch (err) { 652 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 653} 654``` 655 656 657## connection.setDevicePairingConfirmation 658 659setDevicePairingConfirmation(deviceId: string, accept: boolean): void 660 661收到对端蓝牙设备的配对请求事件后，确认请求结果。 662- 对端蓝牙的配对请求通过[on('pinRequired')](#connectiononpinrequired)的回调结果获取。 663 664**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请） 665 666**系统能力**：SystemCapability.Communication.Bluetooth.Core 667 668**参数：** 669 670| 参数名 | 类型 | 必填 | 说明 | 671| ------ | ------- | ---- | -------------------------------- | 672| deviceId | string | 是 | 表示对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 673| accept | boolean | 是 | 是否接受对端设备的配对请求。true表示接受，false表示不接受。 | 674 675**错误码**： 676 677以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 678 679| 错误码ID | 错误信息 | 680| -------- | ---------------------------- | 681|201 | Permission denied. | 682|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 683|801 | Capability not supported. | 684|2900001 | Service stopped. | 685|2900003 | Bluetooth disabled. | 686|2900099 | Operation failed. | 687 688**示例：** 689 690```js 691import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 692// 订阅“pinRequired”配对请求事件，收到对端配对请求后设置配对确认。 693function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data为配对请求的入参，配对请求参数。 694 console.info('pin required = '+ JSON.stringify(data)); 695 connection.setDevicePairingConfirmation(data.deviceId, true); 696} 697try { 698 connection.on('pinRequired', onReceivePinRequiredEvent); 699} catch (err) { 700 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 701} 702``` 703 704 705## connection.setDevicePinCode 706 707setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void 708 709蓝牙配对时，弹框提示用户输入个人身份识别码（Personal identification number，PIN），调用此接口设置PIN码，完成蓝牙配对。使用Callback异步回调。 710 711**需要权限**：ohos.permission.ACCESS_BLUETOOTH 712 713**系统能力**：SystemCapability.Communication.Bluetooth.Core 714 715**参数：** 716 717| 参数名 | 类型 | 必填 | 说明 | 718| ------ | ------- | ---- | -------------------------------- | 719| deviceId | string | 是 | 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 720| code | string | 是 | 用户输入的PIN码，该字符串的字符个数范围为(0, 16]，例如："12345"。 | 721| callback | AsyncCallback<void> | 是 | 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。 | 722 723**错误码**： 724 725以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 726 727| 错误码ID | 错误信息 | 728| -------- | ---------------------------- | 729|201 | Permission denied. | 730|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 731|801 | Capability not supported. | 732|2900001 | Service stopped. | 733|2900003 | Bluetooth disabled. | 734|2900099 | Operation failed. | 735 736**示例：** 737 738```js 739import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 740// callback 741try { 742 connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => { 743 console.info('setDevicePinCode,device name err: ' + JSON.stringify(err)); 744 }); 745} catch (err) { 746 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 747} 748``` 749 750 751## connection.setDevicePinCode 752 753setDevicePinCode(deviceId: string, code: string): Promise<void> 754 755蓝牙配对时，弹框提示用户输入PIN码，调用此接口请求用户输入PIN码，完成蓝牙配对。使用Promise异步回调。 756 757**需要权限**：ohos.permission.ACCESS_BLUETOOTH 758 759**系统能力**：SystemCapability.Communication.Bluetooth.Core 760 761**参数：** 762 763| 参数名 | 类型 | 必填 | 说明 | 764| ------ | ------- | ---- | -------------------------------- | 765| deviceId | string | 是 | 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 766| code | string | 是 | 用户输入的PIN码，该字符串的字符个数范围为(0, 16]，例如："12345"。 | 767 768**返回值：** 769 770| 类型 | 说明 | 771| ------------------- | ------------- | 772| Promise<void> | Promise对象。无返回结果的Promise对象。 | 773 774**错误码**： 775 776以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 777 778| 错误码ID | 错误信息 | 779| -------- | ---------------------------- | 780|201 | Permission denied. | 781|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 782|801 | Capability not supported. | 783|2900001 | Service stopped. | 784|2900003 | Bluetooth disabled. | 785|2900099 | Operation failed. | 786 787**示例：** 788 789```js 790import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 791// promise 792try { 793 connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { 794 console.info('setDevicePinCode'); 795 }, (error: BusinessError) => { 796 console.error('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); 797 }) 798 799} catch (err) { 800 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 801} 802``` 803 804 805## connection.setLocalName<sup>(deprecated)</sup> 806 807setLocalName(name: string): void 808 809设置本机蓝牙设备名称，不能设置为空字符串。如果设为空字符串会失败。 810 811> **说明：**<br/> 812> 从API version 10开始支持，从API version 12开始废弃，不再提供替代接口。 813 814**需要权限**：ohos.permission.ACCESS_BLUETOOTH 815 816**系统能力**：SystemCapability.Communication.Bluetooth.Core 817 818**参数：** 819 820| 参数名 | 类型 | 必填 | 说明 | 821| ---- | ------ | ---- | --------------------- | 822| name | string | 是 | 需要设置的蓝牙名称，名称长度范围：(0, 248]，单位：Byte。 | 823 824**错误码**： 825 826以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 827 828| 错误码ID | 错误信息 | 829| -------- | ---------------------------- | 830|201 | Permission denied. | 831|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 832|801 | Capability not supported. | 833|2900001 | Service stopped. | 834|2900003 | Bluetooth disabled. | 835|2900099 | Operation failed. | 836 837**示例：** 838 839```js 840import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 841try { 842 connection.setLocalName('device_name'); 843} catch (err) { 844 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 845} 846``` 847 848 849## connection.setBluetoothScanMode 850 851setBluetoothScanMode(mode: ScanMode, duration: number): void 852 853设置蓝牙扫描模式，决定本机设备是否可被连接，或者可被发现。 854 855**需要权限**：ohos.permission.ACCESS_BLUETOOTH 856 857**系统能力**：SystemCapability.Communication.Bluetooth.Core 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| -------- | --------------------- | ---- | ---------------------------- | 863| mode | [ScanMode](#scanmode) | 是 | 蓝牙扫描模式。当扫描模式为SCAN_MODE_GENERAL_DISCOVERABLE时，超出duration持续时间(不为0)，扫描模式会重新设置为SCAN_MODE_CONNECTABLE。 | 864| duration | number | 是 | 设备可被发现的持续时间，单位：ms。设置为0则表示持续可发现。 | 865 866**错误码**： 867 868以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 869 870| 错误码ID | 错误信息 | 871| -------- | ---------------------------- | 872|201 | Permission denied. | 873|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 874|801 | Capability not supported. | 875|2900001 | Service stopped. | 876|2900003 | Bluetooth disabled. | 877|2900099 | Operation failed. | 878 879**示例：** 880 881```js 882import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 883try { 884 // 设置为可连接可发现才可被对端设备扫描到，可以连接。 885 connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); 886} catch (err) { 887 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 888} 889``` 890 891 892## connection.getBluetoothScanMode 893 894getBluetoothScanMode(): ScanMode 895 896获取蓝牙扫描模式。 897 898**需要权限**：ohos.permission.ACCESS_BLUETOOTH 899 900**系统能力**：SystemCapability.Communication.Bluetooth.Core 901 902**返回值：** 903 904| 类型 | 说明 | 905| --------------------- | ------- | 906| [ScanMode](#scanmode) | 蓝牙扫描模式。 | 907 908**错误码**： 909 910以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 911 912| 错误码ID | 错误信息 | 913| -------- | ---------------------------- | 914|201 | Permission denied. | 915|801 | Capability not supported. | 916|2900001 | Service stopped. | 917|2900003 | Bluetooth disabled. | 918|2900099 | Operation failed. | 919 920**示例：** 921 922```js 923import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 924try { 925 let scanMode: connection.ScanMode = connection.getBluetoothScanMode(); 926} catch (err) { 927 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 928} 929``` 930 931 932## connection.startBluetoothDiscovery 933 934startBluetoothDiscovery(): void 935 936开启蓝牙扫描，发现对端蓝牙设备。<br> 937- 该接口支持发现传统蓝牙设备和低功耗蓝牙设备，整个蓝牙扫描过程大约持续12s。<br> 938- 扫描结果可通过API version 10开始支持的[connection.on('bluetoothDeviceFind')](#connectiononbluetoothdevicefind)或者API version 18开始支持的[connection.on('discoveryResult')](#connectionondiscoveryresult18)的回调函数获取到。推荐使用[connection.on('discoveryResult')](#connectionondiscoveryresult18)，该方式可以获取到更多设备信息。<br> 939- 若在扫描过程中，请勿重复调用该方法（可使用[connection.isBluetoothDiscovering](#connectionisbluetoothdiscovering11)判断蓝牙当前是否处于扫描过程中）。<br> 940- 调用[connection.stopBluetoothDiscovery](#connectionstopbluetoothdiscovery)可以停止该方法开启的扫描流程，扫描停止后，才能开启下一次蓝牙扫描。<br> 941 942**需要权限**：ohos.permission.ACCESS_BLUETOOTH 943 944**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 945 946**系统能力**：SystemCapability.Communication.Bluetooth.Core 947 948**错误码**： 949 950以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 951 952| 错误码ID | 错误信息 | 953| -------- | ---------------------------- | 954|201 | Permission denied. | 955|801 | Capability not supported. | 956|2900001 | Service stopped. | 957|2900003 | Bluetooth disabled. | 958|2900099 | Operation failed. | 959 960**示例：** 961 962```js 963import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 964function onReceiveEvent(data: Array<string>) { 965 console.info('data length' + data.length); 966} 967try { 968 connection.on('bluetoothDeviceFind', onReceiveEvent); 969 connection.startBluetoothDiscovery(); 970} catch (err) { 971 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 972} 973``` 974 975 976## connection.stopBluetoothDiscovery 977 978stopBluetoothDiscovery(): void 979 980关闭蓝牙扫描。<br> 981- 关闭的扫描是由[connection.startBluetoothDiscovery](#connectionstartbluetoothdiscovery)触发的。<br> 982- 当应用不再需要扫描设备时，需主动调用该方法关闭扫描。<br> 983- 若不在扫描过程中，请勿重复调用该方法（可使用[connection.isBluetoothDiscovering](#connectionisbluetoothdiscovering11)判断蓝牙当前是否处于扫描过程中）。<br> 984 985**需要权限**：ohos.permission.ACCESS_BLUETOOTH 986 987**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 988 989**系统能力**：SystemCapability.Communication.Bluetooth.Core 990 991**错误码**： 992 993以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 994 995| 错误码ID | 错误信息 | 996| -------- | ---------------------------- | 997|201 | Permission denied. | 998|801 | Capability not supported. | 999|2900001 | Service stopped. | 1000|2900003 | Bluetooth disabled. | 1001|2900099 | Operation failed. | 1002 1003**示例：** 1004 1005```js 1006import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1007try { 1008 connection.stopBluetoothDiscovery(); 1009} catch (err) { 1010 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1011} 1012``` 1013 1014 1015## connection.isBluetoothDiscovering<sup>11+</sup> 1016 1017isBluetoothDiscovering(): boolean 1018 1019判断本机蓝牙设备是否处于设备扫描状态。 1020 1021**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1022 1023**系统能力**：SystemCapability.Communication.Bluetooth.Core 1024 1025**返回值：** 1026 1027| 类型 | 说明 | 1028| ------------------- | ------------- | 1029| boolean | 是否开启蓝牙发现。true表示正在发起设备扫描，false表示未发起设备扫描。 | 1030 1031**错误码**： 1032 1033以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1034 1035| 错误码ID | 错误信息 | 1036| -------- | ---------------------------- | 1037|201 | Permission denied. | 1038|801 | Capability not supported. | 1039|2900001 | Service stopped. | 1040|2900003 | Bluetooth disabled. | 1041|2900099 | Operation failed. | 1042 1043**示例：** 1044 1045```js 1046import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1047try { 1048 let res: boolean = connection.isBluetoothDiscovering(); 1049 console.info('isBluetoothDiscovering: ' + res); 1050} catch (err) { 1051 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1052} 1053``` 1054 1055## connection.setRemoteDeviceName<sup>12+</sup> 1056 1057setRemoteDeviceName(deviceId: string, name: string): Promise<void> 1058 1059设置对端蓝牙设备的名称，不能设置为空字符串。如果设为空字符串会失败。使用Promise异步回调。 1060- 建议仅对已配对的设备调用该方法。 1061 1062**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1063 1064**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1065 1066**系统能力**：SystemCapability.Communication.Bluetooth.Core 1067 1068**参数：** 1069 1070| 参数名 | 类型 | 必填 | 说明 | 1071| -------- | ----------------------------------- | ---- | -------------------------------------- | 1072| deviceId | string | 是 | 表示对端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 1073| name | string | 是 | 修改对端设备名称，名称长度范围：(0, 64]，单位：Byte。 | 1074 1075**返回值：** 1076 1077| 类型 | 说明 | 1078| ------------------- | ------------- | 1079| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1080 1081**错误码**： 1082 1083以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1084 1085| 错误码ID | 错误信息 | 1086| -------- | ---------------------------- | 1087|201 | Permission denied. | 1088|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1089|2900001 | Service stopped. | 1090|2900003 | Bluetooth disabled. | 1091 1092**示例：** 1093 1094```js 1095import { BusinessError } from '@kit.BasicServicesKit'; 1096// promise 1097try { 1098 connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => { 1099 console.info('setRemoteDeviceName success'); 1100 }, (error: BusinessError) => { 1101 console.error('setRemoteDeviceName: errCode: ' + error.code + ',errMessage' + error.message); 1102 }) 1103} catch (err) { 1104 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1105} 1106``` 1107 1108 1109## connection.getRemoteDeviceBatteryInfo<sup>12+</sup> 1110 1111getRemoteDeviceBatteryInfo(deviceId: string): Promise<BatteryInfo> 1112 1113获取对端蓝牙设备的电量信息。使用Promise异步回调。 1114- 对端蓝牙设备的电量信息变更通过[on('batteryChange')](#connectiononbatterychange12)的回调结果获取。 1115 1116**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1117 1118**系统能力**：SystemCapability.Communication.Bluetooth.Core 1119 1120**参数：** 1121 1122| 参数名 | 类型 | 必填 | 说明 | 1123| ------ | ------- | ---- | -------------------------------- | 1124| deviceId | string | 是 | 表示对端蓝牙设备的MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 1125 1126**返回值：** 1127 1128| 类型 | 说明 | 1129| ------------------- | ------------- | 1130| Promise<[BatteryInfo](#batteryinfo12)> | Promise对象，返回电量信息对象。 | 1131 1132**错误码**： 1133 1134以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1135 1136| 错误码ID | 错误信息 | 1137| -------- | ---------------------------- | 1138|201 | Permission denied. | 1139|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1140|2900001 | Service stopped. | 1141|2900003 | Bluetooth disabled. | 1142 1143**示例：** 1144 1145```js 1146import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1147// promise 1148try { 1149 connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => { 1150 console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data)); 1151 }); 1152} catch (err) { 1153 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1154} 1155``` 1156 1157 1158## connection.on('batteryChange')<sup>12+</sup> 1159 1160on(type: 'batteryChange', callback: Callback<BatteryInfo>): void 1161 1162订阅对端设备的电量信息变化事件。使用Callback异步回调。 1163 1164**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1165 1166**系统能力**：SystemCapability.Communication.Bluetooth.Core 1167 1168**参数：** 1169 1170| 参数名 | 类型 | 必填 | 说明 | 1171| -------- | ----------------------------------- | ---- | -------------------------------------- | 1172| type | string | 是 | 事件回调类型，支持的事件为'batteryChange'，表示对端设备的电量信息变化事件。当该设备通知电量变化时，会触发该事件。 | 1173| callback | Callback<[BatteryInfo](#batteryinfo12)> | 是 | 指定订阅的回调函数，返回电量信息。 | 1174 1175**错误码**： 1176 1177以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1178 1179| 错误码ID | 错误信息 | 1180| -------- | ---------------------------- | 1181|201 | Permission denied. | 1182|2900099 | Operation failed. | 1183 1184**示例：** 1185 1186```js 1187import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1188let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1189 console.info('BatteryInfo = '+ JSON.stringify(data)); 1190} 1191try { 1192 connection.on('batteryChange', onReceiveEvent); 1193} catch (err) { 1194 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1195} 1196``` 1197 1198 1199## connection.off('batteryChange')<sup>12+</sup> 1200 1201off(type: 'batteryChange', callback?: Callback<BatteryInfo>): void 1202 1203取消订阅对端设备的电量信息变化事件。 1204 1205**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1206 1207**系统能力**：SystemCapability.Communication.Bluetooth.Core 1208 1209**参数：** 1210 1211| 参数名 | 类型 | 必填 | 说明 | 1212| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1213| type | string | 是 | 事件回调类型，支持的事件为'batteryChange'，表示对端设备的电量信息变化事件。 | 1214| callback | Callback<[BatteryInfo](#batteryinfo12)> | 否 | 指定取消订阅的回调函数通知。<br>若传参，则需与[connection.on('batteryChange')](#connectiononbatterychange12)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。 | 1215 1216**错误码**： 1217 1218以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1219 1220| 错误码ID | 错误信息 | 1221| -------- | ---------------------------- | 1222|201 | Permission denied. | 1223|2900099 | Operation failed. | 1224 1225**示例：** 1226 1227```js 1228import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1229let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1230 console.info('BatteryInfo = '+ JSON.stringify(data)); 1231} 1232try { 1233 connection.on('batteryChange', onReceiveEvent); 1234 connection.off('batteryChange', onReceiveEvent); 1235} catch (err) { 1236 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1237} 1238``` 1239 1240 1241## connection.on('bluetoothDeviceFind') 1242 1243on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void 1244 1245订阅蓝牙设备扫描结果上报事件。使用Callback异步回调。<br> 1246- 可扫描到的设备类型包括传统蓝牙设备和低功耗蓝牙设备。<br> 1247- 该上报方式只支持获取设备地址信息。<br> 1248- 推荐使用API version 18开始支持的[connection.on('discoveryResult')](#connectionondiscoveryresult18)扫描上报方式，可获取到更多设备信息，包括设备地址、设备信号强度、设备名称和设备类型。 1249 1250**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1251 1252**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1253 1254**系统能力**：SystemCapability.Communication.Bluetooth.Core 1255 1256**参数：** 1257 1258| 参数名 | 类型 | 必填 | 说明 | 1259| -------- | ----------------------------------- | ---- | -------------------------------------- | 1260| type | string | 是 | 事件回调类型，支持的事件为'bluetoothDeviceFind'，表示蓝牙设备扫描结果上报事件。当调用[connection.startBluetoothDiscovery](#connectionstartbluetoothdiscovery)后，开始设备扫描，若扫描到设备，触发该事件。 | 1261| callback | Callback<Array<string>> | 是 | 指定订阅的回调函数，会携带扫描到的设备地址集合。<br>基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。<br>- 若和该设备地址配对成功后，该地址不会变更。<br>- 若取消配对该设备或蓝牙关闭后，再次重新发起扫描，该虚拟地址会变更。<br>- 若要持久化保存该地址，可使用[access.addPersistentDeviceId](js-apis-bluetooth-access.md#accessaddpersistentdeviceid16)方法。 | 1262 1263**错误码**： 1264 1265以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ---------------------------- | 1269|201 | Permission denied. | 1270|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1271|801 | Capability not supported. | 1272|2900099 | Operation failed. | 1273 1274**示例：** 1275 1276```js 1277import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1278function onReceiveEvent(data: Array<string>) { // data为蓝牙设备地址集合。 1279 console.info('bluetooth device find = '+ JSON.stringify(data)); 1280} 1281try { 1282 connection.on('bluetoothDeviceFind', onReceiveEvent); 1283} catch (err) { 1284 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1285} 1286``` 1287 1288 1289## connection.off('bluetoothDeviceFind') 1290 1291off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void 1292 1293取消订阅蓝牙设备扫描结果上报事件。 1294 1295**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1296 1297**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1298 1299**系统能力**：SystemCapability.Communication.Bluetooth.Core 1300 1301**参数：** 1302 1303| 参数名 | 类型 | 必填 | 说明 | 1304| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1305| type | string | 是 | 事件回调类型，支持的事件为'bluetoothDeviceFind'，表示蓝牙设备扫描结果上报事件。 | 1306| callback | Callback<Array<string>> | 否 | 指定取消订阅的回调函数通知。<br>若传参，则需与[connection.on('bluetoothDeviceFind')](#connectiononbluetoothdevicefind)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。 | 1307 1308**错误码**： 1309 1310以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1311 1312| 错误码ID | 错误信息 | 1313| -------- | ---------------------------- | 1314|201 | Permission denied. | 1315|801 | Capability not supported. | 1316|2900099 | Operation failed. | 1317 1318**示例：** 1319 1320```js 1321import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1322function onReceiveEvent(data: Array<string>) { 1323 console.info('bluetooth device find = '+ JSON.stringify(data)); 1324} 1325try { 1326 connection.on('bluetoothDeviceFind', onReceiveEvent); 1327 connection.off('bluetoothDeviceFind', onReceiveEvent); 1328} catch (err) { 1329 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1330} 1331``` 1332 1333 1334## connection.on('bondStateChange') 1335 1336on(type: 'bondStateChange', callback: Callback<BondStateParam>): void 1337 1338订阅蓝牙配对状态变化事件。使用Callback异步回调。 1339 1340**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1341 1342**系统能力**：SystemCapability.Communication.Bluetooth.Core 1343 1344**参数：** 1345 1346| 参数名 | 类型 | 必填 | 说明 | 1347| -------- | ---------------------------------------- | ---- | ------------------------------------ | 1348| type | string | 是 | 事件回调类型，支持的事件为'bondStateChange'，表示蓝牙配对状态变化事件。<br>当调用[connection.pairDevice](#connectionpairdevice)发起主动配对，或者本机设备收到其他设备的配对请求时，触发该事件。 | 1349| callback | Callback<[BondStateParam](#bondstateparam)> | 是 | 指定订阅的回调函数，会携带配对状态结果。 | 1350 1351**错误码**： 1352 1353以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1354 1355| 错误码ID | 错误信息 | 1356| -------- | ---------------------------- | 1357|201 | Permission denied. | 1358|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1359|801 | Capability not supported. | 1360|2900099 | Operation failed. | 1361 1362**示例：** 1363 1364```js 1365import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1366function onReceiveEvent(data: connection.BondStateParam) { // data为回调函数入参，表示配对的状态。 1367 console.info('pair state = '+ JSON.stringify(data)); 1368} 1369try { 1370 connection.on('bondStateChange', onReceiveEvent); 1371} catch (err) { 1372 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1373} 1374``` 1375 1376 1377## connection.off('bondStateChange') 1378 1379off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void 1380 1381取消订阅蓝牙配对状态变化事件。 1382 1383**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1384 1385**系统能力**：SystemCapability.Communication.Bluetooth.Core 1386 1387**参数：** 1388 1389| 参数名 | 类型 | 必填 | 说明 | 1390| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1391| type | string | 是 | 事件回调类型，支持的事件为'bondStateChange'，表示蓝牙配对状态变化事件。 | 1392| callback | Callback<[BondStateParam](#bondstateparam)> | 否 | 指定取消订阅的回调函数通知。<br>若传参，则需与[connection.on('bondStateChange')](#connectiononbondstatechange)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。 | 1393 1394**错误码**： 1395 1396以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1397 1398| 错误码ID | 错误信息 | 1399| -------- | ---------------------------- | 1400|201 | Permission denied. | 1401|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1402|801 | Capability not supported. | 1403|2900099 | Operation failed. | 1404 1405**示例：** 1406 1407```js 1408import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1409function onReceiveEvent(data: connection.BondStateParam) { 1410 console.info('bond state = '+ JSON.stringify(data)); 1411} 1412try { 1413 connection.on('bondStateChange', onReceiveEvent); 1414 connection.off('bondStateChange', onReceiveEvent); 1415} catch (err) { 1416 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1417} 1418``` 1419 1420 1421## connection.on('pinRequired') 1422 1423on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void 1424 1425订阅配对请求事件。使用Callback异步回调。 1426 1427**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1428 1429**系统能力**：SystemCapability.Communication.Bluetooth.Core 1430 1431**参数：** 1432 1433| 参数名 | 类型 | 必填 | 说明 | 1434| -------- | ---------------------------------------- | ---- | -------------------------------- | 1435| type | string | 是 | 事件回调类型，支持的事件为'pinRequired'，表示配对请求事件。<br>当调用[connection.pairDevice](#connectionpairdevice)发起主动配对，或者本机设备收到其他设备的配对请求时，触发该事件。 | 1436| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 是 | 指定订阅的回调函数，会携带配对请求。 | 1437 1438**错误码**： 1439 1440以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1441 1442| 错误码ID | 错误信息 | 1443| -------- | ---------------------------- | 1444|201 | Permission denied. | 1445|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1446|801 | Capability not supported. | 1447|2900099 | Operation failed. | 1448 1449**示例：** 1450 1451```js 1452import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1453function onReceiveEvent(data: connection.PinRequiredParam) { // data为配对请求参数。 1454 console.info('pin required = '+ JSON.stringify(data)); 1455} 1456try { 1457 connection.on('pinRequired', onReceiveEvent); 1458} catch (err) { 1459 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1460} 1461``` 1462 1463 1464## connection.off('pinRequired') 1465 1466off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void 1467 1468取消订阅配对请求事件。 1469 1470**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1471 1472**系统能力**：SystemCapability.Communication.Bluetooth.Core 1473 1474**参数：** 1475 1476| 参数名 | 类型 | 必填 | 说明 | 1477| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1478| type | string | 是 | 事件回调类型，支持的事件为'pinRequired'，表示配对请求事件。 | 1479| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 否 | 指定取消订阅的回调函数通知。<br>若传参，则需与[connection.on('pinRequired')](#connectiononpinrequired)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。 | 1480 1481**错误码**： 1482 1483以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1484 1485| 错误码ID | 错误信息 | 1486| -------- | ---------------------------- | 1487|201 | Permission denied. | 1488|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1489|801 | Capability not supported. | 1490|2900099 | Operation failed. | 1491 1492**示例：** 1493 1494```js 1495import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1496function onReceiveEvent(data: connection.PinRequiredParam) { 1497 console.info('pin required = '+ JSON.stringify(data)); 1498} 1499try { 1500 connection.on('pinRequired', onReceiveEvent); 1501 connection.off('pinRequired', onReceiveEvent); 1502} catch (err) { 1503 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1504} 1505``` 1506 1507 1508## connection.on('discoveryResult')<sup>18+</sup> 1509 1510on(type: 'discoveryResult', callback: Callback<Array<DiscoveryResult>>): void 1511 1512订阅蓝牙设备扫描结果上报事件。使用Callback异步回调。<br> 1513- 可扫描到的设备类型包括传统蓝牙设备和低功耗蓝牙设备。<br> 1514- 该上报方式支持获取设备地址、设备信号强度、设备名称和设备类型。 1515 1516**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1517 1518**系统能力**：SystemCapability.Communication.Bluetooth.Core 1519 1520**参数：** 1521 1522| 参数名 | 类型 | 必填 | 说明 | 1523| -------- | ----------------------------------- | ---- | -------------------------------------- | 1524| type | string | 是 | 事件回调类型，支持的事件为'discoveryResult'，表示蓝牙设备扫描结果上报事件。当调用[connection.startBluetoothDiscovery](#connectionstartbluetoothdiscovery)后，开始设备扫描，若扫描到设备，触发该事件。 | 1525| callback | Callback<Array<[DiscoveryResult](#discoveryresult18)>> | 是 | 指定订阅的回调函数，会携带扫描结果的集合。 | 1526 1527**错误码**： 1528 1529以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1530 1531| 错误码ID | 错误信息 | 1532| -------- | ---------------------------- | 1533|201 | Permission denied. | 1534|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1535|801 | Capability not supported. | 1536|2900099 | Operation failed. | 1537 1538**示例：** 1539 1540```js 1541import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1542let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合。 1543 console.info('bluetooth device find = '+ JSON.stringify(data)); 1544} 1545try { 1546 connection.on('discoveryResult', onReceiveEvent); 1547} catch (err) { 1548 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1549} 1550``` 1551 1552 1553## connection.off('discoveryResult')<sup>18+</sup> 1554 1555off(type: 'discoveryResult', callback?: Callback<Array<DiscoveryResult>>): void 1556 1557取消订阅蓝牙设备发现上报事件。 1558 1559**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1560 1561**系统能力**：SystemCapability.Communication.Bluetooth.Core 1562 1563**参数：** 1564 1565| 参数名 | 类型 | 必填 | 说明 | 1566| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1567| type | string | 是 | 事件回调类型，支持的事件为'discoveryResult'，表示蓝牙设备扫描结果上报事件。 | 1568| callback | Callback<Array<[DiscoveryResult](#discoveryresult18)>> | 否 | 指定取消订阅的回调函数通知。<br>若传参，则需与[connection.on('discoveryResult')](#connectionondiscoveryresult18)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。 | 1569 1570**错误码**： 1571 1572以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1573 1574| 错误码ID | 错误信息 | 1575| -------- | ---------------------------- | 1576|201 | Permission denied. | 1577|801 | Capability not supported. | 1578|2900099 | Operation failed. | 1579 1580**示例：** 1581 1582```js 1583import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1584let onReceiveEvent: (data: Array<connection.DiscoveryResult>) => void = (data: Array<connection.DiscoveryResult>) => { // data为蓝牙设备扫描结果集合。 1585 console.info('bluetooth device find = '+ JSON.stringify(data)); 1586} 1587try { 1588 connection.on('discoveryResult', onReceiveEvent); 1589 connection.off('discoveryResult', onReceiveEvent); 1590} catch (err) { 1591 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1592} 1593``` 1594 1595 1596## connection.getLastConnectionTime<sup>15+</sup> 1597 1598getLastConnectionTime(deviceId: string): Promise<number> 1599 1600获取对端蓝牙设备最近一次连接的时间点。使用Promise异步回调。 1601 1602**系统能力**：SystemCapability.Communication.Bluetooth.Core 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| ------ | ------- | ---- | -------------------------------- | 1608| deviceId | string | 是 | 表示远端设备MAC地址。例如："XX:XX:XX:XX:XX:XX"。 | 1609 1610**返回值：** 1611 1612| 类型 | 说明 | 1613| ------------------- | ------------- | 1614| Promise<number> | Promise对象，返回对端蓝牙设备最近一次连接的时间点，格式为秒级的UNIX时间戳。 | 1615 1616**错误码**： 1617 1618以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1619 1620| 错误码ID | 错误信息 | 1621| -------- | ---------------------------- | 1622|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1623|801 | Capability not supported. | 1624|2900001 | Service stopped. | 1625|2900003 | Bluetooth disabled. | 1626|2900099 | Operation failed. | 1627 1628**示例：** 1629 1630```js 1631import { BusinessError } from '@kit.BasicServicesKit'; 1632// promise 1633try { 1634 connection.getLastConnectionTime('11:22:33:44:55:66').then((time: number) => { 1635 console.info(`connectionTime: ${time}`); 1636 }); 1637} catch (err) { 1638 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1639} 1640``` 1641 1642## connection.connectAllowedProfiles<sup>16+</sup> 1643 1644connectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void 1645 1646连接对端设备支持的profile（只包括A2DP、HFP和HID）。使用Callback异步回调。 1647- 需先调用[connection.pairDevice](#connectionpairdevice)发起配对，且仅允许在每次发起配对后30s内调用此接口一次。 1648- 当配对成功后，建议先调用[getRemoteProfileUuids](#connectiongetremoteprofileuuids12)主动查询目标设备支持的profile能力。若存在应用需要的能力，才调用此接口。 1649 1650**需要权限：**: ohos.permission.ACCESS_BLUETOOTH 1651 1652**系统能力：**: SystemCapability.Communication.Bluetooth.Core 1653 1654**参数：** 1655 1656| 参数名 | 类型 | 必填 | 说明 | 1657| -------- | ------ | ---- | ----------------------------------- | 1658| deviceId | string | 是 | 表示需要连接的对端设备地址，例如："XX:XX:XX:XX:XX:XX"。| 1659| callback | AsyncCallback<void> | 是 | 回调函数。当发起连接成功，err为undefined，否则为错误对象。 | 1660 1661**错误码：** 1662 1663以下错误码的详细介绍请参见 [通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1664 1665| 错误码ID| 错误信息| 1666| -------- | ---------------------------- | 1667|201 | Permission denied. | 1668|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1669|801 | Capability not supported. | 1670|2900001 | Service stopped. | 1671|2900003 | Bluetooth disabled. | 1672|2900099 | Operation failed. | 1673 1674**示例：** 1675 1676```js 1677import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1678try { 1679 connection.connectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => { 1680 if (err) { 1681 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1682 return; 1683 } 1684 console.info('connectAllowedProfiles'); 1685 }); 1686} catch (err) { 1687 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1688} 1689``` 1690 1691 1692## connection.connectAllowedProfiles<sup>16+</sup> 1693 1694connectAllowedProfiles(deviceId: string): Promise<void> 1695 1696连接对端设备支持的profile（只包括A2DP、HFP和HID）。使用Promise异步回调。 1697- 需先调用[connection.pairDevice](#connectionpairdevice)发起配对，且仅允许在每次发起配对后30s内调用此接口一次。 1698- 当配对成功后，建议先调用[getRemoteProfileUuids](#connectiongetremoteprofileuuids12)主动查询目标设备支持的profile能力。若存在应用需要的能力，才调用此接口。 1699 1700**需要权限：**: ohos.permission.ACCESS_BLUETOOTH 1701 1702**系统能力：**: SystemCapability.Communication.Bluetooth.Core 1703 1704**参数：** 1705 1706| 参数名 | 类型 | 必填 | 说明 | 1707| -------- | ------ | ---- | ----------------------------------- | 1708| deviceId | string | 是 | 表示需要连接的对端设备地址，例如："XX:XX:XX:XX:XX:XX"。| 1709 1710**返回值：** 1711 1712| 类型 | 说明 | 1713| ------------------------------------------------- | ------------------- | 1714| Promise<void> | Promise对象。无返回结果的Promise对象。| 1715 1716**错误码：** 1717 1718以下错误码的详细介绍请参见 [通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1719 1720| 错误码ID| 错误信息| 1721| -------- | ---------------------------- | 1722|201 | Permission denied. | 1723|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1724|801 | Capability not supported. | 1725|2900001 | Service stopped. | 1726|2900003 | Bluetooth disabled. | 1727|2900099 | Operation failed. | 1728 1729**示例：** 1730 1731```js 1732import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1733try { 1734 connection.connectAllowedProfiles('68:13:24:79:4C:8C').then(() => { 1735 console.info('connectAllowedProfiles'); 1736 }, (err: BusinessError) => { 1737 console.error('connectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message); 1738 }); 1739} catch (err) { 1740 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1741} 1742``` 1743 1744## BondStateParam 1745 1746描述配对状态结果的参数结构。 1747 1748**系统能力**：SystemCapability.Communication.Bluetooth.Core 1749 1750| 名称 | 类型 | 只读 | 可选 | 说明 | 1751| -------- | ------ | ---- | ---- | ----------- | 1752| deviceId | string | 否 | 否 | 配对中的对端设备地址。 | 1753| state | [BondState](#bondstate) | 否 | 否 | 配对状态。 | 1754| cause<sup>12+</sup>| [UnbondCause](#unbondcause12) | 否 | 否 | 配对失败的原因。| 1755 1756 1757## PinRequiredParam 1758 1759描述配对请求的参数结构。 1760 1761**系统能力**：SystemCapability.Communication.Bluetooth.Core 1762 1763| 名称 | 类型 | 只读 | 可选 | 说明 | 1764| -------- | ------ | ---- | ---- | ----------- | 1765| deviceId | string | 否 | 否 | 要配对的对端设备地址。 | 1766| pinCode | string | 否 | 否 | 配对过程中的密钥。 | 1767 1768 1769 1770## DeviceClass 1771 1772描述蓝牙设备的类型。 1773 1774**系统能力**：SystemCapability.Communication.Bluetooth.Core 1775 1776| 名称 | 类型 | 只读 | 可选 | 说明 | 1777| --------------- | ----------------------------------- | ---- | ---- | ---------------- | 1778| majorClass | [MajorClass](js-apis-bluetooth-constant.md#majorclass) | 否 | 否 | 主要类型。是蓝牙标准协议中定义的类型字段。 | 1779| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 否 | 否 | 子类型，是在主要类型上基础上进一步细分的类型。是蓝牙标准协议中定义的类型字段。 | 1780| classOfDevice | number | 否 | 否 | 设备类型。是蓝牙标准协议中定义的类型字段，包含了[MajorClass](js-apis-bluetooth-constant.md#majorclass)、[MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass)和支持的主要服务这三种设备信息。 | 1781 1782 1783## BatteryInfo<sup>12+</sup> 1784 1785描述设备的电量信息。<br>只有支持蓝牙标准协议定义的电量信息AT（Attention）命令（包括：+XEVENT和IPHONEACCEV）的设备才支持上报有效的电量信息。 1786 1787**系统能力**：SystemCapability.Communication.Bluetooth.Core 1788 1789| 名称 | 类型 | 只读 | 可选 | 说明 | 1790| -------- | ------ | ---- | ---- | ----------- | 1791| batteryLevel | number | 否 | 否 | 表示设备的电量值。<br>如果该值为-1，表示没有电量信息。 | 1792| leftEarBatteryLevel | number | 否 | 否 | 若是蓝牙耳机设备类型，表示左侧耳机的电量值。<br>如果该值为-1，表示没有电量信息。 | 1793| leftEarChargeState | [DeviceChargeState](#devicechargestate12) | 否 | 否 | 若是蓝牙耳机设备类型，表示左侧耳机的充电状态。 | 1794| rightEarBatteryLevel | number | 否 | 否 | 若是蓝牙耳机设备类型，表示右侧耳机的电量值。<br>如果该值为-1，表示没有电量信息。 | 1795| rightEarChargeState | [DeviceChargeState](#devicechargestate12) | 否 | 否 | 若是蓝牙耳机设备类型，表示右侧耳机的充电状态。 | 1796| boxBatteryLevel | number | 否 | 否 | 若是蓝牙耳机设备类型，表示耳机仓的电量值。<br>如果值该为-1，表示没有电量信息。 | 1797| boxChargeState | [DeviceChargeState](#devicechargestate12) | 否 | 否 | 若是蓝牙耳机设备类型，表示耳机仓的充电状态。 | 1798 1799 1800## BluetoothTransport 1801 1802枚举，表示设备传输类型。 1803 1804**系统能力**：SystemCapability.Communication.Bluetooth.Core 1805 1806| 名称 | 值 | 说明 | 1807| -------------------------------- | ------ | --------------- | 1808| TRANSPORT_BR_EDR | 0 | 传统蓝牙（Basic Rate/Enhanced Data Rate，BR/EDR）设备传输方式。 | 1809| TRANSPORT_LE | 1 | 低功耗蓝牙（Bluetooth Low Energy，BLE）设备传输方式。 | 1810| TRANSPORT_DUAL<sup>20+</sup> | 2 | 同时支持传统蓝牙（BR/EDR）和低功耗蓝牙（BLE）的双模设备传输方式。设备可以根据需要选择使用传统蓝牙（BR/EDR）或低功耗蓝牙（BLE）进行通信。 | 1811| TRANSPORT_UNKNOWN<sup>20+</sup> | 3 | 未知的设备传输方式。 | 1812 1813 1814## ScanMode 1815 1816枚举，表示扫描模式。该模式决定设备是否可被发现或可被连接。 1817 1818**系统能力**：SystemCapability.Communication.Bluetooth.Core 1819 1820| 名称 | 值 | 说明 | 1821| ---------------------------------------- | ---- | --------------- | 1822| SCAN_MODE_NONE | 0 | 不可发现、不可连接模式。 | 1823| SCAN_MODE_CONNECTABLE | 1 | 可连接模式。 | 1824| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | 通用可发现模式，可被长时间发现。 | 1825| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | 有限可发现模式，持续一定时间。 | 1826| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | 可连接及通用可发现模式。 | 1827| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | 可连接及有限可发现模式。 | 1828 1829 1830## BondState 1831 1832枚举，配对状态。 1833 1834**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1835 1836**系统能力**：SystemCapability.Communication.Bluetooth.Core 1837 1838| 名称 | 值 | 说明 | 1839| ------------------ | ---- | ------ | 1840| BOND_STATE_INVALID | 0 | 未配对状态。 | 1841| BOND_STATE_BONDING | 1 | 配对中的状态。 | 1842| BOND_STATE_BONDED | 2 | 已配对状态。 | 1843 1844 1845## UnbondCause<sup>12+</sup> 1846 1847枚举，配对失败原因。 1848 1849**系统能力**：SystemCapability.Communication.Bluetooth.Core 1850 1851| 名称 | 值 | 说明 | 1852| ------------------ | ---- | ------ | 1853| USER_REMOVED | 0 | 用户主动移除设备。若配对状态[BondState](#bondstate)是已配对，也表示配对成功。| 1854| REMOTE_DEVICE_DOWN | 1 | 对端设备不在线。例如：对端设备蓝牙是关闭的。| 1855| AUTH_FAILURE | 2 | 鉴权失败。例如：两端设备密钥不匹配。| 1856| AUTH_REJECTED | 3 | 鉴权被拒绝。例如：对端设备拒绝了配对请求。 | 1857| INTERNAL_ERROR | 4 | 内部错误。例如：设备不支持配对、配对过程超时等异常。 | 1858 1859 1860## DeviceChargeState<sup>12+</sup> 1861 1862枚举，表示设备当前的充电状态。 1863 1864**系统能力**：SystemCapability.Communication.Bluetooth.Core 1865 1866| 名称 | 值 | 说明 | 1867| ------------------ | ---- | ------ | 1868| DEVICE_NORMAL_CHARGE_NOT_CHARGED | 0 | 不支持超级快充能力的设备当前处于未充电状态。| 1869| DEVICE_NORMAL_CHARGE_IN_CHARGING | 1 | 不支持超级快充能力的设备当前处于充电状态。| 1870| DEVICE_SUPER_CHARGE_NOT_CHARGED | 2 | 支持超级快充能力的设备当前处于未充电状态。| 1871| DEVICE_SUPER_CHARGE_IN_CHARGING | 3 | 支持超级快充能力的设备当前处于充电状态。| 1872 1873## DiscoveryResult<sup>18+</sup> 1874 1875扫描到设备后，上报的扫描结果。 1876 1877**系统能力**：SystemCapability.Communication.Bluetooth.Core 1878 1879| 名称 | 类型 | 只读 | 可选 | 说明 | 1880| -------- | ------ | ---- | ---- | ----------- | 1881| deviceId | string | 否 | 否 | 扫描到的设备地址。<br>基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。<br>- 若和该设备地址配对成功后，该地址不会变更。<br>- 若取消配对该设备或蓝牙关闭后，再次重新发起扫描，该虚拟地址会变更。<br>- 若要持久化保存该地址，可使用[access.addPersistentDeviceId](js-apis-bluetooth-access.md#accessaddpersistentdeviceid16)方法。| 1882| rssi | number | 否 | 否 | 扫描到的设备信号强度，单位：dBm。| 1883| deviceName | string | 否 | 否 | 扫描到的设备名称。| 1884| deviceClass | [DeviceClass](#deviceclass) | 否 | 否 | 扫描到的设备类型。|