1# @ohos.bluetooth.connection (蓝牙connection模块) 2 3connection模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10 11## 导入模块 12 13```js 14import { connection } from '@kit.ConnectivityKit'; 15``` 16 17 18## ProfileConnectionState 19 20type ProfileConnectionState = constant.ProfileConnectionState 21 22蓝牙设备的profile连接状态。 23 24**系统能力**：SystemCapability.Communication.Bluetooth.Core。 25 26| 类型 | 说明 | 27| ------------------- | ------------------- | 28| [constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 蓝牙设备的profile连接状态。 | 29 30 31## ProfileId 32 33type ProfileId = constant.ProfileId 34 35蓝牙profile枚举。 36 37**系统能力**：SystemCapability.Communication.Bluetooth.Core。 38 39| 类型 | 说明 | 40| ------------------- | ------------------- | 41| [constant.ProfileId](js-apis-bluetooth-constant.md#profileid) | 蓝牙profile枚举。 | 42 43 44## ProfileUuids 45 46type ProfileUuids = constant.ProfileUuids 47 48表示Profile的UUID。 49 50**系统能力**：SystemCapability.Communication.Bluetooth.Core。 51 52| 类型 | 说明 | 53| ------------------- | ------------------- | 54| [constant.ProfileUuids](js-apis-bluetooth-constant.md#profileuuids) | 表示Profile的UUID。 | 55 56 57## MajorClass 58 59type MajorClass = constant.MajorClass 60 61蓝牙设备主要类别 62 63**系统能力**：SystemCapability.Communication.Bluetooth.Core。 64 65| 类型 | 说明 | 66| ------------------- | ------------------- | 67| [constant.MajorClass](js-apis-bluetooth-constant.md#majorclass) | 蓝牙设备主要类别。 | 68 69 70## MajorMinorClass 71 72type MajorMinorClass = constant.MajorMinorClass 73 74主要次要蓝牙设备类别 75 76**系统能力**：SystemCapability.Communication.Bluetooth.Core。 77 78| 类型 | 说明 | 79| ------------------- | ------------------- | 80| [constant.MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 主要次要蓝牙设备类别。 | 81 82 83## connection.pairDevice 84 85pairDevice(deviceId: string, callback: AsyncCallback<void>): void 86 87发起蓝牙配对。使用Callback异步回调。 88 89**需要权限**：ohos.permission.ACCESS_BLUETOOTH 90 91**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 92 93**系统能力**：SystemCapability.Communication.Bluetooth.Core。 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| -------- | ------ | ---- | ----------------------------------- | 99| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 100| callback | AsyncCallback<void> | 是 | 回调函数。当配对成功，err为undefined，否则为错误对象。 | 101 102**错误码**： 103 104以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 105 106| 错误码ID | 错误信息 | 107| -------- | ---------------------------- | 108|201 | Permission denied. | 109|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 110|801 | Capability not supported. | 111|2900001 | Service stopped. | 112|2900003 | Bluetooth disabled. | 113|2900099 | Operation failed. | 114 115**示例：** 116 117```js 118import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 119//callback 120try { 121 connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => { 122 console.info('pairDevice, device name err:' + JSON.stringify(err)); 123 }); 124} catch (err) { 125 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 126} 127 128``` 129 130 131## connection.pairDevice 132 133pairDevice(deviceId: string): Promise<void> 134 135发起蓝牙配对。使用Promise异步回调。 136 137**需要权限**：ohos.permission.ACCESS_BLUETOOTH 138 139**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 140 141**系统能力**：SystemCapability.Communication.Bluetooth.Core。 142 143**参数：** 144 145| 参数名 | 类型 | 必填 | 说明 | 146| -------- | ------ | ---- | ----------------------------------- | 147| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 148 149**返回值：** 150 151| 类型 | 说明 | 152| ------------------- | ------------- | 153| Promise<void> | 返回promise对象。 | 154 155**错误码**： 156 157以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 158 159| 错误码ID | 错误信息 | 160| -------- | ---------------------------- | 161|201 | Permission denied. | 162|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 163|801 | Capability not supported. | 164|2900001 | Service stopped. | 165|2900003 | Bluetooth disabled. | 166|2900099 | Operation failed. | 167 168**示例：** 169 170```js 171import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 172//promise 173try { 174 connection.pairDevice('11:22:33:44:55:66').then(() => { 175 console.info('pairDevice'); 176 }, (error: BusinessError) => { 177 console.info('pairDevice: errCode:' + error.code + ',errMessage' + error.message); 178 }) 179 180} catch (err) { 181 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 182} 183``` 184 185 186## connection.getRemoteDeviceName 187 188getRemoteDeviceName(deviceId: string): string 189 190获取对端蓝牙设备的名称。 191 192**需要权限**：ohos.permission.ACCESS_BLUETOOTH 193 194**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 195 196**系统能力**：SystemCapability.Communication.Bluetooth.Core。 197 198**参数：** 199 200| 参数名 | 类型 | 必填 | 说明 | 201| -------- | ------ | ---- | --------------------------------- | 202| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 203 204**返回值：** 205 206| 类型 | 说明 | 207| ------ | ------------- | 208| string | 以字符串格式返回设备名称。 | 209 210**错误码**： 211 212以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 213 214| 错误码ID | 错误信息 | 215| -------- | ---------------------------- | 216|201 | Permission denied. | 217|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 218|801 | Capability not supported. | 219|2900001 | Service stopped. | 220|2900003 | Bluetooth disabled. | 221|2900099 | Operation failed. | 222 223**示例：** 224 225```js 226import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 227try { 228 let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX'); 229} catch (err) { 230 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 231} 232``` 233 234 235## connection.getRemoteDeviceClass 236 237getRemoteDeviceClass(deviceId: string): DeviceClass 238 239获取对端蓝牙设备的类别。 240 241**需要权限**：ohos.permission.ACCESS_BLUETOOTH 242 243**系统能力**：SystemCapability.Communication.Bluetooth.Core。 244 245**参数：** 246 247| 参数名 | 类型 | 必填 | 说明 | 248| -------- | ------ | ---- | --------------------------------- | 249| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 250 251**返回值：** 252 253| 类型 | 说明 | 254| --------------------------- | -------- | 255| [DeviceClass](#deviceclass) | 远程设备的类别。 | 256 257**错误码**： 258 259以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 260 261| 错误码ID | 错误信息 | 262| -------- | ---------------------------- | 263|201 | Permission denied. | 264|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 265|801 | Capability not supported. | 266|2900001 | Service stopped. | 267|2900003 | Bluetooth disabled. | 268|2900099 | Operation failed. | 269 270**示例：** 271 272```js 273import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 274try { 275 let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX'); 276} catch (err) { 277 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 278} 279``` 280 281 282## connection.getRemoteProfileUuids<sup>12+</sup> 283 284getRemoteProfileUuids(deviceId: string, callback: AsyncCallback<Array<ProfileUuids>>): void 285 286获取对端蓝牙设备支持的Profile UUID。使用Callback异步回调。 287 288**需要权限**：ohos.permission.ACCESS_BLUETOOTH 289 290**系统能力**：SystemCapability.Communication.Bluetooth.Core。 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| -------- | ------ | ---- | ----------------------------------- | 296| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 297| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | 298 299**错误码**： 300 301以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 302 303| 错误码ID | 错误信息 | 304| -------- | ---------------------------- | 305|201 | Permission denied. | 306|401 | Invalid parameter. | 307|801 | Capability not supported. | 308|2900001 | Service stopped. | 309|2900003 | Bluetooth disabled. | 310|2900099 | Operation failed. | 311 312**示例：** 313 314```js 315import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 316try { 317 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => { 318 console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); 319 }); 320} catch (err) { 321 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 322} 323 324``` 325 326 327## connection.getRemoteProfileUuids<sup>12+</sup> 328 329getRemoteProfileUuids(deviceId: string): Promise<Array<ProfileUuids>> 330 331获取对端蓝牙设备支持的Profile UUID。使用Promise异步回调。 332 333**需要权限**：ohos.permission.ACCESS_BLUETOOTH 334 335**系统能力**：SystemCapability.Communication.Bluetooth.Core。 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | ------ | ---- | ----------------------------------- | 341| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 342 343**返回值：** 344 345| 类型 | 说明 | 346| ------------------- | ------------- | 347| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | 返回promise对象。 | 348 349**错误码**： 350 351以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 352 353| 错误码ID | 错误信息 | 354| -------- | ---------------------------- | 355|201 | Permission denied. | 356|401 | Invalid parameter. | 357|801 | Capability not supported. | 358|2900001 | Service stopped. | 359|2900003 | Bluetooth disabled. | 360|2900099 | Operation failed. | 361 362**示例：** 363 364```js 365import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 366try { 367 connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => { 368 console.info('getRemoteProfileUuids'); 369 }, (err: BusinessError) => { 370 console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 371 }); 372} catch (err) { 373 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 374} 375``` 376 377 378## connection.getLocalName 379 380getLocalName(): string 381 382获取蓝牙本地设备名称。 383 384**需要权限**：ohos.permission.ACCESS_BLUETOOTH 385 386**系统能力**：SystemCapability.Communication.Bluetooth.Core。 387 388**返回值：** 389 390| 类型 | 说明 | 391| ------ | --------- | 392| string | 蓝牙本地设备名称。 | 393 394**错误码**： 395 396以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 397 398| 错误码ID | 错误信息 | 399| -------- | ---------------------------- | 400|201 | Permission denied. | 401|801 | Capability not supported. | 402|2900001 | Service stopped. | 403|2900099 | Operation failed. | 404 405**示例：** 406 407```js 408import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 409try { 410 let localName: string = connection.getLocalName(); 411} catch (err) { 412 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 413} 414``` 415 416 417## connection.getPairedDevices 418 419getPairedDevices(): Array<string> 420 421获取蓝牙配对列表。 422 423**需要权限**：ohos.permission.ACCESS_BLUETOOTH 424 425**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 426 427**系统能力**：SystemCapability.Communication.Bluetooth.Core。 428 429**返回值：** 430 431| 类型 | 说明 | 432| ------------------- | ------------- | 433| Array<string> | 已配对蓝牙设备的地址列表。基于信息安全考虑，此处获取的设备地址为随机MAC地址。配对成功后，该地址不会变更；已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 434 435**错误码**： 436 437以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 438 439| 错误码ID | 错误信息 | 440| -------- | ---------------------------- | 441|201 | Permission denied. | 442|801 | Capability not supported. | 443|2900001 | Service stopped. | 444|2900003 | Bluetooth disabled. | 445|2900099 | Operation failed. | 446 447**示例：** 448 449```js 450import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 451try { 452 let devices: Array<string> = connection.getPairedDevices(); 453} catch (err) { 454 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 455} 456``` 457 458 459## connection.getPairState<sup>11+</sup> 460 461getPairState(deviceId: string): BondState 462 463获取蓝牙配对状态。 464 465**需要权限**：ohos.permission.ACCESS_BLUETOOTH 466 467**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 468 469**系统能力**：SystemCapability.Communication.Bluetooth.Core。 470 471**参数：** 472 473| 参数名 | 类型 | 必填 | 说明 | 474| -------- | ------ | ---- | --------------------------------- | 475| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 476 477**返回值：** 478 479| 类型 | 说明 | 480| --------------------------- | -------- | 481| [BondState](#bondstate) | 表示设备的蓝牙配对状态。 | 482 483**错误码**： 484 485以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 486 487| 错误码ID | 错误信息 | 488| -------- | ---------------------------- | 489|201 | Permission denied. | 490|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 491|801 | Capability not supported. | 492|2900001 | Service stopped. | 493|2900003 | Bluetooth disabled. | 494|2900099 | Operation failed. | 495 496**示例：** 497 498```js 499import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 500try { 501 let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX"); 502 console.info('getPairState: ' + res); 503} catch (err) { 504 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 505} 506``` 507 508 509## connection.getProfileConnectionState 510 511getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState 512 513获取蓝牙Profile的连接状态，其中ProfileId为可选参数。如果携带ProfileId，则返回的是当前Profile的连接状态。如果未携带ProfileId，任一Profile已连接则返回[STATE_CONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)，否则返回[STATE_DISCONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)。 514 515**需要权限**：ohos.permission.ACCESS_BLUETOOTH 516 517**系统能力**：SystemCapability.Communication.Bluetooth.Core。 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| --------- | --------- | ---- | ------------------------------------- | 523| profileId | [ProfileId](js-apis-bluetooth-constant.md#profileid) | 否 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | 524 525**返回值：** 526 527| 类型 | 说明 | 528| ------------------------------------------------- | ------------------- | 529| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | profile的连接状态。 | 530 531**错误码**： 532 533以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 534 535| 错误码ID | 错误信息 | 536| -------- | ---------------------------- | 537|201 | Permission denied. | 538|401 | Invalid parameter. Possible causes: 1. Incorrect parameter types. | 539|801 | Capability not supported. | 540|2900001 | Service stopped. | 541|2900003 | Bluetooth disabled. | 542|2900004 | Profile not supported. | 543|2900099 | Operation failed. | 544 545**示例：** 546 547```js 548import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 549import { constant } from '@kit.ConnectivityKit'; 550try { 551 let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE); 552} catch (err) { 553 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 554} 555``` 556 557 558## connection.setDevicePairingConfirmation 559 560setDevicePairingConfirmation(deviceId: string, accept: boolean): void 561 562设置设备配对请求确认。 563 564**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请） 565 566**系统能力**：SystemCapability.Communication.Bluetooth.Core。 567 568**参数：** 569 570| 参数名 | 类型 | 必填 | 说明 | 571| ------ | ------- | ---- | -------------------------------- | 572| deviceId | string | 是 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 573| accept | boolean | 是 | 接受配对请求设置为true，否则设置为false。 | 574 575**错误码**： 576 577以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 578 579| 错误码ID | 错误信息 | 580| -------- | ---------------------------- | 581|201 | Permission denied. | 582|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 583|801 | Capability not supported. | 584|2900001 | Service stopped. | 585|2900003 | Bluetooth disabled. | 586|2900099 | Operation failed. | 587 588**示例：** 589 590```js 591import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 592// 订阅“pinRequired”配对请求事件，收到远端配对请求后设置配对确认 593function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data为配对请求的入参，配对请求参数 594 console.info('pin required = '+ JSON.stringify(data)); 595 connection.setDevicePairingConfirmation(data.deviceId, true); 596} 597try { 598 connection.on('pinRequired', onReceivePinRequiredEvent); 599} catch (err) { 600 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 601} 602``` 603 604 605## connection.setDevicePinCode 606 607setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void 608 609当蓝牙配对类型PinType为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。使用Callback异步回调。 610 611**需要权限**：ohos.permission.ACCESS_BLUETOOTH 612 613**系统能力**：SystemCapability.Communication.Bluetooth.Core。 614 615**参数：** 616 617| 参数名 | 类型 | 必填 | 说明 | 618| ------ | ------- | ---- | -------------------------------- | 619| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 620| code | string | 是 | 用户输入的PIN码。 | 621| callback | AsyncCallback<void> | 是 | 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。 | 622 623**错误码**： 624 625以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 626 627| 错误码ID | 错误信息 | 628| -------- | ---------------------------- | 629|201 | Permission denied. | 630|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 631|801 | Capability not supported. | 632|2900001 | Service stopped. | 633|2900003 | Bluetooth disabled. | 634|2900099 | Operation failed. | 635 636**示例：** 637 638```js 639import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 640//callback 641try { 642 connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => { 643 console.info('setDevicePinCode,device name err:' + JSON.stringify(err)); 644 }); 645} catch (err) { 646 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 647} 648``` 649 650 651## connection.setDevicePinCode 652 653setDevicePinCode(deviceId: string, code: string): Promise<void> 654 655当蓝牙配对类型PinType为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。使用Promise异步回调。 656 657**需要权限**：ohos.permission.ACCESS_BLUETOOTH 658 659**系统能力**：SystemCapability.Communication.Bluetooth.Core。 660 661**参数：** 662 663| 参数名 | 类型 | 必填 | 说明 | 664| ------ | ------- | ---- | -------------------------------- | 665| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 666| code | string | 是 | 用户输入的PIN码。 | 667 668**返回值：** 669 670| 类型 | 说明 | 671| ------------------- | ------------- | 672| Promise<void> | 返回promise对象。 | 673 674**错误码**： 675 676以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 677 678| 错误码ID | 错误信息 | 679| -------- | ---------------------------- | 680|201 | Permission denied. | 681|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 682|801 | Capability not supported. | 683|2900001 | Service stopped. | 684|2900003 | Bluetooth disabled. | 685|2900099 | Operation failed. | 686 687**示例：** 688 689```js 690import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 691//promise 692try { 693 connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { 694 console.info('setDevicePinCode'); 695 }, (error: BusinessError) => { 696 console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); 697 }) 698 699} catch (err) { 700 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 701} 702``` 703 704 705## connection.setLocalName<sup>(deprecated)</sup> 706 707setLocalName(name: string): void 708 709设置蓝牙本地设备名称。 710 711> **说明：**<br/> 712> 从API version 10开始支持，从API version 12开始废弃，不再提供替代接口。 713 714**需要权限**：ohos.permission.ACCESS_BLUETOOTH 715 716**系统能力**：SystemCapability.Communication.Bluetooth.Core。 717 718**参数：** 719 720| 参数名 | 类型 | 必填 | 说明 | 721| ---- | ------ | ---- | --------------------- | 722| name | string | 是 | 要设置的蓝牙名称，最大长度为248字节数。 | 723 724**错误码**： 725 726以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 727 728| 错误码ID | 错误信息 | 729| -------- | ---------------------------- | 730|201 | Permission denied. | 731|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 732|801 | Capability not supported. | 733|2900001 | Service stopped. | 734|2900003 | Bluetooth disabled. | 735|2900099 | Operation failed. | 736 737**示例：** 738 739```js 740import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 741try { 742 connection.setLocalName('device_name'); 743} catch (err) { 744 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 745} 746``` 747 748 749## connection.setBluetoothScanMode 750 751setBluetoothScanMode(mode: ScanMode, duration: number): void 752 753设置蓝牙扫描模式，可以被远端设备发现。 754 755**需要权限**：ohos.permission.ACCESS_BLUETOOTH 756 757**系统能力**：SystemCapability.Communication.Bluetooth.Core。 758 759**参数：** 760 761| 参数名 | 类型 | 必填 | 说明 | 762| -------- | --------------------- | ---- | ---------------------------- | 763| mode | [ScanMode](#scanmode) | 是 | 蓝牙扫描模式。当扫描模式为SCAN_MODE_GENERAL_DISCOVERABLE时，如果超出duration持续时间（不为0），扫描模式会重新设置为SCAN_MODE_CONNECTABLE。 | 764| duration | number | 是 | 设备可被发现的持续时间，单位为毫秒；设置为0则持续可发现。 | 765 766**错误码**： 767 768以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 769 770| 错误码ID | 错误信息 | 771| -------- | ---------------------------- | 772|201 | Permission denied. | 773|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 774|801 | Capability not supported. | 775|2900001 | Service stopped. | 776|2900003 | Bluetooth disabled. | 777|2900099 | Operation failed. | 778 779**示例：** 780 781```js 782import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 783try { 784 // 设置为可连接可发现才可被远端设备扫描到，可以连接。 785 connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); 786} catch (err) { 787 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 788} 789``` 790 791 792## connection.getBluetoothScanMode 793 794getBluetoothScanMode(): ScanMode 795 796获取蓝牙扫描模式。 797 798**需要权限**：ohos.permission.ACCESS_BLUETOOTH 799 800**系统能力**：SystemCapability.Communication.Bluetooth.Core。 801 802**返回值：** 803 804| 类型 | 说明 | 805| --------------------- | ------- | 806| [ScanMode](#scanmode) | 蓝牙扫描模式。 | 807 808**错误码**： 809 810以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 811 812| 错误码ID | 错误信息 | 813| -------- | ---------------------------- | 814|201 | Permission denied. | 815|801 | Capability not supported. | 816|2900001 | Service stopped. | 817|2900003 | Bluetooth disabled. | 818|2900099 | Operation failed. | 819 820**示例：** 821 822```js 823import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 824try { 825 let scanMode: connection.ScanMode = connection.getBluetoothScanMode(); 826} catch (err) { 827 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 828} 829``` 830 831 832## connection.startBluetoothDiscovery 833 834startBluetoothDiscovery(): void 835 836开启蓝牙扫描，可以发现远端设备。 837 838**需要权限**：ohos.permission.ACCESS_BLUETOOTH 839 840**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 841 842**系统能力**：SystemCapability.Communication.Bluetooth.Core。 843 844**错误码**： 845 846以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 847 848| 错误码ID | 错误信息 | 849| -------- | ---------------------------- | 850|201 | Permission denied. | 851|801 | Capability not supported. | 852|2900001 | Service stopped. | 853|2900003 | Bluetooth disabled. | 854|2900099 | Operation failed. | 855 856**示例：** 857 858```js 859import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 860function onReceiveEvent(data: Array<string>) { 861 console.info('data length' + data.length); 862} 863try { 864 connection.on('bluetoothDeviceFind', onReceiveEvent); 865 connection.startBluetoothDiscovery(); 866} catch (err) { 867 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 868} 869``` 870 871 872## connection.stopBluetoothDiscovery 873 874stopBluetoothDiscovery(): void 875 876关闭蓝牙扫描。 877 878**需要权限**：ohos.permission.ACCESS_BLUETOOTH 879 880**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 881 882**系统能力**：SystemCapability.Communication.Bluetooth.Core。 883 884**错误码**： 885 886以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 887 888| 错误码ID | 错误信息 | 889| -------- | ---------------------------- | 890|201 | Permission denied. | 891|801 | Capability not supported. | 892|2900001 | Service stopped. | 893|2900003 | Bluetooth disabled. | 894|2900099 | Operation failed. | 895 896**示例：** 897 898```js 899import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 900try { 901 connection.stopBluetoothDiscovery(); 902} catch (err) { 903 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 904} 905``` 906 907 908## connection.isBluetoothDiscovering<sup>11+</sup> 909 910isBluetoothDiscovering(): boolean 911 912查询设备的蓝牙发现状态。 913 914**需要权限**：ohos.permission.ACCESS_BLUETOOTH 915 916**系统能力**：SystemCapability.Communication.Bluetooth.Core。 917 918**返回值：** 919 920| 类型 | 说明 | 921| ------------------- | ------------- | 922| boolean | 设备已开启蓝牙发现为true，否则为false。 | 923 924**错误码**： 925 926以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 927 928| 错误码ID | 错误信息 | 929| -------- | ---------------------------- | 930|201 | Permission denied. | 931|801 | Capability not supported. | 932|2900001 | Service stopped. | 933|2900003 | Bluetooth disabled. | 934|2900099 | Operation failed. | 935 936**示例：** 937 938```js 939import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 940try { 941 let res: boolean = connection.isBluetoothDiscovering(); 942 console.info('isBluetoothDiscovering: ' + res); 943} catch (err) { 944 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 945} 946``` 947 948## connection.setRemoteDeviceName<sup>12+</sup> 949 950setRemoteDeviceName(deviceId: string, name: string): Promise<void> 951 952设置蓝牙远端设备名称。使用Promise异步回调。 953 954**需要权限**：ohos.permission.ACCESS_BLUETOOTH 955 956**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 957 958**系统能力**：SystemCapability.Communication.Bluetooth.Core。 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963| -------- | ----------------------------------- | ---- | -------------------------------------- | 964| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 965| name | string | 是 | 修改远端设备名称，最大长度为64字节。 | 966 967**返回值：** 968 969| 类型 | 说明 | 970| ------------------- | ------------- | 971| Promise<void> | 以Promise形式返回设置蓝牙远端设备名称的结果，设置失败时返回错误码信息。 | 972 973**错误码**： 974 975以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 976 977| 错误码ID | 错误信息 | 978| -------- | ---------------------------- | 979|201 | Permission denied. | 980|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 981|2900001 | Service stopped. | 982|2900003 | Bluetooth disabled. | 983 984**示例：** 985 986```js 987import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 988//promise 989try { 990 connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => { 991 console.info('setRemoteDeviceName success'); 992 }, (error: BusinessError) => { 993 console.error('setRemoteDeviceName: errCode:' + error.code + ',errMessage' + error.message); 994 }) 995 996} catch (err) { 997 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 998} 999``` 1000 1001 1002## connection.getRemoteDeviceBatteryInfo<sup>12+</sup> 1003 1004getRemoteDeviceBatteryInfo(deviceId: string): Promise<BatteryInfo> 1005 1006获取蓝牙远端设备的电量信息。使用Promise异步回调。 1007 1008**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1009 1010**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1011 1012**参数：** 1013 1014| 参数名 | 类型 | 必填 | 说明 | 1015| ------ | ------- | ---- | -------------------------------- | 1016| deviceId | string | 是 | 表示远端设备MAC地址，例如："11:22:33:AA:BB:FF"。 | 1017 1018**返回值：** 1019 1020| 类型 | 说明 | 1021| ------------------- | ------------- | 1022| Promise<[BatteryInfo](#batteryinfo12)> | 以Promise形式返回蓝牙远端设备的电量信息。 | 1023 1024**错误码**： 1025 1026以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1027 1028| 错误码ID | 错误信息 | 1029| -------- | ---------------------------- | 1030|201 | Permission denied. | 1031|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1032|2900001 | Service stopped. | 1033|2900003 | Bluetooth disabled. | 1034 1035**示例：** 1036 1037```js 1038import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1039// promise 1040try { 1041 connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => { 1042 console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data)); 1043 }); 1044} catch (err) { 1045 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1046} 1047``` 1048 1049 1050## connection.on('batteryChange')<sup>12+</sup> 1051 1052on(type: 'batteryChange', callback: Callback<BatteryInfo>): void 1053 1054订阅蓝牙远程设备的电量信息变更事件。使用Callback异步回调。 1055 1056**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1057 1058**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1059 1060**参数：** 1061 1062| 参数名 | 类型 | 必填 | 说明 | 1063| -------- | ----------------------------------- | ---- | -------------------------------------- | 1064| type | string | 是 | 填写"batteryChange"字符串，表示蓝牙远端设备的电池信息变更事件。 | 1065| callback | Callback<[BatteryInfo](#batteryinfo12)> | 是 | 表示回调函数的入参，返回电量信息。 | 1066 1067**错误码**： 1068 1069以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1070 1071| 错误码ID | 错误信息 | 1072| -------- | ---------------------------- | 1073|201 | Permission denied. | 1074|2900099 | Operation failed. | 1075 1076**示例：** 1077 1078```js 1079import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1080let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1081 console.info('BatteryInfo = '+ JSON.stringify(data)); 1082} 1083try { 1084 connection.on('batteryChange', onReceiveEvent); 1085} catch (err) { 1086 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1087} 1088``` 1089 1090 1091## connection.off('batteryChange')<sup>12+</sup> 1092 1093off(type: 'batteryChange', callback?: Callback<BatteryInfo>): void 1094 1095取消订阅蓝牙远程设备的电量信息变更事件。 1096 1097**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1098 1099**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1100 1101**参数：** 1102 1103| 参数名 | 类型 | 必填 | 说明 | 1104| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1105| type | string | 是 | 填写"batteryChange"字符串，表示取消蓝牙远端设备的电池信息变更事件。 | 1106| callback | Callback<[BatteryInfo](#batteryinfo12)> | 否 | 表示回调函数的入参，返回电量信息。 | 1107 1108**错误码**： 1109 1110以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1111 1112| 错误码ID | 错误信息 | 1113| -------- | ---------------------------- | 1114|201 | Permission denied. | 1115|2900099 | Operation failed. | 1116 1117**示例：** 1118 1119```js 1120import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1121let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => { 1122 console.info('BatteryInfo = '+ JSON.stringify(data)); 1123} 1124try { 1125 connection.on('batteryChange', onReceiveEvent); 1126 connection.off('batteryChange', onReceiveEvent); 1127} catch (err) { 1128 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1129} 1130``` 1131 1132 1133## connection.on('bluetoothDeviceFind') 1134 1135on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void 1136 1137订阅蓝牙设备发现上报事件。使用Callback异步回调。 1138 1139**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1140 1141**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1142 1143**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1144 1145**参数：** 1146 1147| 参数名 | 类型 | 必填 | 说明 | 1148| -------- | ----------------------------------- | ---- | -------------------------------------- | 1149| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | 1150| callback | Callback<Array<string>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。基于信息安全考虑，此处获取的设备地址为随机MAC地址。配对成功后，该地址不会变更；已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 1151 1152**错误码**： 1153 1154以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1155 1156| 错误码ID | 错误信息 | 1157| -------- | ---------------------------- | 1158|201 | Permission denied. | 1159|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1160|801 | Capability not supported. | 1161|2900099 | Operation failed. | 1162 1163**示例：** 1164 1165```js 1166import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1167function onReceiveEvent(data: Array<string>) { // data为蓝牙设备地址集合 1168 console.info('bluetooth device find = '+ JSON.stringify(data)); 1169} 1170try { 1171 connection.on('bluetoothDeviceFind', onReceiveEvent); 1172} catch (err) { 1173 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1174} 1175``` 1176 1177 1178## connection.off('bluetoothDeviceFind') 1179 1180off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void 1181 1182取消订阅蓝牙设备发现上报事件。 1183 1184**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1185 1186**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1187 1188**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1189 1190**参数：** 1191 1192| 参数名 | 类型 | 必填 | 说明 | 1193| -------- | ----------------------------------- | ---- | ---------------------------------------- | 1194| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | 1195| callback | Callback<Array<string>> | 否 | 表示取消订阅蓝牙设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1196 1197**错误码**： 1198 1199以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1200 1201| 错误码ID | 错误信息 | 1202| -------- | ---------------------------- | 1203|201 | Permission denied. | 1204|801 | Capability not supported. | 1205|2900099 | Operation failed. | 1206 1207**示例：** 1208 1209```js 1210import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1211function onReceiveEvent(data: Array<string>) { 1212 console.info('bluetooth device find = '+ JSON.stringify(data)); 1213} 1214try { 1215 connection.on('bluetoothDeviceFind', onReceiveEvent); 1216 connection.off('bluetoothDeviceFind', onReceiveEvent); 1217} catch (err) { 1218 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1219} 1220``` 1221 1222 1223## connection.on('bondStateChange') 1224 1225on(type: 'bondStateChange', callback: Callback<BondStateParam>): void 1226 1227订阅蓝牙配对状态改变事件。使用Callback异步回调。 1228 1229**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1230 1231**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1232 1233**参数：** 1234 1235| 参数名 | 类型 | 必填 | 说明 | 1236| -------- | ---------------------------------------- | ---- | ------------------------------------ | 1237| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | 1238| callback | Callback<[BondStateParam](#bondstateparam)> | 是 | 表示回调函数的入参，配对的状态。回调函数由用户创建通过该接口注册。 | 1239 1240**错误码**： 1241 1242以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1243 1244| 错误码ID | 错误信息 | 1245| -------- | ---------------------------- | 1246|201 | Permission denied. | 1247|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1248|801 | Capability not supported. | 1249|2900099 | Operation failed. | 1250 1251**示例：** 1252 1253```js 1254import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1255function onReceiveEvent(data: connection.BondStateParam) { // data为回调函数入参，表示配对的状态 1256 console.info('pair state = '+ JSON.stringify(data)); 1257} 1258try { 1259 connection.on('bondStateChange', onReceiveEvent); 1260} catch (err) { 1261 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1262} 1263``` 1264 1265 1266## connection.off('bondStateChange') 1267 1268off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void 1269 1270取消订阅蓝牙配对状态改变事件。 1271 1272**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1273 1274**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1275 1276**参数：** 1277 1278| 参数名 | 类型 | 必填 | 说明 | 1279| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1280| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | 1281| callback | Callback<[BondStateParam](#bondstateparam)> | 否 | 表示取消订阅蓝牙配对状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1282 1283**错误码**： 1284 1285以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1286 1287| 错误码ID | 错误信息 | 1288| -------- | ---------------------------- | 1289|201 | Permission denied. | 1290|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1291|801 | Capability not supported. | 1292|2900099 | Operation failed. | 1293 1294**示例：** 1295 1296```js 1297import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1298function onReceiveEvent(data: connection.BondStateParam) { 1299 console.info('bond state = '+ JSON.stringify(data)); 1300} 1301try { 1302 connection.on('bondStateChange', onReceiveEvent); 1303 connection.off('bondStateChange', onReceiveEvent); 1304} catch (err) { 1305 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1306} 1307``` 1308 1309 1310## connection.on('pinRequired') 1311 1312on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void 1313 1314订阅远端蓝牙设备的配对请求事件。使用Callback异步回调。 1315 1316**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1317 1318**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1319 1320**参数：** 1321 1322| 参数名 | 类型 | 必填 | 说明 | 1323| -------- | ---------------------------------------- | ---- | -------------------------------- | 1324| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | 1325| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 是 | 表示回调函数的入参，配对请求。回调函数由用户创建通过该接口注册。 | 1326 1327**错误码**： 1328 1329以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1330 1331| 错误码ID | 错误信息 | 1332| -------- | ---------------------------- | 1333|201 | Permission denied. | 1334|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1335|801 | Capability not supported. | 1336|2900099 | Operation failed. | 1337 1338**示例：** 1339 1340```js 1341import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1342function onReceiveEvent(data: connection.PinRequiredParam) { // data为配对请求参数 1343 console.info('pin required = '+ JSON.stringify(data)); 1344} 1345try { 1346 connection.on('pinRequired', onReceiveEvent); 1347} catch (err) { 1348 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1349} 1350``` 1351 1352 1353## connection.off('pinRequired') 1354 1355off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void 1356 1357取消订阅远端蓝牙设备的配对请求事件。 1358 1359**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1360 1361**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1362 1363**参数：** 1364 1365| 参数名 | 类型 | 必填 | 说明 | 1366| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1367| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | 1368| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 否 | 表示取消订阅蓝牙配对请求事件上报，入参为配对请求参数。不填该参数则取消订阅该type对应的所有回调。 | 1369 1370**错误码**： 1371 1372以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1373 1374| 错误码ID | 错误信息 | 1375| -------- | ---------------------------- | 1376|201 | Permission denied. | 1377|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1378|801 | Capability not supported. | 1379|2900099 | Operation failed. | 1380 1381**示例：** 1382 1383```js 1384import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1385function onReceiveEvent(data: connection.PinRequiredParam) { 1386 console.info('pin required = '+ JSON.stringify(data)); 1387} 1388try { 1389 connection.on('pinRequired', onReceiveEvent); 1390 connection.off('pinRequired', onReceiveEvent); 1391} catch (err) { 1392 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1393} 1394``` 1395 1396 1397## BondStateParam 1398 1399描述配对状态参数。 1400 1401**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1402 1403| 名称 | 类型 | 可读 | 可写 | 说明 | 1404| -------- | ------ | ---- | ---- | ----------- | 1405| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 1406| state | BondState | 是 | 否 | 表示配对设备的状态。 | 1407| cause<sup>12+</sup>| [UnbondCause](#unbondcause12) | 是 | 否 | 表示配对失败的原因。| 1408 1409 1410## PinRequiredParam 1411 1412描述配对请求参数。 1413 1414**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1415 1416| 名称 | 类型 | 可读 | 可写 | 说明 | 1417| -------- | ------ | ---- | ---- | ----------- | 1418| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 1419| pinCode | string | 是 | 否 | 表示要配对的密钥。 | 1420 1421 1422 1423## DeviceClass 1424 1425描述蓝牙设备的类别。 1426 1427**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1428 1429| 名称 | 类型 | 可读 | 可写 | 说明 | 1430| --------------- | ----------------------------------- | ---- | ---- | ---------------- | 1431| majorClass | [MajorClass](js-apis-bluetooth-constant.md#majorclass) | 是 | 否 | 表示蓝牙设备主要类别的枚举。 | 1432| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 是 | 否 | 表示主要次要蓝牙设备类别的枚举。 | 1433| classOfDevice | number | 是 | 否 | 表示设备类别。 | 1434 1435 1436## BatteryInfo<sup>12+</sup> 1437 1438描述电量信息的内容。 1439 1440**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1441 1442| 名称 | 类型 | 可读 | 可写 | 说明 | 1443| -------- | ------ | ---- | ---- | ----------- | 1444| batteryLevel | number | 是 | 否 | 表示远端设备的电量值，如果值为-1，表示没有电量信息。 | 1445| leftEarBatteryLevel | number | 是 | 否 | 表示左侧耳机的电量值，如果值为-1，表示没有电量信息。 | 1446| leftEarChargeState | [DeviceChargeState](#devicechargestate12) | 是 | 否 | 表示左侧耳机的充电状态。 | 1447| rightEarBatteryLevel | number | 是 | 否 | 表示右侧耳机的电量值，如果值为-1，表示没有电量信息。 | 1448| rightEarChargeState | [DeviceChargeState](#devicechargestate12) | 是 | 否 | 表示右侧耳机的充电状态。 | 1449| boxBatteryLevel | number | 是 | 否 | 表示耳机仓的电量值，如果值为-1，表示没有电量信息。 | 1450| boxChargeState | [DeviceChargeState](#devicechargestate12) | 是 | 否 | 表示耳机仓的充电状态。 | 1451 1452 1453## BluetoothTransport 1454 1455枚举，表示设备类型。例如传统蓝牙设备或低功耗蓝牙设备，支持双模默认使用TRANSPORT_BR_EDR。 1456 1457**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1458 1459| 名称 | 值 | 说明 | 1460| -------------------------------- | ------ | --------------- | 1461| TRANSPORT_BR_EDR | 0 | 表示传统蓝牙(BR/EDR)设备。 | 1462| TRANSPORT_LE | 1 | 表示低功耗蓝牙(BLE)设备。 | 1463 1464 1465## ScanMode 1466 1467枚举，扫描模式。 1468 1469**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1470 1471| 名称 | 值 | 说明 | 1472| ---------------------------------------- | ---- | --------------- | 1473| SCAN_MODE_NONE | 0 | 没有扫描模式。 | 1474| SCAN_MODE_CONNECTABLE | 1 | 可连接扫描模式。 | 1475| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | general发现模式。 | 1476| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | limited发现模式。 | 1477| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | 可连接general发现模式。 | 1478| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | 可连接limited发现模式。 | 1479 1480 1481## BondState 1482 1483枚举，配对状态。 1484 1485**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1486 1487**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1488 1489| 名称 | 值 | 说明 | 1490| ------------------ | ---- | ------ | 1491| BOND_STATE_INVALID | 0 | 无效的配对。 | 1492| BOND_STATE_BONDING | 1 | 正在配对。 | 1493| BOND_STATE_BONDED | 2 | 已配对。 | 1494 1495 1496## UnbondCause<sup>12+</sup> 1497 1498枚举，配对失败原因。 1499 1500**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1501 1502| 名称 | 值 | 说明 | 1503| ------------------ | ---- | ------ | 1504| USER_REMOVED | 0 | 用户主动移除设备。| 1505| REMOTE_DEVICE_DOWN | 1 | 远端设备关闭。| 1506| AUTH_FAILURE | 2 | PIN码错误。| 1507| AUTH_REJECTED | 3 | 远端设备鉴权拒绝。| 1508| INTERNAL_ERROR | 4 | 内部错误。| 1509 1510 1511## DeviceChargeState<sup>12+</sup> 1512 1513枚举，表示充电状态。 1514 1515**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1516 1517| 名称 | 值 | 说明 | 1518| ------------------ | ---- | ------ | 1519| DEVICE_NORMAL_CHARGE_NOT_CHARGED | 0 | 未充电，不支持超级充电。| 1520| DEVICE_NORMAL_CHARGE_IN_CHARGING | 1 | 正在充电，不支持超级充电。| 1521| DEVICE_SUPER_CHARGE_NOT_CHARGED | 2 | 未充电，支持超级充电。| 1522| DEVICE_SUPER_CHARGE_IN_CHARGING | 3 | 正在充电，支持超级充电。|