1# @ohos.bluetooth.connection (蓝牙connection模块)(系统接口) 2 3<!--Kit: Connectivity Kit--> 4<!--Subsystem: Communication--> 5<!--Owner: @enjoy_sunshine--> 6<!--Designer: @chengguohong; @tangjia15--> 7<!--Tester: @wangfeng517--> 8<!--Adviser: @zhang_yixin13--> 9 10connection模块提供了对蓝牙操作和管理的方法。 11 12> **说明：** 13> 14> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.bluetooth.connection (蓝牙connection模块)](js-apis-bluetooth-connection.md) 16 17 18## 导入模块 19 20```js 21import { connection } from '@kit.ConnectivityKit'; 22``` 23 24 25## connection.pairCredibleDevice 26 27pairCredibleDevice(deviceId: string, transport: BluetoothTransport, callback: AsyncCallback<void>): void 28 29向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。使用Callback异步回调。 30 31**系统接口**：此接口为系统接口。 32 33**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 34 35**系统能力**：SystemCapability.Communication.Bluetooth.Core 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| -------- | ------ | ---- | ----------------------------------- | 41| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 42| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | 是 | 表示在配对远端设备时使用的传输方式。<br>-若明确使用传统蓝牙（BR/EDR）或者低功耗蓝牙（BLE）方式，则传入TRANSPORT_BR_EDR或TRANSPORT_LE。<br>-若不确定使用哪种传输方式，则传入TRANSPORT_DUAL<sup>20+</sup>或TRANSPORT_UNKNOWN<sup>20+</sup>，蓝牙子系统会决策传输方式。 | 43| callback | AsyncCallback<void> | 是 | 回调函数。当发起配对成功，err为undefined，否则为错误对象。 | 44 45**错误码**： 46 47以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 48 49| 错误码ID | 错误信息 | 50| -------- | ---------------------------- | 51|201 | Permission denied. | 52|202 | Non-system applications are not allowed to use system APIs. | 53|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 54|801 | Capability not supported. | 55|2900001 | Service stopped. | 56|2900003 | Bluetooth disabled. | 57|2900099 | Operation failed. | 58 59**示例：** 60 61```js 62import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 63try { 64 connection.pairCredibleDevice('68:13:24:79:4C:8C', connection.BluetoothTransport 65 .TRANSPORT_BR_EDR, (err: BusinessError) => { 66 if (err) { 67 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 68 return; 69 } 70 console.info('pairCredibleDevice, err: ' + JSON.stringify(err)); 71 }); 72} catch (err) { 73 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 74} 75``` 76 77 78## connection.pairCredibleDevice 79 80pairCredibleDevice(deviceId: string, transport: BluetoothTransport): Promise<void> 81 82向可信的远端设备发起蓝牙配对。通过非蓝牙扫描的方式(例如NFC等)获取到外设的地址，可以通过该接口发起配对。使用Promise异步回调。 83 84**系统接口**：此接口为系统接口。 85 86**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 87 88**系统能力**：SystemCapability.Communication.Bluetooth.Core 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| -------- | ------ | ---- | ----------------------------------- | 94| deviceId | string | 是 | 表示配对的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 95| transport | [BluetoothTransport](js-apis-bluetooth-connection.md#bluetoothtransport) | 是 | 表示在配对远端设备时使用的传输方式。<br>-若明确使用传统蓝牙（BR/EDR）或者低功耗蓝牙（BLE）方式，则传入TRANSPORT_BR_EDR或TRANSPORT_LE。<br>-若不确定使用哪种传输方式，则传入TRANSPORT_DUAL<sup>20+</sup>或TRANSPORT_UNKNOWN<sup>20+</sup>，蓝牙子系统会决策传输方式。 | 96 97**返回值：** 98 99| 类型 | 说明 | 100| ------------------------------------------------- | ------------------- | 101| Promise<void> | 返回promise对象。 | 102 103**错误码**： 104 105以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 106 107| 错误码ID | 错误信息 | 108| -------- | ---------------------------- | 109|201 | Permission denied. | 110|202 | Non-system applications are not allowed to use system APIs. | 111|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 112|801 | Capability not supported. | 113|2900001 | Service stopped. | 114|2900003 | Bluetooth disabled. | 115|2900099 | Operation failed. | 116 117**示例：** 118 119```js 120import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 121try { 122 connection.pairCredibleDevice('68:13:24:79:4C:8C', 0).then(() => { 123 console.info('PairCredibleDevice'); 124 }, (err: BusinessError) => { 125 console.error('PairCredibleDevice:errCode' + err.code + ', errMessage: ' + err.message); 126 }); 127} catch (err) { 128 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 129} 130``` 131 132 133## connection.cancelPairedDevice 134 135cancelPairedDevice(deviceId: string, callback: AsyncCallback<void>): void 136 137删除配对的远程设备。使用Callback异步回调。 138 139**系统接口**：此接口为系统接口。 140 141**需要权限**：ohos.permission.ACCESS_BLUETOOTH 142 143**系统能力**：SystemCapability.Communication.Bluetooth.Core 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| -------- | ------ | ---- | ------------------------------------- | 149| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 150| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | 151 152**错误码**： 153 154以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 155 156| 错误码ID | 错误信息 | 157| -------- | ---------------------------- | 158|201 | Permission denied. | 159|202 | Non-system applications are not allowed to use system APIs. | 160|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 161|801 | Capability not supported. | 162|2900001 | Service stopped. | 163|2900003 | Bluetooth disabled. | 164|2900099 | Operation failed. | 165 166**示例：** 167 168```js 169import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 170// callback 171try { 172 connection.cancelPairedDevice('11:22:33:44:55:66', (err: BusinessError) => { 173 console.info('cancelPairedDevice, device name err:' + JSON.stringify(err)); 174 }); 175} catch (err) { 176 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 177} 178``` 179 180 181## connection.cancelPairedDevice 182 183cancelPairedDevice(deviceId: string): Promise<void> 184 185删除配对的远程设备。使用Promise异步回调。 186 187**系统接口**：此接口为系统接口。 188 189**需要权限**：ohos.permission.ACCESS_BLUETOOTH 190 191**系统能力**：SystemCapability.Communication.Bluetooth.Core 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| -------- | ------ | ---- | ------------------------------------- | 197| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| ------------------- | ------------- | 203| Promise<void> | 返回promise对象。 | 204 205**错误码**： 206 207以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 208 209| 错误码ID | 错误信息 | 210| -------- | ---------------------------- | 211|201 | Permission denied. | 212|202 | Non-system applications are not allowed to use system APIs. | 213|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 214|801 | Capability not supported. | 215|2900001 | Service stopped. | 216|2900003 | Bluetooth disabled. | 217|2900099 | Operation failed. | 218 219**示例：** 220 221```js 222import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 223// promise 224try { 225 connection.cancelPairedDevice('11:22:33:44:55:66').then(() => { 226 console.info('cancelPairedDevice'); 227 }, (error: BusinessError) => { 228 console.error('cancelPairedDevice: errCode:' + error.code + ',errMessage' + error.message); 229 }) 230 231} catch (err) { 232 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 233} 234``` 235 236 237## connection.cancelPairingDevice 238 239cancelPairingDevice(deviceId: string, callback: AsyncCallback<void>): void 240 241删除正在配对中的远程设备。使用Callback异步回调。 242 243**系统接口**：此接口为系统接口。 244 245**需要权限**：ohos.permission.ACCESS_BLUETOOTH 246 247**系统能力**：SystemCapability.Communication.Bluetooth.Core 248 249**参数：** 250 251| 参数名 | 类型 | 必填 | 说明 | 252| -------- | ------ | ---- | ------------------------------------- | 253| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 254| callback | AsyncCallback<void> | 是 | 回调函数。当删除远程配对设备成功，err为undefined，否则为错误对象。 | 255 256**错误码**： 257 258以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 259 260| 错误码ID | 错误信息 | 261| -------- | ---------------------------- | 262|201 | Permission denied. | 263|202 | Non-system applications are not allowed to use system APIs. | 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 connection.cancelPairingDevice('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.cancelPairingDevice 283 284cancelPairingDevice(deviceId: string): Promise<void> 285 286删除正在配对中的远程设备。使用Promise异步回调。 287 288**系统接口**：此接口为系统接口。 289 290**需要权限**：ohos.permission.ACCESS_BLUETOOTH 291 292**系统能力**：SystemCapability.Communication.Bluetooth.Core 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| -------- | ------ | ---- | ------------------------------------- | 298| deviceId | string | 是 | 表示要删除的远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 299 300**返回值：** 301 302| 类型 | 说明 | 303| ------------------- | ------------- | 304| Promise<void> | 返回promise对象。 | 305 306**错误码**： 307 308以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 309 310| 错误码ID | 错误信息 | 311| -------- | ---------------------------- | 312|201 | Permission denied. | 313|202 | Non-system applications are not allowed to use system APIs. | 314|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 315|801 | Capability not supported. | 316|2900001 | Service stopped. | 317|2900003 | Bluetooth disabled. | 318|2900099 | Operation failed. | 319 320**示例：** 321 322```js 323import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 324try { 325 connection.cancelPairingDevice('XX:XX:XX:XX:XX:XX'); 326} catch (err) { 327 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 328} 329``` 330 331 332## connection.getLocalProfileUuids 333 334getLocalProfileUuids(callback: AsyncCallback<Array<ProfileUuids>>): void 335 336获取本地设备的profile UUID。使用Callback异步回调。 337 338**系统接口**：此接口为系统接口。 339 340**需要权限**：ohos.permission.ACCESS_BLUETOOTH 341 342**系统能力**：SystemCapability.Communication.Bluetooth.Core 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| -------- | ------ | ---- | ----------------------------------- | 348| callback | AsyncCallback<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | 是 | 回调函数。当获取UUID成功，err为undefined，否则为错误对象。 | 349 350**错误码**： 351 352以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 353 354| 错误码ID | 错误信息 | 355| -------- | ---------------------------- | 356|201 | Permission denied. | 357|202 | Non-system applications are not allowed to use system APIs. | 358|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 359|801 | Capability not supported. | 360|2900001 | Service stopped. | 361|2900003 | Bluetooth disabled. | 362|2900099 | Operation failed. | 363 364**示例：** 365 366```js 367import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 368try { 369 connection.getLocalProfileUuids((err: BusinessError, data: Array<connection.ProfileUuids>) => { 370 console.info('getLocalProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data)); 371 }); 372} catch (err) { 373 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 374} 375``` 376 377 378## connection.getLocalProfileUuids 379 380getLocalProfileUuids(): Promise<Array<ProfileUuids>> 381 382获取本地设备的profile UUID。使用Promise异步回调。 383 384**系统接口**：此接口为系统接口。 385 386**需要权限**：ohos.permission.ACCESS_BLUETOOTH 387 388**系统能力**：SystemCapability.Communication.Bluetooth.Core 389 390**返回值：** 391 392| 类型 | 说明 | 393| ------------------- | ------------- | 394| Promise<Array<[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)>> | 返回promise对象。 | 395 396**错误码**： 397 398以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 399 400| 错误码ID | 错误信息 | 401| -------- | ---------------------------- | 402|201 | Permission denied. | 403|202 | Non-system applications are not allowed to use system APIs. | 404|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 405|801 | Capability not supported. | 406|2900001 | Service stopped. | 407|2900003 | Bluetooth disabled. | 408|2900099 | Operation failed. | 409 410**示例：** 411 412```js 413import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 414try { 415 connection.getLocalProfileUuids().then(() => { 416 console.info('getLocalProfileUuids'); 417 }, (err: BusinessError) => { 418 console.error('getLocalProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 419 }); 420} catch (err) { 421 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 422} 423``` 424 425 426## connection.disconnectAllowedProfiles<sup>11+</sup> 427 428disconnectAllowedProfiles(deviceId: string, callback: AsyncCallback<void>): void 429 430断开远端设备所有连接的profiles。使用Callback异步回调。 431 432**系统接口**：此接口为系统接口。 433 434**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 435 436**系统能力**：SystemCapability.Communication.Bluetooth.Core 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441| -------- | ------ | ---- | ----------------------------------- | 442| deviceId | string | 是 | 表示断开的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 443| callback | AsyncCallback<void> | 是 | 以callback形式异步返回结果。当发起断开成功，err为undefined，否则为错误对象。 | 444 445**错误码**： 446 447以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 448 449| 错误码ID | 错误信息 | 450| -------- | ---------------------------- | 451|201 | Permission denied. | 452|202 | Non-system applications are not allowed to use system APIs. | 453|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 454|801 | Capability not supported. | 455|2900001 | Service stopped. | 456|2900003 | Bluetooth disabled. | 457|2900099 | Operation failed. | 458 459**示例：** 460 461```js 462import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 463try { 464 connection.disconnectAllowedProfiles('68:13:24:79:4C:8C', (err: BusinessError) => { 465 if (err) { 466 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 467 return; 468 } 469 console.info('disconnectAllowedProfiles, err: ' + JSON.stringify(err)); 470 }); 471} catch (err) { 472 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 473} 474``` 475 476 477## connection.disconnectAllowedProfiles<sup>11+</sup> 478 479disconnectAllowedProfiles(deviceId: string): Promise<void> 480 481断开远端设备所有连接的profiles。使用Promise异步回调。 482 483**系统接口**：此接口为系统接口。 484 485**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 486 487**系统能力**：SystemCapability.Communication.Bluetooth.Core 488 489**参数：** 490 491| 参数名 | 类型 | 必填 | 说明 | 492| -------- | ------ | ---- | ----------------------------------- | 493| deviceId | string | 是 | 表示断开的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 494 495**返回值：** 496 497| 类型 | 说明 | 498| ------------------------------------------------- | ------------------- | 499| Promise<void> | 以Promise形式返回断开profiles的结果，返回true为成功，false为失败。 | 500 501**错误码**： 502 503以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 504 505| 错误码ID | 错误信息 | 506| -------- | ---------------------------- | 507|201 | Permission denied. | 508|202 | Non-system applications are not allowed to use system APIs. | 509|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 510|801 | Capability not supported. | 511|2900001 | Service stopped. | 512|2900003 | Bluetooth disabled. | 513|2900099 | Operation failed. | 514 515**示例：** 516 517```js 518import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 519try { 520 connection.disconnectAllowedProfiles('68:13:24:79:4C:8C').then(() => { 521 console.info('disconnectAllowedProfiles'); 522 }, (err: BusinessError) => { 523 console.error('disconnectAllowedProfiles:errCode' + err.code + ', errMessage: ' + err.message); 524 }); 525} catch (err) { 526 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 527} 528``` 529 530 531## connection.getRemoteProductId<sup>11+</sup> 532 533getRemoteProductId(deviceId: string): string 534 535获取对端蓝牙设备的Product ID。从API16开始不再校验ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH权限。 536 537**系统接口**：此接口为系统接口。 538 539**系统能力**：SystemCapability.Communication.Bluetooth.Core 540 541**参数：** 542 543| 参数名 | 类型 | 必填 | 说明 | 544| -------- | ------ | ---- | --------------------------------- | 545| deviceId | string | 是 | 表示远程设备的地址，例如："XX:XX:XX:XX:XX:XX"。 | 546 547**返回值：** 548 549| 类型 | 说明 | 550| ------ | ------------- | 551| string | 以字符串格式返回设备Product ID。 | 552 553**错误码**： 554 555以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 556 557| 错误码ID | 错误信息 | 558| -------- | ---------------------------- | 559|202 | Non-system applications are not allowed to use system APIs. | 560|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 561|801 | Capability not supported. | 562|2900001 | Service stopped. | 563|2900003 | Bluetooth disabled. | 564|2900099 | Operation failed. | 565 566**示例：** 567 568```js 569try { 570 let remoteDeviceProductId = connection.getRemoteProductId('XX:XX:XX:XX:XX:XX'); 571} catch (err) { 572 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 573} 574``` 575 576## connection.setRemoteDeviceType<sup>12+</sup> 577 578setRemoteDeviceType(deviceId: string, type: DeviceType): Promise<void> 579 580设置蓝牙远端设备自定义类型。使用Promise异步回调。 581 582**系统接口**：此接口为系统接口。 583 584**需要权限**：ohos.permission.ACCESS_BLUETOOTH 585 586**系统能力**：SystemCapability.Communication.Bluetooth.Core 587 588**参数：** 589 590| 参数名 | 类型 | 必填 | 说明 | 591| ------ | ------- | ---- | -------------------------------- | 592| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 593| type | [DeviceType](#devicetype12) | 是 | 表示设备类型。 | 594 595**返回值：** 596 597| 类型 | 说明 | 598| ------------------- | ------------- | 599| Promise<void> | 以Promise形式返回设置蓝牙远端设备类型的结果，设置失败时返回错误码信息。 | 600 601**错误码**： 602 603以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 604 605| 错误码ID | 错误信息 | 606| -------- | ---------------------------- | 607|201 | Permission denied. | 608|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 609|2900001 | Service stopped. | 610|2900003 | Bluetooth disabled. | 611 612**示例：** 613 614```js 615import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 616// promise 617try { 618 connection.setRemoteDeviceType('11:22:33:44:55:66', connection.DeviceType.DEVICE_TYPE_HEADSET).then(() => { 619 console.info('setRemoteDeviceType success'); 620 }); 621} catch (err) { 622 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 623} 624``` 625 626 627## connection.getRemoteDeviceType<sup>12+</sup> 628 629getRemoteDeviceType(deviceId: string): Promise<DeviceType> 630 631获取蓝牙远端设备自定义类型。使用Promise异步回调。从API18开始不再校验ohos.permission.ACCESS_BLUETOOTH权限。 632 633**系统接口**：此接口为系统接口。 634 635**系统能力**：SystemCapability.Communication.Bluetooth.Core 636 637**参数：** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| ------ | ------- | ---- | -------------------------------- | 641| deviceId | string | 是 | 表示远端设备MAC地址，例如："XX:XX:XX:XX:XX:XX"。 | 642 643**返回值：** 644 645| 类型 | 说明 | 646| ------------------- | ------------- | 647| Promise<[DeviceType](#devicetype12)> | 以Promise形式返回设置蓝牙远端设备类型的结果，返回值为设备类型。 | 648 649**错误码**： 650 651以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 652 653| 错误码ID | 错误信息 | 654| -------- | ---------------------------- | 655|202 | Non-system applications are not allowed to use system APIs. | 656|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 657|2900001 | Service stopped. | 658|2900003 | Bluetooth disabled. | 659 660**示例：** 661 662```js 663import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 664// promise 665try { 666 connection.getRemoteDeviceType('11:22:33:44:55:66').then((data: connection.DeviceType) => { 667 console.info('getRemoteDeviceType success, DeviceType:' + JSON.stringify(data)); 668 }); 669} catch (err) { 670 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 671} 672``` 673 674 675## connection.controlDeviceAction<sup>15+</sup> 676 677controlDeviceAction(controlDeviceActionParams: ControlDeviceActionParams): Promise<void> 678 679查找蓝牙耳机设备时，向耳机发送控制命令。使用Promise异步回调。 680 681**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH（该权限仅系统应用可申请）。 682 683**系统能力**：SystemCapability.Communication.Bluetooth.Core 684 685**参数：** 686 687| 参数名 | 类型 | 必填 | 说明 | 688| ------ | ------- | ---- | -------------------------------- | 689| controlDeviceActionParams<sup>15+</sup> | [ControlDeviceActionParams](#controldeviceactionparams15) | 是 | 控制蓝牙外设的相关信息。 | 690 691**返回值：** 692 693| 类型 | 说明 | 694| ------------------- | ------------- | 695| Promise<void> | 返回promise对象。 | 696 697**错误码**： 698 699以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 700 701| 错误码ID | 错误信息 | 702| -------- | ---------------------------- | 703|201 | Permission denied. | 704|202 | Non-system applications are not allowed to use system APIs. | 705|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 706|801 | Capability not supported. | 707|2900001 | Service stopped. | 708|2900003 | Bluetooth disabled. | 709|2900099 | Operation failed. | 710 711**示例：** 712 713```js 714import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 715try { 716 let controlDeviceActionParams: connection.ControlDeviceActionParams = { 717 deviceId: '40:DC:A5:E5:75:C3', 718 type: connection.ControlType.PLAY, 719 typeValue: connection.ControlTypeValue.ENABLE, 720 controlObject: connection.ControlObject.LEFT_EAR 721 }; 722 connection.controlDeviceAction(controlDeviceActionParams).then(() => { 723 console.info('controlDeviceAction success'); 724 }, (err: BusinessError) => { 725 console.error('controlDeviceAction: errCode' + err.code + ', errMessage: ' + err.message); 726 }); 727} catch (err) { 728 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 729} 730``` 731 732 733## connection.updateCloudBluetoothDevice<sup>15+</sup> 734 735updateCloudBluetoothDevice(trustedPairedDevices: TrustedPairedDevices): Promise<void> 736 737更新云设备到蓝牙设置。使用Promise异步回调。 738 739**系统接口**：此接口为系统接口。 740 741**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.MANAGE_BLUETOOTH 742 743**系统能力**：SystemCapability.Communication.Bluetooth.Core 744 745**参数：** 746 747| 参数名 | 类型 | 必填 | 说明 | 748| ------ | ------- | ---- | -------------------------------- | 749| trustedPairedDevices | [TrustedPairedDevices](#trustedpaireddevices15) | 是 | 表示云设备列表。 | 750 751**返回值：** 752 753| 类型 | 说明 | 754| ------------------- | ------------- | 755| Promise<void> | 以Promise形式返回设置云设备的结果。设置失败时返回错误码信息。 | 756 757**错误码**： 758 759以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 760 761| 错误码ID | 错误信息 | 762| -------- | ---------------------------- | 763|201 | Permission denied. | 764|202 | Non-system applications are not allowed to use system APIs. | 765|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 766|801 | Capability not supported. | 767|2900001 | Service stopped. | 768|2900003 | Bluetooth disabled. | 769|2900099 | Operation failed. | 770 771**示例：** 772 773```js 774import { connection } from '@kit.ConnectivityKit'; 775// promise 776/** 777 * 更新云设备到蓝牙设置项。 778 */ 779const trustPairDeviceArr: connection.TrustedPairedDevice[] = []; 780let descBuffer = new ArrayBuffer(1); 781trustPairDeviceArr.push({ 782 sn: '', 783 deviceType: '', 784 modelId: '', 785 manufactory: '', 786 productId: '', 787 hiLinkVersion: '', 788 macAddress: '11:22:33:44:55:66', 789 serviceType: '', 790 serviceId: '', 791 deviceName: '', 792 uuids: '', 793 bluetoothClass: 0, 794 token: descBuffer, 795 deviceNameTime: 0, 796 secureAdvertisingInfo: descBuffer, 797 pairState: 0 798 }); 799const trustPairDevices: connection.TrustedPairedDevices = { trustedPairedDevices: trustPairDeviceArr }; 800try { 801 connection.updateCloudBluetoothDevice(trustPairDevices) 802 .then(() => { 803 console.info('updateCloudBluetoothDevice success!'); 804 }) 805 .catch((err: BusinessError) => { 806 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 807 }); 808} catch (err) { 809 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 810} 811 812``` 813 814 815## PinRequiredParam 816 817描述配对请求参数。 818 819**系统能力**：SystemCapability.Communication.Bluetooth.Core 820 821| 名称 | 类型 | 只读 | 可选 | 说明 | 822| -------- | ------ | ---- | ---- | ----------- | 823| pinType | [PinType](#pintype) | 否 | 否 | 表示要配对的设备类型。<br/>此接口为系统接口。 | 824 825## ControlDeviceActionParams<sup>15+</sup> 826 827控制命令的配置参数。 828 829**系统能力**：SystemCapability.Communication.Bluetooth.Core 830 831| 名称 | 类型 | 只读 | 可选 | 说明 | 832| -------- | ------ | ---- | ---- | ----------- | 833| deviceId | string | 否 | 否 | 表示要配对的设备ID。 | 834| type | [ControlType](#controltype15) | 否 | 否 | 表示控制类型。 | 835| typeValue | [ControlTypeValue](#controltypevalue15) | 否 | 否 | 表示控制动作。 | 836| controlObject | [ControlObject](#controlobject15) | 否 | 否 | 表示控制对象。| 837 838## PinType 839 840枚举，蓝牙配对类型。 841 842**系统接口：** 此接口为系统接口。 843 844**系统能力**：SystemCapability.Communication.Bluetooth.Core 845 846| 名称 | 值 | 说明 | 847| -------------------------------- | ------ | --------------- | 848| PIN_TYPE_ENTER_PIN_CODE | 0 | 用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 849| PIN_TYPE_ENTER_PASSKEY | 1 | 用户需要输入对端设备上显示的PASSKEY。<br/>此接口为系统接口。 | 850| PIN_TYPE_CONFIRM_PASSKEY | 2 | 用户需要确认本地设备上显示的PASSKEY。<br/>此接口为系统接口。 | 851| PIN_TYPE_NO_PASSKEY_CONSENT | 3 | 无PASSKEY，用户需要接受或拒绝配对请求。<br/>此接口为系统接口。 | 852| PIN_TYPE_NOTIFY_PASSKEY | 4 | 本地设备显示PASSKEY，用户需要在对端设备上输入该PASSKEY。<br/>此接口为系统接口。 | 853| PIN_TYPE_DISPLAY_PIN_CODE | 5 | bluetooth 2.0设备，用户需要输入对端设备上显示的PIN码。<br/>此接口为系统接口。 | 854| PIN_TYPE_OOB_CONSENT | 6 | 用户需要接受或拒绝OOB配对请求。<br/>此接口为系统接口。 | 855| PIN_TYPE_PIN_16_DIGITS | 7 | 用户需要输入对端设备上显示的16位PIN码。<br/>此接口为系统接口。 | 856 857 858 859## DeviceType<sup>12+</sup> 860 861枚举，蓝牙远程设备的自定义类型。 862 863**系统接口：** 此接口为系统接口。 864 865**系统能力**：SystemCapability.Communication.Bluetooth.Core 866 867| 名称 | 值 | 说明 | 868| -------------------------------- | ------ | --------------- | 869| DEVICE_TYPE_DEFAULT<sup>12+</sup> | 0 | 默认设备类型，与原类型一致。<br/>此接口为系统接口。 | 870| DEVICE_TYPE_CAR<sup>12+</sup> | 1 | 汽车。<br/>此接口为系统接口。 | 871| DEVICE_TYPE_HEADSET<sup>12+</sup> | 2 | 耳机。<br/>此接口为系统接口。 | 872| DEVICE_TYPE_HEARING<sup>12+</sup> | 3 | 助听器<br/>此接口为系统接口。 | 873| DEVICE_TYPE_GLASSES<sup>12+</sup> | 4 | 眼镜。<br/>此接口为系统接口。 | 874| DEVICE_TYPE_WATCH<sup>12+</sup> | 5 | 手表。<br/>此接口为系统接口。 | 875| DEVICE_TYPE_SPEAKER<sup>12+</sup> | 6 | 音响。<br/>此接口为系统接口。 | 876| DEVICE_TYPE_OTHERS<sup>12+</sup> | 7 | 其他设备。<br/>此接口为系统接口。 | 877 878 879## BatteryInfo<sup>12+</sup> 880 881描述电量信息的内容。 882 883**系统能力**：SystemCapability.Communication.Bluetooth.Core 884 885| 名称 | 类型 | 只读 | 可选 | 说明 | 886| -------- | ------ | ---- | ---- | ----------- | 887| deviceId | string | 否 | 否 | 表示远端设备的MAC地址。<br/>此接口为系统接口。 | 888 889 890## ControlType<sup>15+</sup> 891 892枚举，控制类型。 893 894**系统能力**：SystemCapability.Communication.Bluetooth.Core 895 896| 名称 | 值 | 说明 | 897| -------------------------------- | ------ | --------------- | 898| PLAY | 0 | 表示控制类型为播放。 | 899| VIBRATE | 1 | 表示控制类型为振动。 | 900| FLASH | 2 | 表示控制类型为闪光。 | 901| LOCK | 3 | 表示控制类型为锁定。 | 902 903 904## ControlTypeValue<sup>15+</sup> 905 906枚举，控制动作。 907 908**系统能力**：SystemCapability.Communication.Bluetooth.Core 909 910| 名称 | 值 | 说明 | 911| ------- | ---- | ---------- | 912| DISABLE | 0 | 表示禁用。 | 913| ENABLE | 1 | 表示使能。 | 914| QUERY | 2 | 表示查询。 | 915 916 917## ControlObject<sup>15+</sup> 918 919枚举，控制对象。 920 921**系统能力**：SystemCapability.Communication.Bluetooth.Core 922 923| 名称 | 值 | 说明 | 924| -------------- | ---- | -------------------- | 925| LEFT_EAR | 0 | 表示控制对象是左耳。 | 926| RIGHT_EAR | 1 | 表示控制对象是右耳。 | 927| LEFT_RIGHT_EAR | 2 | 表示控制对象是双耳。 | 928 929 930## TrustedPairedDevices<sup>15+</sup> 931 932云设备列表。 933 934**系统能力**：SystemCapability.Communication.Bluetooth.Core 935 936| 名称 | 类型 | 只读 | 可选 | 说明 | 937| -------- | ------ | ---- | ---- | ----------- | 938| trustedPairedDevices | Array<[TrustedPairedDevice](#trustedpaireddevice15)> | 否 | 否 | 表示云设备列表。 | 939 940## TrustedPairedDevice<sup>15+</sup> 941 942云设备信息。 943 944**系统能力**：SystemCapability.Communication.Bluetooth.Core。 945 946| 名称 | 类型 | 只读 | 可选 | 说明 | 947| -------- | ------ | ---- | ---- | ----------- | 948| sn | string | 否 | 否 | 表示设备的序列号。 | 949| deviceType | string | 否 | 否 | 表示设备类型。 | 950| modelId | string | 否 | 否 | 表示左侧耳机的充电状态。 | 951| manufactory | string | 否 | 否 | 表示制造商信息。 | 952| productId | string | 否 | 否 | 表示设备产品信息。 | 953| hiLinkVersion | string | 否 | 否 | 表示hilink版本信息。 | 954| macAddress | string | 否 | 否 | 表示设备MAC地址。 | 955| serviceType | string | 否 | 否 | 表示设备服务类型。 | 956| serviceId | string | 否 | 否 | 表示设备id。 | 957| deviceName | string | 否 | 否 | 表示设备名字。 | 958| uuids | string | 否 | 否 | 表示设备的UUID。 | 959| bluetoothClass | number | 否 | 否 | 表示远端设备类型。 | 960| token | ArrayBuffer | 否 | 否 | 表示设备的token信息。 | 961| deviceNameTime | number | 否 | 否 | 表示设备名字的修改时间。 | 962| secureAdvertisingInfo | ArrayBuffer | 否 | 否 | 表示设备广播信息。 | 963| pairState | number | 否 | 否 | 表示设备配对状态。 | 964