1# @ohos.bluetooth.connection (蓝牙connection模块) 2 3connection模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10 11## 导入模块 12 13```js 14import connection from '@ohos.bluetooth.connection'; 15``` 16 17 18## connection.pairDevice 19 20pairDevice(deviceId: string, callback: AsyncCallback<void>): void 21 22发起蓝牙配对。 23 24**需要权限**：ohos.permission.ACCESS_BLUETOOTH 25 26**系统能力**：SystemCapability.Communication.Bluetooth.Core。 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | ------ | ---- | ----------------------------------- | 32| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 33| callback | AsyncCallback<void> | 是 | 回调函数。当配对成功，err为undefined，否则为错误对象。 | 34 35**错误码**： 36 37以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 38 39| 错误码ID | 错误信息 | 40| -------- | ---------------------------- | 41|2900001 | Service stopped. | 42|2900003 | Bluetooth switch is off. | 43|2900099 | Operation failed. | 44 45**示例：** 46 47```js 48import { BusinessError } from '@ohos.base'; 49try { 50 // 实际的地址可由扫描流程获取 51 connection.pairDevice('XX:XX:XX:XX:XX:XX'); 52} catch (err) { 53 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 54} 55``` 56 57 58## connection.pairDevice 59 60pairDevice(deviceId: string): Promise<void> 61 62发起蓝牙配对。 63 64**需要权限**：ohos.permission.ACCESS_BLUETOOTH 65 66**系统能力**：SystemCapability.Communication.Bluetooth.Core。 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| -------- | ------ | ---- | ----------------------------------- | 72| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 73 74**返回值：** 75 76| 类型 | 说明 | 77| ------------------- | ------------- | 78| Promise<void> | 返回promise对象。 | 79 80**错误码**： 81 82以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 83 84| 错误码ID | 错误信息 | 85| -------- | ---------------------------- | 86|2900001 | Service stopped. | 87|2900003 | Bluetooth switch is off. | 88|2900099 | Operation failed. | 89 90**示例：** 91 92```js 93import { BusinessError } from '@ohos.base'; 94try { 95 // 实际的地址可由扫描流程获取 96 connection.pairDevice('XX:XX:XX:XX:XX:XX'); 97} catch (err) { 98 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 99} 100``` 101 102 103## connection.getRemoteDeviceName 104 105getRemoteDeviceName(deviceId: string): string 106 107获取对端蓝牙设备的名称。 108 109**需要权限**：ohos.permission.ACCESS_BLUETOOTH 110 111**系统能力**：SystemCapability.Communication.Bluetooth.Core。 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| -------- | ------ | ---- | --------------------------------- | 117| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 118 119**返回值：** 120 121| 类型 | 说明 | 122| ------ | ------------- | 123| string | 以字符串格式返回设备名称。 | 124 125**错误码**： 126 127以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 128 129| 错误码ID | 错误信息 | 130| -------- | ---------------------------- | 131|2900001 | Service stopped. | 132|2900003 | Bluetooth switch is off. | 133|2900099 | Operation failed. | 134 135**示例：** 136 137```js 138import { BusinessError } from '@ohos.base'; 139try { 140 let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX'); 141} catch (err) { 142 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 143} 144``` 145 146 147## connection.getRemoteDeviceClass 148 149getRemoteDeviceClass(deviceId: string): DeviceClass 150 151获取对端蓝牙设备的类别。 152 153**需要权限**：ohos.permission.ACCESS_BLUETOOTH 154 155**系统能力**：SystemCapability.Communication.Bluetooth.Core。 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| -------- | ------ | ---- | --------------------------------- | 161| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 162 163**返回值：** 164 165| 类型 | 说明 | 166| --------------------------- | -------- | 167| [DeviceClass](#deviceclass) | 远程设备的类别。 | 168 169**错误码**： 170 171以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 172 173| 错误码ID | 错误信息 | 174| -------- | ---------------------------- | 175|2900001 | Service stopped. | 176|2900003 | Bluetooth switch is off. | 177|2900099 | Operation failed. | 178 179**示例：** 180 181```js 182import { BusinessError } from '@ohos.base'; 183try { 184 let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX'); 185} catch (err) { 186 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 187} 188``` 189 190 191## connection.getLocalName 192 193getLocalName(): string 194 195获取蓝牙本地设备名称。 196 197**需要权限**：ohos.permission.ACCESS_BLUETOOTH 198 199**系统能力**：SystemCapability.Communication.Bluetooth.Core。 200 201**返回值：** 202 203| 类型 | 说明 | 204| ------ | --------- | 205| string | 蓝牙本地设备名称。 | 206 207**错误码**： 208 209以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 210 211| 错误码ID | 错误信息 | 212| -------- | ---------------------------- | 213|2900001 | Service stopped. | 214|2900099 | Operation failed. | 215 216**示例：** 217 218```js 219import { BusinessError } from '@ohos.base'; 220try { 221 let localName: string = connection.getLocalName(); 222} catch (err) { 223 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 224} 225``` 226 227 228## connection.getPairedDevices 229 230getPairedDevices(): Array<string> 231 232获取蓝牙配对列表。 233 234**需要权限**：ohos.permission.ACCESS_BLUETOOTH 235 236**系统能力**：SystemCapability.Communication.Bluetooth.Core。 237 238**返回值：** 239 240| 类型 | 说明 | 241| ------------------- | ------------- | 242| Array<string> | 已配对蓝牙设备的地址列表。 | 243 244**错误码**： 245 246以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 247 248| 错误码ID | 错误信息 | 249| -------- | ---------------------------- | 250|2900001 | Service stopped. | 251|2900003 | Bluetooth switch is off. | 252|2900099 | Operation failed. | 253 254**示例：** 255 256```js 257import { BusinessError } from '@ohos.base'; 258try { 259 let devices: Array<string> = connection.getPairedDevices(); 260} catch (err) { 261 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 262} 263``` 264 265 266## connection.getPairState<sup>11+</sup> 267 268getPairState(deviceId: string): BondState 269 270获取蓝牙配对状态。 271 272**需要权限**：ohos.permission.ACCESS_BLUETOOTH 273 274**系统能力**：SystemCapability.Communication.Bluetooth.Core。 275 276**参数：** 277 278| 参数名 | 类型 | 必填 | 说明 | 279| -------- | ------ | ---- | --------------------------------- | 280| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 281 282**返回值：** 283 284| 类型 | 说明 | 285| --------------------------- | -------- | 286| [BondState](#bondstate) | 表示设备的蓝牙配对状态。 | 287 288**错误码**： 289 290以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 291 292| 错误码ID | 错误信息 | 293| -------- | ---------------------------- | 294|2900001 | Service stopped. | 295|2900003 | Bluetooth switch is off. | 296|2900099 | Operation failed. | 297 298**示例：** 299 300```js 301import { BusinessError } from '@ohos.base'; 302try { 303 let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX"); 304 console.log('getPairState: ' + res); 305} catch (err) { 306 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 307} 308``` 309 310 311## connection.getProfileConnectionState 312 313getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState 314 315获取蓝牙Profile的连接状态，其中ProfileId为可选参数。如果携带ProfileId，则返回的是当前Profile的连接状态。如果未携带ProfileId，任一Profile已连接则返回[STATE_CONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)，否则返回[STATE_DISCONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate)。 316 317**需要权限**：ohos.permission.ACCESS_BLUETOOTH 318 319**系统能力**：SystemCapability.Communication.Bluetooth.Core。 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| --------- | --------- | ---- | ------------------------------------- | 325| ProfileId | [profileId](js-apis-bluetooth-constant.md#profileid) | 否 | 表示profile的枚举值，例如：PROFILE_A2DP_SOURCE。 | 326 327**返回值：** 328 329| 类型 | 说明 | 330| ------------------------------------------------- | ------------------- | 331| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | profile的连接状态。 | 332 333**错误码**： 334 335以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 336 337| 错误码ID | 错误信息 | 338| -------- | ---------------------------- | 339|2900001 | Service stopped. | 340|2900003 | Bluetooth switch is off. | 341|2900004 | Profile is not supported. | 342|2900099 | Operation failed. | 343 344**示例：** 345 346```js 347import { BusinessError } from '@ohos.base'; 348import constant from '@ohos.bluetooth.constant'; 349try { 350 let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE); 351} catch (err) { 352 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 353} 354``` 355 356 357## connection.setDevicePairingConfirmation 358 359setDevicePairingConfirmation(deviceId: string, accept: boolean): void 360 361设置设备配对请求确认。 362 363**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 364 365**系统能力**：SystemCapability.Communication.Bluetooth.Core。 366 367**参数：** 368 369| 参数名 | 类型 | 必填 | 说明 | 370| ------ | ------- | ---- | -------------------------------- | 371| deviceId | string | 是 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 372| accept | boolean | 是 | 接受配对请求设置为true，否则设置为false。 | 373 374**错误码**： 375 376以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 377 378| 错误码ID | 错误信息 | 379| -------- | ---------------------------- | 380|2900001 | Service stopped. | 381|2900003 | Bluetooth switch is off. | 382|2900099 | Operation failed. | 383 384**示例：** 385 386```js 387import { BusinessError } from '@ohos.base'; 388// 订阅“pinRequired”配对请求事件，收到远端配对请求后设置配对确认 389function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data为配对请求的入参，配对请求参数 390 console.info('pin required = '+ JSON.stringify(data)); 391 connection.setDevicePairingConfirmation(data.deviceId, true); 392} 393try { 394 connection.on('pinRequired', onReceivePinRequiredEvent); 395} catch (err) { 396 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 397} 398``` 399 400 401## connection.setDevicePinCode 402 403setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback<void>): void 404 405当蓝牙配对类型PinType为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 406 407**需要权限**：ohos.permission.ACCESS_BLUETOOTH 408 409**系统能力**：SystemCapability.Communication.Bluetooth.Core。 410 411**参数：** 412 413| 参数名 | 类型 | 必填 | 说明 | 414| ------ | ------- | ---- | -------------------------------- | 415| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 416| code | string | 是 | 用户输入的PIN码。 | 417| callback | AsyncCallback<void> | 是 | 回调函数，当设置PinCode成功，err为undefined，否则为错误对象。 | 418 419**错误码**： 420 421以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 422 423| 错误码ID | 错误信息 | 424| -------- | ---------------------------- | 425|2900001 | Service stopped. | 426|2900003 | Bluetooth switch is off. | 427|2900099 | Operation failed. | 428 429**示例：** 430 431```js 432import { BusinessError } from '@ohos.base'; 433//callback 434try { 435 connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => { 436 console.info('setDevicePinCode,device name err:' + JSON.stringify(err)); 437 }); 438} catch (err) { 439 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 440} 441``` 442 443 444## connection.setDevicePinCode 445 446setDevicePinCode(deviceId: string, code: string): Promise<void> 447 448当蓝牙配对类型PinType为PIN_TYPE_ENTER_PIN_CODE或PIN_TYPE_PIN_16_DIGITS时调用此接口，请求用户输入PIN码。 449 450**需要权限**：ohos.permission.ACCESS_BLUETOOTH 451 452**系统能力**：SystemCapability.Communication.Bluetooth.Core。 453 454**参数：** 455 456| 参数名 | 类型 | 必填 | 说明 | 457| ------ | ------- | ---- | -------------------------------- | 458| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 459| code | string | 是 | 用户输入的PIN码。 | 460 461**返回值：** 462 463| 类型 | 说明 | 464| ------------------- | ------------- | 465| Promise<void> | 返回promise对象。 | 466 467**错误码**： 468 469以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 470 471| 错误码ID | 错误信息 | 472| -------- | ---------------------------- | 473|2900001 | Service stopped. | 474|2900003 | Bluetooth switch is off. | 475|2900099 | Operation failed. | 476 477**示例：** 478 479```js 480import { BusinessError } from '@ohos.base'; 481//promise 482try { 483 connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => { 484 console.info('setDevicePinCode'); 485 }, (error: BusinessError) => { 486 console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message); 487 }) 488 489} catch (err) { 490 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 491} 492``` 493 494 495## connection.setLocalName 496 497setLocalName(name: string): void 498 499设置蓝牙本地设备名称。 500 501**需要权限**：ohos.permission.ACCESS_BLUETOOTH 502 503**系统能力**：SystemCapability.Communication.Bluetooth.Core。 504 505**参数：** 506 507| 参数名 | 类型 | 必填 | 说明 | 508| ---- | ------ | ---- | --------------------- | 509| name | string | 是 | 要设置的蓝牙名称，最大长度为248字节数。 | 510 511**错误码**： 512 513以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 514 515| 错误码ID | 错误信息 | 516| -------- | ---------------------------- | 517|2900001 | Service stopped. | 518|2900003 | Bluetooth switch is off. | 519|2900099 | Operation failed. | 520 521**示例：** 522 523```js 524import { BusinessError } from '@ohos.base'; 525try { 526 connection.setLocalName('device_name'); 527} catch (err) { 528 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 529} 530``` 531 532 533## connection.setBluetoothScanMode 534 535setBluetoothScanMode(mode: ScanMode, duration: number): void 536 537设置蓝牙扫描模式，可以被远端设备发现。 538 539**需要权限**：ohos.permission.ACCESS_BLUETOOTH 540 541**系统能力**：SystemCapability.Communication.Bluetooth.Core。 542 543**参数：** 544 545| 参数名 | 类型 | 必填 | 说明 | 546| -------- | --------------------- | ---- | ---------------------------- | 547| mode | [ScanMode](#scanmode) | 是 | 蓝牙扫描模式。 | 548| duration | number | 是 | 设备可被发现的持续时间，单位为毫秒；设置为0则持续可发现。 | 549 550**错误码**： 551 552以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 553 554| 错误码ID | 错误信息 | 555| -------- | ---------------------------- | 556|2900001 | Service stopped. | 557|2900003 | Bluetooth switch is off. | 558|2900099 | Operation failed. | 559 560**示例：** 561 562```js 563import { BusinessError } from '@ohos.base'; 564try { 565 // 设置为可连接可发现才可被远端设备扫描到，可以连接。 566 connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100); 567} catch (err) { 568 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 569} 570``` 571 572 573## connection.getBluetoothScanMode 574 575getBluetoothScanMode(): ScanMode 576 577获取蓝牙扫描模式。 578 579**需要权限**：ohos.permission.ACCESS_BLUETOOTH 580 581**系统能力**：SystemCapability.Communication.Bluetooth.Core。 582 583**返回值：** 584 585| 类型 | 说明 | 586| --------------------- | ------- | 587| [ScanMode](#scanmode) | 蓝牙扫描模式。 | 588 589**错误码**： 590 591以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 592 593| 错误码ID | 错误信息 | 594| -------- | ---------------------------- | 595|2900001 | Service stopped. | 596|2900003 | Bluetooth switch is off. | 597|2900099 | Operation failed. | 598 599**示例：** 600 601```js 602import { BusinessError } from '@ohos.base'; 603try { 604 let scanMode: connection.ScanMode = connection.getBluetoothScanMode(); 605} catch (err) { 606 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 607} 608``` 609 610 611## connection.startBluetoothDiscovery 612 613startBluetoothDiscovery(): void 614 615开启蓝牙扫描，可以发现远端设备。 616 617**需要权限**：ohos.permission.ACCESS_BLUETOOTH 618 619**系统能力**：SystemCapability.Communication.Bluetooth.Core。 620 621**错误码**： 622 623以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 624 625| 错误码ID | 错误信息 | 626| -------- | ---------------------------- | 627|2900001 | Service stopped. | 628|2900003 | Bluetooth switch is off. | 629|2900099 | Operation failed. | 630 631**示例：** 632 633```js 634import { BusinessError } from '@ohos.base'; 635function onReceiveEvent(data: Array<string>) { 636 console.log('data length' + data.length); 637} 638try { 639 connection.on('bluetoothDeviceFind', onReceiveEvent); 640 connection.startBluetoothDiscovery(); 641} catch (err) { 642 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 643} 644``` 645 646 647## connection.stopBluetoothDiscovery 648 649stopBluetoothDiscovery(): void 650 651关闭蓝牙扫描。 652 653**需要权限**：ohos.permission.ACCESS_BLUETOOTH 654 655**系统能力**：SystemCapability.Communication.Bluetooth.Core。 656 657**错误码**： 658 659以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 660 661| 错误码ID | 错误信息 | 662| -------- | ---------------------------- | 663|2900001 | Service stopped. | 664|2900003 | Bluetooth switch is off. | 665|2900099 | Operation failed. | 666 667**示例：** 668 669```js 670import { BusinessError } from '@ohos.base'; 671try { 672 connection.stopBluetoothDiscovery(); 673} catch (err) { 674 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 675} 676``` 677 678 679## connection.isBluetoothDiscovering<sup>11+</sup> 680 681isBluetoothDiscovering(): boolean 682 683查询设备的蓝牙发现状态。 684 685**需要权限**：ohos.permission.ACCESS_BLUETOOTH 686 687**系统能力**：SystemCapability.Communication.Bluetooth.Core。 688 689**返回值：** 690 691| 类型 | 说明 | 692| ------------------- | ------------- | 693| boolean | 设备已开启蓝牙发现为true，否则为false。 | 694 695**错误码**： 696 697以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 698 699| 错误码ID | 错误信息 | 700| -------- | ---------------------------- | 701|2900001 | Service stopped. | 702|2900003 | Bluetooth switch is off. | 703|2900099 | Operation failed. | 704 705**示例：** 706 707```js 708import { BusinessError } from '@ohos.base'; 709try { 710 let res: boolean = connection.isBluetoothDiscovering(); 711 console.log('isBluetoothDiscovering: ' + res); 712} catch (err) { 713 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 714} 715``` 716 717 718## connection.on('bluetoothDeviceFind') 719 720on(type: 'bluetoothDeviceFind', callback: Callback<Array<string>>): void 721 722订阅蓝牙设备发现上报事件。 723 724**需要权限**：ohos.permission.ACCESS_BLUETOOTH 725 726**系统能力**：SystemCapability.Communication.Bluetooth.Core。 727 728**参数：** 729 730| 参数名 | 类型 | 必填 | 说明 | 731| -------- | ----------------------------------- | ---- | -------------------------------------- | 732| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | 733| callback | Callback<Array<string>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 734 735**错误码**： 736 737以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 738 739| 错误码ID | 错误信息 | 740| -------- | ---------------------------- | 741|2900099 | Operation failed. | 742 743**示例：** 744 745```js 746import { BusinessError } from '@ohos.base'; 747function onReceiveEvent(data: Array<string>) { // data为蓝牙设备地址集合 748 console.info('bluetooth device find = '+ JSON.stringify(data)); 749} 750try { 751 connection.on('bluetoothDeviceFind', onReceiveEvent); 752} catch (err) { 753 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 754} 755``` 756 757 758## connection.off('bluetoothDeviceFind') 759 760off(type: 'bluetoothDeviceFind', callback?: Callback<Array<string>>): void 761 762取消订阅蓝牙设备发现上报事件。 763 764**需要权限**：ohos.permission.ACCESS_BLUETOOTH 765 766**系统能力**：SystemCapability.Communication.Bluetooth.Core。 767 768**参数：** 769 770| 参数名 | 类型 | 必填 | 说明 | 771| -------- | ----------------------------------- | ---- | ---------------------------------------- | 772| type | string | 是 | 填写"bluetoothDeviceFind"字符串，表示蓝牙设备发现事件。 | 773| callback | Callback<Array<string>> | 否 | 表示取消订阅蓝牙设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 774 775**错误码**： 776 777以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 778 779| 错误码ID | 错误信息 | 780| -------- | ---------------------------- | 781|2900099 | Operation failed. | 782 783**示例：** 784 785```js 786import { BusinessError } from '@ohos.base'; 787function onReceiveEvent(data: Array<string>) { 788 console.info('bluetooth device find = '+ JSON.stringify(data)); 789} 790try { 791 connection.on('bluetoothDeviceFind', onReceiveEvent); 792 connection.off('bluetoothDeviceFind', onReceiveEvent); 793} catch (err) { 794 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 795} 796``` 797 798 799## connection.on('bondStateChange') 800 801on(type: 'bondStateChange', callback: Callback<BondStateParam>): void 802 803订阅蓝牙配对状态改变事件。 804 805**需要权限**：ohos.permission.ACCESS_BLUETOOTH 806 807**系统能力**：SystemCapability.Communication.Bluetooth.Core。 808 809**参数：** 810 811| 参数名 | 类型 | 必填 | 说明 | 812| -------- | ---------------------------------------- | ---- | ------------------------------------ | 813| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | 814| callback | Callback<[BondStateParam](#bondstateparam)> | 是 | 表示回调函数的入参，配对的状态。回调函数由用户创建通过该接口注册。 | 815 816**错误码**： 817 818以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 819 820| 错误码ID | 错误信息 | 821| -------- | ---------------------------- | 822|2900099 | Operation failed. | 823 824**示例：** 825 826```js 827import { BusinessError } from '@ohos.base'; 828function onReceiveEvent(data: connection.BondStateParam) { // data为回调函数入参，表示配对的状态 829 console.info('pair state = '+ JSON.stringify(data)); 830} 831try { 832 connection.on('bondStateChange', onReceiveEvent); 833} catch (err) { 834 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 835} 836``` 837 838 839## connection.off('bondStateChange') 840 841off(type: 'bondStateChange', callback?: Callback<BondStateParam>): void 842 843取消订阅蓝牙配对状态改变事件。 844 845**需要权限**：ohos.permission.ACCESS_BLUETOOTH 846 847**系统能力**：SystemCapability.Communication.Bluetooth.Core。 848 849**参数：** 850 851| 参数名 | 类型 | 必填 | 说明 | 852| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 853| type | string | 是 | 填写"bondStateChange"字符串，表示蓝牙配对状态改变事件。 | 854| callback | Callback<[BondStateParam](#bondstateparam)> | 否 | 表示取消订阅蓝牙配对状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 | 855 856**错误码**： 857 858以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 859 860| 错误码ID | 错误信息 | 861| -------- | ---------------------------- | 862|2900099 | Operation failed. | 863 864**示例：** 865 866```js 867import { BusinessError } from '@ohos.base'; 868function onReceiveEvent(data: connection.BondStateParam) { 869 console.info('bond state = '+ JSON.stringify(data)); 870} 871try { 872 connection.on('bondStateChange', onReceiveEvent); 873 connection.off('bondStateChange', onReceiveEvent); 874} catch (err) { 875 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 876} 877``` 878 879 880## connection.on('pinRequired') 881 882on(type: 'pinRequired', callback: Callback<PinRequiredParam>): void 883 884订阅远端蓝牙设备的配对请求事件。 885 886**需要权限**：ohos.permission.ACCESS_BLUETOOTH 887 888**系统能力**：SystemCapability.Communication.Bluetooth.Core。 889 890**参数：** 891 892| 参数名 | 类型 | 必填 | 说明 | 893| -------- | ---------------------------------------- | ---- | -------------------------------- | 894| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | 895| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 是 | 表示回调函数的入参，配对请求。回调函数由用户创建通过该接口注册。 | 896 897**错误码**： 898 899以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 900 901| 错误码ID | 错误信息 | 902| -------- | ---------------------------- | 903|2900099 | Operation failed. | 904 905**示例：** 906 907```js 908import { BusinessError } from '@ohos.base'; 909function onReceiveEvent(data: connection.PinRequiredParam) { // data为配对请求参数 910 console.info('pin required = '+ JSON.stringify(data)); 911} 912try { 913 connection.on('pinRequired', onReceiveEvent); 914} catch (err) { 915 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 916} 917``` 918 919 920## connection.off('pinRequired') 921 922off(type: 'pinRequired', callback?: Callback<PinRequiredParam>): void 923 924取消订阅远端蓝牙设备的配对请求事件。 925 926**需要权限**：ohos.permission.ACCESS_BLUETOOTH 927 928**系统能力**：SystemCapability.Communication.Bluetooth.Core。 929 930**参数：** 931 932| 参数名 | 类型 | 必填 | 说明 | 933| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 934| type | string | 是 | 填写"pinRequired"字符串，表示配对请求事件。 | 935| callback | Callback<[PinRequiredParam](#pinrequiredparam)> | 否 | 表示取消订阅蓝牙配对请求事件上报，入参为配对请求参数。不填该参数则取消订阅该type对应的所有回调。 | 936 937**错误码**： 938 939以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 940 941| 错误码ID | 错误信息 | 942| -------- | ---------------------------- | 943|2900099 | Operation failed. | 944 945**示例：** 946 947```js 948import { BusinessError } from '@ohos.base'; 949function onReceiveEvent(data: connection.PinRequiredParam) { 950 console.info('pin required = '+ JSON.stringify(data)); 951} 952try { 953 connection.on('pinRequired', onReceiveEvent); 954 connection.off('pinRequired', onReceiveEvent); 955} catch (err) { 956 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 957} 958``` 959 960 961## BondStateParam 962 963描述配对状态参数。 964 965**系统能力**：SystemCapability.Communication.Bluetooth.Core。 966 967| 名称 | 类型 | 可读 | 可写 | 说明 | 968| -------- | ------ | ---- | ---- | ----------- | 969| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 970| state | BondState | 是 | 否 | 表示配对设备的状态。 | 971 972 973## PinRequiredParam 974 975描述配对请求参数。 976 977**系统能力**：SystemCapability.Communication.Bluetooth.Core。 978 979| 名称 | 类型 | 可读 | 可写 | 说明 | 980| -------- | ------ | ---- | ---- | ----------- | 981| deviceId | string | 是 | 否 | 表示要配对的设备ID。 | 982| pinCode | string | 是 | 否 | 表示要配对的密钥。 | 983 984 985 986## DeviceClass 987 988描述蓝牙设备的类别。 989 990**系统能力**：SystemCapability.Communication.Bluetooth.Core。 991 992| 名称 | 类型 | 可读 | 可写 | 说明 | 993| --------------- | ----------------------------------- | ---- | ---- | ---------------- | 994| majorClass | [MajorClass](js-apis-bluetooth-constant.md#majorclass) | 是 | 否 | 表示蓝牙设备主要类别的枚举。 | 995| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | 是 | 否 | 表示主要次要蓝牙设备类别的枚举。 | 996| classOfDevice | number | 是 | 否 | 表示设备类别。 | 997 998 999## BluetoothTransport 1000 1001枚举，表示设备类型。例如传统蓝牙设备或低功耗蓝牙设备，支持双模默认使用TRANSPORT_BR_EDR。 1002 1003**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1004 1005| 名称 | 值 | 说明 | 1006| -------------------------------- | ------ | --------------- | 1007| TRANSPORT_BR_EDR | 0 | 表示传统蓝牙(BR/EDR)设备。 | 1008| TRANSPORT_LE | 1 | 表示低功耗蓝牙(BLE)设备。 | 1009 1010 1011## ScanMode 1012 1013枚举，扫描模式。 1014 1015**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1016 1017| 名称 | 值 | 说明 | 1018| ---------------------------------------- | ---- | --------------- | 1019| SCAN_MODE_NONE | 0 | 没有扫描模式。 | 1020| SCAN_MODE_CONNECTABLE | 1 | 可连接扫描模式。 | 1021| SCAN_MODE_GENERAL_DISCOVERABLE | 2 | general发现模式。 | 1022| SCAN_MODE_LIMITED_DISCOVERABLE | 3 | limited发现模式。 | 1023| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4 | 可连接general发现模式。 | 1024| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5 | 可连接limited发现模式。 | 1025 1026 1027## BondState 1028 1029枚举，配对状态。 1030 1031**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1032 1033| 名称 | 值 | 说明 | 1034| ------------------ | ---- | ------ | 1035| BOND_STATE_INVALID | 0 | 无效的配对。 | 1036| BOND_STATE_BONDING | 1 | 正在配对。 | 1037| BOND_STATE_BONDED | 2 | 已配对。 |