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