1# @ohos.bluetooth.ble (蓝牙ble模块) 2 3ble模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7> - 接口中涉及的UUID服务，可以通过工具函数[util.generateRandomUUID](../apis-arkts/js-apis-util.md#utilgeneraterandomuuid9)生成。 8 9 10 11## 导入模块 12 13```js 14import { ble } from '@kit.ConnectivityKit'; 15``` 16 17 18## ProfileConnectionState<sup>10+</sup> 19 20type ProfileConnectionState = constant.ProfileConnectionState 21 22蓝牙设备的profile连接状态。 23 24**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 25 26**系统能力**：SystemCapability.Communication.Bluetooth.Core 27 28| 类型 | 说明 | 29| ------------------- | ------------------- | 30| [constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 蓝牙设备的profile连接状态。 | 31 32 33## ble.createGattServer 34 35createGattServer(): GattServer 36 37创建GattServer实例。 38 39**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力**：SystemCapability.Communication.Bluetooth.Core 42 43**返回值：** 44 45| 类型 | 说明 | 46| ----------------------------- | ---------- | 47| [GattServer](#gattserver) | 返回一个Gatt服务的实例。 | 48 49**示例：** 50 51```js 52let gattServer: ble.GattServer = ble.createGattServer(); 53console.info('gatt success'); 54``` 55 56 57## ble.createGattClientDevice 58 59createGattClientDevice(deviceId: string): GattClientDevice 60 61创建一个可使用的GattClientDevice实例。 62 63**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 64 65**系统能力**：SystemCapability.Communication.Bluetooth.Core 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| -------- | ------ | ---- | ------------------------------------ | 71| deviceId | string | 是 | 对端设备地址， 例如："XX:XX:XX:XX:XX:XX"。 | 72 73**返回值：** 74 75| 类型 | 说明 | 76| ------------------------------------- | ------------------------------------ | 77| [GattClientDevice](#gattclientdevice) | client端类，使用client端方法之前需要创建该类的实例进行操作。 | 78 79**错误码**： 80 81以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 82 83| 错误码ID | 错误信息 | 84| -------- | ---------------------------- | 85|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 86|801 | Capability not supported. | 87 88**示例：** 89 90```js 91import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 92try { 93 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 94} catch (err) { 95 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 96} 97``` 98 99 100## ble.getConnectedBLEDevices 101 102getConnectedBLEDevices(): Array<string> 103 104获取和当前设备连接的BLE设备。 105 106**需要权限**：ohos.permission.ACCESS_BLUETOOTH 107 108**系统能力**：SystemCapability.Communication.Bluetooth.Core 109 110**返回值：** 111 112| 类型 | 说明 | 113| ------------------- | ------------------- | 114| Array<string> | 返回当前设备作为Server端时连接BLE设备地址集合。<br>基于信息安全考虑，此处获取的设备地址为随机MAC地址。<br>- 配对成功后，该地址不会变更。<br>- 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 115 116**错误码**： 117 118以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 119 120| 错误码ID | 错误信息 | 121| -------- | ---------------------------- | 122|201 | Permission denied. | 123|801 | Capability not supported. | 124|2900001 | Service stopped. | 125|2900003 | Bluetooth disabled. | 126|2900099 | Operation failed. | 127 128**示例：** 129 130```js 131import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 132try { 133 let result: Array<string> = ble.getConnectedBLEDevices(); 134} catch (err) { 135 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 136} 137``` 138 139 140## ble.startBLEScan 141 142startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void 143 144发起BLE扫描流程。 145> **说明：** 146> - 该接口只能扫描BLE设备。 147> - 该接口只支持单路扫描，即应用同时只能调用一次，下一次调用前，需要先调用[ble.stopBLEScan](#blestopblescan)。 148> - 若需要使用多路扫描，可使用[BleScanner](#blescanner15)。 149 150**需要权限**：ohos.permission.ACCESS_BLUETOOTH 151 152**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 153 154**系统能力**：SystemCapability.Communication.Bluetooth.Core 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| ------- | -------------------------------------- | ---- | ----------------------------------- | 160| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，符合过滤条件的设备发现会保留。如果不使用过滤的方式，该参数设置为null。 | 161| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的参数配置，可选参数。 | 162 163**错误码**： 164 165以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 166 167| 错误码ID | 错误信息 | 168| -------- | ---------------------------- | 169|201 | Permission denied. | 170|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 171|801 | Capability not supported. | 172|2900001 | Service stopped. | 173|2900003 | Bluetooth disabled. | 174|2900099 | Operation failed. | 175 176**示例：** 177 178```js 179import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 180function onReceiveEvent(data: Array<ble.ScanResult>) { 181 console.info('BLE scan device find result = '+ JSON.stringify(data)); 182} 183try { 184 ble.on("BLEDeviceFind", onReceiveEvent); 185 let scanFilter: ble.ScanFilter = { 186 deviceId:"XX:XX:XX:XX:XX:XX", 187 name:"test", 188 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 189 }; 190 let scanOptions: ble.ScanOptions = { 191 interval: 500, 192 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 193 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE 194 } 195 ble.startBLEScan([scanFilter],scanOptions); 196} catch (err) { 197 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 198} 199``` 200 201 202## ble.stopBLEScan 203 204stopBLEScan(): void 205 206停止BLE扫描流程。 207 208**需要权限**：ohos.permission.ACCESS_BLUETOOTH 209 210**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 211 212**系统能力**：SystemCapability.Communication.Bluetooth.Core 213 214**错误码**： 215 216以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 217 218| 错误码ID | 错误信息 | 219| -------- | ---------------------------- | 220|201 | Permission denied. | 221|801 | Capability not supported. | 222|2900001 | Service stopped. | 223|2900003 | Bluetooth disabled. | 224|2900099 | Operation failed. | 225 226**示例：** 227 228```js 229import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 230try { 231 ble.stopBLEScan(); 232} catch (err) { 233 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 234} 235``` 236 237 238## ble.startAdvertising 239 240startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void 241 242开始发送BLE广播。 243 244**需要权限**：ohos.permission.ACCESS_BLUETOOTH 245 246**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 247 248**系统能力**：SystemCapability.Communication.Bluetooth.Core 249 250**参数：** 251 252| 参数名 | 类型 | 必填 | 说明 | 253| ----------- | ------------------------------------- | ---- | -------------- | 254| setting | [AdvertiseSetting](#advertisesetting) | 是 | BLE广播的相关参数。 | 255| advData | [AdvertiseData](#advertisedata) | 是 | BLE广播包内容。 | 256| advResponse | [AdvertiseData](#advertisedata) | 否 | BLE回复扫描请求回复响应。 | 257 258**错误码**： 259 260以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 261 262| 错误码ID | 错误信息 | 263| -------- | ---------------------------- | 264|201 | Permission denied. | 265|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 266|801 | Capability not supported. | 267|2900001 | Service stopped. | 268|2900003 | Bluetooth disabled. | 269|2900099 | Operation failed. | 270 271**示例：** 272 273```js 274import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 275let manufactureValueBuffer = new Uint8Array(4); 276manufactureValueBuffer[0] = 1; 277manufactureValueBuffer[1] = 2; 278manufactureValueBuffer[2] = 3; 279manufactureValueBuffer[3] = 4; 280 281let serviceValueBuffer = new Uint8Array(4); 282serviceValueBuffer[0] = 4; 283serviceValueBuffer[1] = 6; 284serviceValueBuffer[2] = 7; 285serviceValueBuffer[3] = 8; 286console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 287console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 288try { 289 let setting: ble.AdvertiseSetting = { 290 interval:150, 291 txPower:0, 292 connectable:true 293 }; 294 let manufactureDataUnit: ble.ManufactureData = { 295 manufactureId:4567, 296 manufactureValue:manufactureValueBuffer.buffer 297 }; 298 let serviceDataUnit: ble.ServiceData = { 299 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 300 serviceValue:serviceValueBuffer.buffer 301 }; 302 let advData: ble.AdvertiseData = { 303 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 304 manufactureData:[manufactureDataUnit], 305 serviceData:[serviceDataUnit] 306 }; 307 let advResponse: ble.AdvertiseData = { 308 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 309 manufactureData:[manufactureDataUnit], 310 serviceData:[serviceDataUnit] 311 }; 312 ble.startAdvertising(setting, advData ,advResponse); 313} catch (err) { 314 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 315} 316``` 317 318 319## ble.stopAdvertising 320 321stopAdvertising(): void 322 323停止发送BLE广播。 324 325**需要权限**：ohos.permission.ACCESS_BLUETOOTH 326 327**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 328 329**系统能力**：SystemCapability.Communication.Bluetooth.Core 330 331**错误码**： 332 333以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 334 335| 错误码ID | 错误信息 | 336| -------- | ---------------------------- | 337|201 | Permission denied. | 338|801 | Capability not supported. | 339|2900001 | Service stopped. | 340|2900003 | Bluetooth disabled. | 341|2900099 | Operation failed. | 342 343**示例：** 344 345```js 346import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 347try { 348 ble.stopAdvertising(); 349} catch (err) { 350 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 351} 352``` 353 354 355## ble.startAdvertising<sup>11+</sup> 356 357startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void 358 359开始发送BLE广播。使用Callback异步回调。从API15开始，多次调用，可发起多路广播，每一路广播通过不同的ID管理。 360 361**需要权限**：ohos.permission.ACCESS_BLUETOOTH 362 363**系统能力**：SystemCapability.Communication.Bluetooth.Core 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| ------------------- | --------------------------------------- | ----- | ------------------------------- | 369| advertisingParams | [AdvertisingParams](#advertisingparams11) | 是 | 启动BLE广播的相关参数。 | 370| callback | AsyncCallback<number> | 是 | 广播ID标识，通过注册回调函数获取。 | 371 372**错误码**： 373 374以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 375 376| 错误码ID | 错误信息 | 377| -------- | -------------------------------------- | 378|201 | Permission denied. | 379|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 380|801 | Capability not supported. | 381|2900001 | Service stopped. | 382|2900003 | Bluetooth disabled. | 383|2900099 | Operation failed. | 384 385**示例：** 386 387```js 388import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 389let manufactureValueBuffer = new Uint8Array(4); 390manufactureValueBuffer[0] = 1; 391manufactureValueBuffer[1] = 2; 392manufactureValueBuffer[2] = 3; 393manufactureValueBuffer[3] = 4; 394 395let serviceValueBuffer = new Uint8Array(4); 396serviceValueBuffer[0] = 4; 397serviceValueBuffer[1] = 6; 398serviceValueBuffer[2] = 7; 399serviceValueBuffer[3] = 8; 400console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 401console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 402try { 403 let setting: ble.AdvertiseSetting = { 404 interval:150, 405 txPower:0, 406 connectable:true, 407 }; 408 let manufactureDataUnit: ble.ManufactureData = { 409 manufactureId:4567, 410 manufactureValue:manufactureValueBuffer.buffer 411 }; 412 let serviceDataUnit: ble.ServiceData = { 413 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 414 serviceValue:serviceValueBuffer.buffer 415 }; 416 let advData: ble.AdvertiseData = { 417 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 418 manufactureData:[manufactureDataUnit], 419 serviceData:[serviceDataUnit] 420 }; 421 let advResponse: ble.AdvertiseData = { 422 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 423 manufactureData:[manufactureDataUnit], 424 serviceData:[serviceDataUnit] 425 }; 426 let advertisingParams: ble.AdvertisingParams = { 427 advertisingSettings: setting, 428 advertisingData: advData, 429 advertisingResponse: advResponse, 430 duration: 0 431 } 432 let advHandle = 0xFF; 433 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 434 if (err) { 435 return; 436 } else { 437 advHandle = outAdvHandle; 438 console.info("advHandle: " + advHandle); 439 } 440 }); 441} catch (err) { 442 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 443} 444``` 445 446 447## ble.startAdvertising<sup>11+</sup> 448 449startAdvertising(advertisingParams: AdvertisingParams): Promise<number> 450 451开始发送BLE广播。使用Promise异步回调。从API15开始，多次调用，可发起多路广播，每一路广播通过不同的ID管理。 452 453**需要权限**：ohos.permission.ACCESS_BLUETOOTH 454 455**系统能力**：SystemCapability.Communication.Bluetooth.Core 456 457**参数：** 458 459| 参数名 | 类型 | 必填 | 说明 | 460| ------------------- | -------------------------------------- | ----- | ----------------------- | 461| advertisingParams | [AdvertisingParams](#advertisingparams11) | 是 | 启动BLE广播的相关参数。 | 462 463**返回值：** 464 465| 类型 | 说明 | 466| -------------------------- | ------------------------------- | 467| Promise<number> | 广播ID标识，通过promise形式获取。 | 468 469**错误码**： 470 471以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 472 473| 错误码ID | 错误信息 | 474| -------- | -------------------------------------- | 475|201 | Permission denied. | 476|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 477|801 | Capability not supported. | 478|2900001 | Service stopped. | 479|2900003 | Bluetooth disabled. | 480|2900099 | Operation failed. | 481 482**示例：** 483 484```js 485import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 486let manufactureValueBuffer = new Uint8Array(4); 487manufactureValueBuffer[0] = 1; 488manufactureValueBuffer[1] = 2; 489manufactureValueBuffer[2] = 3; 490manufactureValueBuffer[3] = 4; 491 492let serviceValueBuffer = new Uint8Array(4); 493serviceValueBuffer[0] = 4; 494serviceValueBuffer[1] = 6; 495serviceValueBuffer[2] = 7; 496serviceValueBuffer[3] = 8; 497console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 498console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 499try { 500 let setting: ble.AdvertiseSetting = { 501 interval:150, 502 txPower:0, 503 connectable:true 504 }; 505 let manufactureDataUnit: ble.ManufactureData = { 506 manufactureId:4567, 507 manufactureValue:manufactureValueBuffer.buffer 508 }; 509 let serviceDataUnit: ble.ServiceData = { 510 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 511 serviceValue:serviceValueBuffer.buffer 512 }; 513 let advData: ble.AdvertiseData = { 514 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 515 manufactureData:[manufactureDataUnit], 516 serviceData:[serviceDataUnit] 517 }; 518 let advResponse: ble.AdvertiseData = { 519 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 520 manufactureData:[manufactureDataUnit], 521 serviceData:[serviceDataUnit] 522 }; 523 let advertisingParams: ble.AdvertisingParams = { 524 advertisingSettings: setting, 525 advertisingData: advData, 526 advertisingResponse: advResponse, 527 duration: 0 528 } 529 let advHandle = 0xFF; 530 ble.startAdvertising(advertisingParams) 531 .then(outAdvHandle => { 532 advHandle = outAdvHandle; 533 }); 534} catch (err) { 535 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 536} 537``` 538 539 540## ble.enableAdvertising<sup>11+</sup> 541 542enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void 543 544临时启动BLE广播。使用Callback异步回调。 545 546**需要权限**：ohos.permission.ACCESS_BLUETOOTH 547 548**系统能力**：SystemCapability.Communication.Bluetooth.Core 549 550**参数：** 551 552| 参数名 | 类型 | 必填 | 说明 | 553| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 554| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | 是 | 临时启动BLE广播的相关参数。 | 555| callback | AsyncCallback<void> | 是 | 回调函数。 | 556 557**错误码**： 558 559以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 560 561| 错误码ID | 错误信息 | 562| ------- | -------------------------------------- | 563|201 | Permission denied. | 564|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 565|801 | Capability not supported. | 566|2900001 | Service stopped. | 567|2900003 | Bluetooth disabled. | 568|2900099 | Operation failed. | 569 570**示例：** 571 572```js 573import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 574let manufactureValueBuffer = new Uint8Array(4); 575manufactureValueBuffer[0] = 1; 576manufactureValueBuffer[1] = 2; 577manufactureValueBuffer[2] = 3; 578manufactureValueBuffer[3] = 4; 579 580let serviceValueBuffer = new Uint8Array(4); 581serviceValueBuffer[0] = 4; 582serviceValueBuffer[1] = 6; 583serviceValueBuffer[2] = 7; 584serviceValueBuffer[3] = 8; 585console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 586console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 587try { 588 let setting: ble.AdvertiseSetting = { 589 interval:150, 590 txPower:0, 591 connectable:true 592 }; 593 let manufactureDataUnit: ble.ManufactureData = { 594 manufactureId:4567, 595 manufactureValue:manufactureValueBuffer.buffer 596 }; 597 let serviceDataUnit: ble.ServiceData = { 598 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 599 serviceValue:serviceValueBuffer.buffer 600 }; 601 let advData: ble.AdvertiseData = { 602 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 603 manufactureData:[manufactureDataUnit], 604 serviceData:[serviceDataUnit] 605 }; 606 let advResponse: ble.AdvertiseData = { 607 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 608 manufactureData:[manufactureDataUnit], 609 serviceData:[serviceDataUnit] 610 }; 611 let advertisingParams: ble.AdvertisingParams = { 612 advertisingSettings: setting, 613 advertisingData: advData, 614 advertisingResponse: advResponse, 615 duration: 300 616 } 617 let advHandle = 0xFF; 618 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 619 if (err) { 620 return; 621 } else { 622 advHandle = outAdvHandle; 623 console.info("advHandle: " + advHandle); 624 } 625 }); 626 627 let advertisingEnableParams: ble.AdvertisingEnableParams = { 628 advertisingId: advHandle, 629 duration: 0 630 } 631 632 // after 3s, advertising disabled, then enable the advertising 633 ble.enableAdvertising(advertisingEnableParams, (err) => { 634 if (err) { 635 return; 636 } 637 }); 638} catch (err) { 639 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 640} 641``` 642 643 644## ble.enableAdvertising<sup>11+</sup> 645 646enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void> 647 648临时启动BLE广播。使用Promise异步回调。 649 650**需要权限**：ohos.permission.ACCESS_BLUETOOTH 651 652**系统能力**：SystemCapability.Communication.Bluetooth.Core 653 654**参数：** 655 656| 参数名 | 类型 | 必填 | 说明 | 657| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 658| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | 是 | 临时启动BLE广播的相关参数。 | 659 660**返回值：** 661 662| 类型 | 说明 | 663| -------------------------- | ------------ | 664| Promise<void> | 回调函数。 | 665 666**错误码**： 667 668以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 669 670| 错误码ID | 错误信息 | 671| ------- | -------------------------------------- | 672|201 | Permission denied. | 673|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 674|801 | Capability not supported. | 675|2900001 | Service stopped. | 676|2900003 | Bluetooth disabled. | 677|2900099 | Operation failed. | 678 679**示例：** 680 681```js 682import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 683let manufactureValueBuffer = new Uint8Array(4); 684manufactureValueBuffer[0] = 1; 685manufactureValueBuffer[1] = 2; 686manufactureValueBuffer[2] = 3; 687manufactureValueBuffer[3] = 4; 688 689let serviceValueBuffer = new Uint8Array(4); 690serviceValueBuffer[0] = 4; 691serviceValueBuffer[1] = 6; 692serviceValueBuffer[2] = 7; 693serviceValueBuffer[3] = 8; 694console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 695console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 696try { 697 let setting: ble.AdvertiseSetting = { 698 interval:150, 699 txPower:0, 700 connectable:true 701 }; 702 let manufactureDataUnit: ble.ManufactureData = { 703 manufactureId:4567, 704 manufactureValue:manufactureValueBuffer.buffer 705 }; 706 let serviceDataUnit: ble.ServiceData = { 707 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 708 serviceValue:serviceValueBuffer.buffer 709 }; 710 let advData: ble.AdvertiseData = { 711 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 712 manufactureData:[manufactureDataUnit], 713 serviceData:[serviceDataUnit] 714 }; 715 let advResponse: ble.AdvertiseData = { 716 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 717 manufactureData:[manufactureDataUnit], 718 serviceData:[serviceDataUnit] 719 }; 720 let advertisingParams: ble.AdvertisingParams = { 721 advertisingSettings: setting, 722 advertisingData: advData, 723 advertisingResponse: advResponse, 724 duration: 300 725 } 726 let advHandle = 0xFF; 727 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 728 if (err) { 729 return; 730 } else { 731 advHandle = outAdvHandle; 732 console.info("advHandle: " + advHandle); 733 } 734 }); 735 736 let advertisingEnableParams: ble.AdvertisingEnableParams = { 737 advertisingId: advHandle, 738 duration: 0 739 } 740 741 // after 3s, advertising disabled, then enable the advertising 742 ble.enableAdvertising(advertisingEnableParams) 743 .then(() => { 744 console.info("enable success"); 745 }); 746} catch (err) { 747 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 748} 749``` 750 751 752## ble.disableAdvertising<sup>11+</sup> 753 754disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void 755 756临时停止BLE广播。使用Callback异步回调。 757 758**需要权限**：ohos.permission.ACCESS_BLUETOOTH 759 760**系统能力**：SystemCapability.Communication.Bluetooth.Core 761 762**参数：** 763 764| 参数名 | 类型 | 必填 | 说明 | 765| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 766| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | 是 | 临时停止BLE广播的相关参数。 | 767| callback | AsyncCallback<void> | 是 | 回调函数。 | 768 769**错误码**： 770 771以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 772 773| 错误码ID | 错误信息 | 774| ------- | -------------------------------------- | 775|201 | Permission denied. | 776|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 777|801 | Capability not supported. | 778|2900001 | Service stopped. | 779|2900003 | Bluetooth disabled. | 780|2900099 | Operation failed. | 781 782**示例：** 783 784```js 785import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 786let manufactureValueBuffer = new Uint8Array(4); 787manufactureValueBuffer[0] = 1; 788manufactureValueBuffer[1] = 2; 789manufactureValueBuffer[2] = 3; 790manufactureValueBuffer[3] = 4; 791 792let serviceValueBuffer = new Uint8Array(4); 793serviceValueBuffer[0] = 4; 794serviceValueBuffer[1] = 6; 795serviceValueBuffer[2] = 7; 796serviceValueBuffer[3] = 8; 797console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 798console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 799try { 800 let setting: ble.AdvertiseSetting = { 801 interval:150, 802 txPower:0, 803 connectable:true 804 }; 805 let manufactureDataUnit: ble.ManufactureData = { 806 manufactureId:4567, 807 manufactureValue:manufactureValueBuffer.buffer 808 }; 809 let serviceDataUnit: ble.ServiceData = { 810 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 811 serviceValue:serviceValueBuffer.buffer 812 }; 813 let advData: ble.AdvertiseData = { 814 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 815 manufactureData:[manufactureDataUnit], 816 serviceData:[serviceDataUnit] 817 }; 818 let advResponse: ble.AdvertiseData = { 819 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 820 manufactureData:[manufactureDataUnit], 821 serviceData:[serviceDataUnit] 822 }; 823 let advertisingParams: ble.AdvertisingParams = { 824 advertisingSettings: setting, 825 advertisingData: advData, 826 advertisingResponse: advResponse, 827 duration: 0 828 } 829 let advHandle = 0xFF; 830 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 831 if (err) { 832 return; 833 } else { 834 advHandle = outAdvHandle; 835 console.info("advHandle: " + advHandle); 836 } 837 }); 838 839 let advertisingDisableParams: ble.AdvertisingDisableParams = { 840 advertisingId: advHandle 841 } 842 ble.disableAdvertising(advertisingDisableParams, (err) => { 843 if (err) { 844 return; 845 } 846 }); 847} catch (err) { 848 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 849} 850``` 851 852 853## ble.disableAdvertising<sup>11+</sup> 854 855disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void> 856 857临时停止BLE广播。使用Promise异步回调。 858 859**需要权限**：ohos.permission.ACCESS_BLUETOOTH 860 861**系统能力**：SystemCapability.Communication.Bluetooth.Core 862 863**参数：** 864 865| 参数名 | 类型 | 必填 | 说明 | 866| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 867| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | 是 | 临时停止BLE广播的相关参数。 | 868 869**返回值：** 870 871| 类型 | 说明 | 872| -------------------------- | ------------ | 873| Promise<void> | 回调函数。 | 874 875**错误码**： 876 877以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 878 879| 错误码ID | 错误信息 | 880| ------- | -------------------------------------- | 881|201 | Permission denied. | 882|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 883|801 | Capability not supported. | 884|2900001 | Service stopped. | 885|2900003 | Bluetooth disabled. | 886|2900099 | Operation failed. | 887 888**示例：** 889 890```js 891import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 892let manufactureValueBuffer = new Uint8Array(4); 893manufactureValueBuffer[0] = 1; 894manufactureValueBuffer[1] = 2; 895manufactureValueBuffer[2] = 3; 896manufactureValueBuffer[3] = 4; 897 898let serviceValueBuffer = new Uint8Array(4); 899serviceValueBuffer[0] = 4; 900serviceValueBuffer[1] = 6; 901serviceValueBuffer[2] = 7; 902serviceValueBuffer[3] = 8; 903console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 904console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 905try { 906 let setting: ble.AdvertiseSetting = { 907 interval:150, 908 txPower:0, 909 connectable:true 910 }; 911 let manufactureDataUnit: ble.ManufactureData = { 912 manufactureId:4567, 913 manufactureValue:manufactureValueBuffer.buffer 914 }; 915 let serviceDataUnit: ble.ServiceData = { 916 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 917 serviceValue:serviceValueBuffer.buffer 918 }; 919 let advData: ble.AdvertiseData = { 920 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 921 manufactureData:[manufactureDataUnit], 922 serviceData:[serviceDataUnit] 923 }; 924 let advResponse: ble.AdvertiseData = { 925 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 926 manufactureData:[manufactureDataUnit], 927 serviceData:[serviceDataUnit] 928 }; 929 let advertisingParams: ble.AdvertisingParams = { 930 advertisingSettings: setting, 931 advertisingData: advData, 932 advertisingResponse: advResponse, 933 duration: 0 934 } 935 let advHandle = 0xFF; 936 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 937 if (err) { 938 return; 939 } else { 940 advHandle = outAdvHandle; 941 console.info("advHandle: " + advHandle); 942 } 943 }); 944 945 let advertisingDisableParams: ble.AdvertisingDisableParams = { 946 advertisingId: advHandle 947 } 948 ble.disableAdvertising(advertisingDisableParams) 949 .then(() => { 950 console.info("enable success"); 951 }); 952} catch (err) { 953 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 954} 955``` 956 957## ble.stopAdvertising<sup>11+</sup> 958 959stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void 960 961停止发送BLE广播。使用Callback异步回调。 962 963**需要权限**：ohos.permission.ACCESS_BLUETOOTH 964 965**系统能力**：SystemCapability.Communication.Bluetooth.Core 966 967**参数：** 968 969| 参数名 | 类型 | 必填 | 说明 | 970| ------------------------- | ---------------------------- | ----- | --------------------------- | 971| advertisingId | number | 是 | 需要停止的广播ID标识。 | 972| callback | AsyncCallback<void> | 是 | 回调函数。 | 973 974**错误码**： 975 976以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 977 978| 错误码ID | 错误信息 | 979| -------- | ---------------------------- | 980|201 | Permission denied. | 981|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 982|801 | Capability not supported. | 983|2900001 | Service stopped. | 984|2900003 | Bluetooth disabled. | 985|2900099 | Operation failed. | 986 987**示例：** 988 989```js 990import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 991let manufactureValueBuffer = new Uint8Array(4); 992manufactureValueBuffer[0] = 1; 993manufactureValueBuffer[1] = 2; 994manufactureValueBuffer[2] = 3; 995manufactureValueBuffer[3] = 4; 996 997let serviceValueBuffer = new Uint8Array(4); 998serviceValueBuffer[0] = 4; 999serviceValueBuffer[1] = 6; 1000serviceValueBuffer[2] = 7; 1001serviceValueBuffer[3] = 8; 1002console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 1003console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 1004try { 1005 let setting: ble.AdvertiseSetting = { 1006 interval:150, 1007 txPower:0, 1008 connectable:true 1009 }; 1010 let manufactureDataUnit: ble.ManufactureData = { 1011 manufactureId:4567, 1012 manufactureValue:manufactureValueBuffer.buffer 1013 }; 1014 let serviceDataUnit: ble.ServiceData = { 1015 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 1016 serviceValue:serviceValueBuffer.buffer 1017 }; 1018 let advData: ble.AdvertiseData = { 1019 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1020 manufactureData:[manufactureDataUnit], 1021 serviceData:[serviceDataUnit] 1022 }; 1023 let advResponse: ble.AdvertiseData = { 1024 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1025 manufactureData:[manufactureDataUnit], 1026 serviceData:[serviceDataUnit] 1027 }; 1028 let advertisingParams: ble.AdvertisingParams = { 1029 advertisingSettings: setting, 1030 advertisingData: advData, 1031 advertisingResponse: advResponse, 1032 duration: 0 1033 } 1034 let advHandle = 0xFF; 1035 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 1036 if (err) { 1037 return; 1038 } else { 1039 advHandle = outAdvHandle; 1040 console.info("advHandle: " + advHandle); 1041 } 1042 }); 1043 1044 ble.stopAdvertising(advHandle, (err) => { 1045 if (err) { 1046 return; 1047 } 1048 }); 1049} catch (err) { 1050 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1051} 1052``` 1053 1054 1055## ble.stopAdvertising<sup>11+</sup> 1056 1057stopAdvertising(advertisingId: number): Promise<void> 1058 1059停止发送BLE广播。使用Promise异步回调。 1060 1061**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1062 1063**系统能力**：SystemCapability.Communication.Bluetooth.Core 1064 1065**参数：** 1066 1067| 参数名 | 类型 | 必填 | 说明 | 1068| ------------------------- | ---------------------------- | ----- | --------------------------- | 1069| advertisingId | number | 是 | 需要停止的广播ID标识。 | 1070 1071**返回值：** 1072 1073| 类型 | 说明 | 1074| -------------------------- | ------------ | 1075| Promise<void> | 回调函数。 | 1076 1077**错误码**： 1078 1079以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1080 1081| 错误码ID | 错误信息 | 1082| -------- | ---------------------------- | 1083|201 | Permission denied. | 1084|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 1085|801 | Capability not supported. | 1086|2900001 | Service stopped. | 1087|2900003 | Bluetooth disabled. | 1088|2900099 | Operation failed. | 1089 1090**示例：** 1091 1092```js 1093import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1094let manufactureValueBuffer = new Uint8Array(4); 1095manufactureValueBuffer[0] = 1; 1096manufactureValueBuffer[1] = 2; 1097manufactureValueBuffer[2] = 3; 1098manufactureValueBuffer[3] = 4; 1099 1100let serviceValueBuffer = new Uint8Array(4); 1101serviceValueBuffer[0] = 4; 1102serviceValueBuffer[1] = 6; 1103serviceValueBuffer[2] = 7; 1104serviceValueBuffer[3] = 8; 1105console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 1106console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 1107try { 1108 let setting: ble.AdvertiseSetting = { 1109 interval:150, 1110 txPower:0, 1111 connectable:true 1112 }; 1113 let manufactureDataUnit: ble.ManufactureData = { 1114 manufactureId:4567, 1115 manufactureValue:manufactureValueBuffer.buffer 1116 }; 1117 let serviceDataUnit: ble.ServiceData = { 1118 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 1119 serviceValue:serviceValueBuffer.buffer 1120 }; 1121 let advData: ble.AdvertiseData = { 1122 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1123 manufactureData:[manufactureDataUnit], 1124 serviceData:[serviceDataUnit] 1125 }; 1126 let advResponse: ble.AdvertiseData = { 1127 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1128 manufactureData:[manufactureDataUnit], 1129 serviceData:[serviceDataUnit] 1130 }; 1131 let advertisingParams: ble.AdvertisingParams = { 1132 advertisingSettings: setting, 1133 advertisingData: advData, 1134 advertisingResponse: advResponse, 1135 duration: 0 1136 } 1137 let advHandle = 0xFF; 1138 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 1139 if (err) { 1140 return; 1141 } else { 1142 advHandle = outAdvHandle; 1143 console.info("advHandle: " + advHandle); 1144 } 1145 }); 1146 1147 ble.stopAdvertising(advHandle) 1148 .then(() => { 1149 console.info("enable success"); 1150 }); 1151} catch (err) { 1152 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1153} 1154``` 1155 1156 1157## ble.on('advertisingStateChange')<sup>11+</sup> 1158 1159on(type: 'advertisingStateChange', callback: Callback<AdvertisingStateChangeInfo>): void 1160 1161订阅BLE广播状态。使用Callback异步回调。 1162 1163**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1164 1165**系统能力**：SystemCapability.Communication.Bluetooth.Core 1166 1167**参数：** 1168 1169| 参数名 | 类型 | 必填 | 说明 | 1170| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1171| type | string | 是 | 填写"advertisingStateChange"字符串，表示广播状态事件。 | 1172| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | 是 | 表示回调函数的入参，广播状态。回调函数由用户创建通过该接口注册。 | 1173 1174**错误码**： 1175 1176以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1177 1178| 错误码ID | 错误信息 | 1179| -------- | ---------------------------- | 1180|201 | Permission denied. | 1181|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1182|801 | Capability not supported. | 1183|2900099 | Operation failed. | 1184 1185**示例：** 1186 1187```js 1188import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1189function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1190 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1191} 1192try { 1193 ble.on('advertisingStateChange', onReceiveEvent); 1194} catch (err) { 1195 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1196} 1197``` 1198 1199 1200## ble.off('advertisingStateChange')<sup>11+</sup> 1201 1202off(type: 'advertisingStateChange', callback?: Callback<AdvertisingStateChangeInfo>): void 1203 1204取消订阅BLE广播状态。 1205 1206**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1207 1208**系统能力**：SystemCapability.Communication.Bluetooth.Core 1209 1210**参数：** 1211 1212| 参数名 | 类型 | 必填 | 说明 | 1213| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1214| type | string | 是 | 填写"advertisingStateChange"字符串，表示广播状态事件。 | 1215| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | 否 | 表示取消订阅广播状态上报。不填该参数则取消订阅该type对应的所有回调。 | 1216 1217**错误码**： 1218 1219以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1220 1221| 错误码ID | 错误信息 | 1222| -------- | ---------------------------- | 1223|201 | Permission denied. | 1224|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1225|801 | Capability not supported. | 1226|2900099 | Operation failed. | 1227 1228**示例：** 1229 1230```js 1231import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1232function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1233 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1234} 1235try { 1236 ble.on('advertisingStateChange', onReceiveEvent); 1237 ble.off('advertisingStateChange', onReceiveEvent); 1238} catch (err) { 1239 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1240} 1241``` 1242 1243 1244## ble.on('BLEDeviceFind') 1245 1246on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void 1247 1248订阅BLE设备发现上报事件。使用Callback异步回调。 1249 1250**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1251 1252**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1253 1254**系统能力**：SystemCapability.Communication.Bluetooth.Core 1255 1256**参数：** 1257 1258| 参数名 | 类型 | 必填 | 说明 | 1259| -------- | ---------------------------------------- | ---- | ----------------------------------- | 1260| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 1261| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 1262 1263**错误码**： 1264 1265以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1266 1267| 错误码ID | 错误信息 | 1268| -------- | ---------------------------- | 1269|201 | Permission denied. | 1270|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1271|801 | Capability not supported. | 1272|2900099 | Operation failed. | 1273 1274**示例：** 1275 1276```js 1277import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1278function onReceiveEvent(data: Array<ble.ScanResult>) { 1279 console.info('bluetooth device find = '+ JSON.stringify(data)); 1280} 1281try { 1282 ble.on('BLEDeviceFind', onReceiveEvent); 1283} catch (err) { 1284 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1285} 1286``` 1287 1288 1289## ble.off('BLEDeviceFind') 1290 1291off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void 1292 1293取消订阅BLE设备发现上报事件。 1294 1295**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1296 1297**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1298 1299**系统能力**：SystemCapability.Communication.Bluetooth.Core 1300 1301**参数：** 1302 1303| 参数名 | 类型 | 必填 | 说明 | 1304| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1305| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 1306| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1307 1308**错误码**： 1309 1310以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1311 1312 1313| 错误码ID | 错误信息 | 1314| -------- | ---------------------------- | 1315|201 | Permission denied. | 1316|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1317|801 | Capability not supported. | 1318|2900099 | Operation failed. | 1319 1320**示例：** 1321 1322```js 1323import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1324function onReceiveEvent(data: Array<ble.ScanResult>) { 1325 console.info('bluetooth device find = '+ JSON.stringify(data)); 1326} 1327try { 1328 ble.on('BLEDeviceFind', onReceiveEvent); 1329 ble.off('BLEDeviceFind', onReceiveEvent); 1330} catch (err) { 1331 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1332} 1333``` 1334 1335 1336## GattServer 1337 1338server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。 1339 1340 1341### addService 1342 1343addService(service: GattService): void 1344 1345server端添加服务。 1346 1347**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1348 1349**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1350 1351**系统能力**：SystemCapability.Communication.Bluetooth.Core 1352 1353**参数：** 1354 1355| 参数名 | 类型 | 必填 | 说明 | 1356| ------- | --------------------------- | ---- | ------------------------ | 1357| service | [GattService](#gattservice) | 是 | 服务端的service数据。BLE广播的相关参数 | 1358 1359**错误码**： 1360 1361以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1362 1363| 错误码ID | 错误信息 | 1364| -------- | ---------------------------- | 1365|201 | Permission denied. | 1366|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1367|801 | Capability not supported. | 1368|2900001 | Service stopped. | 1369|2900003 | Bluetooth disabled. | 1370|2900099 | Operation failed. | 1371 1372**示例：** 1373 1374```js 1375import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1376// 创建descriptors。 1377let descriptors: Array<ble.BLEDescriptor> = []; 1378let arrayBuffer = new ArrayBuffer(8); 1379let descV = new Uint8Array(arrayBuffer); 1380descV[0] = 11; 1381let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1382 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1383 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 1384descriptors[0] = descriptor; 1385 1386// 创建characteristics。 1387let characteristics: Array<ble.BLECharacteristic> = []; 1388let arrayBufferC = new ArrayBuffer(8); 1389let cccV = new Uint8Array(arrayBufferC); 1390cccV[0] = 1; 1391let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1392 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 1393characteristics[0] = characteristic; 1394 1395// 创建gattService。 1396let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; 1397 1398try { 1399 let gattServer: ble.GattServer = ble.createGattServer(); 1400 gattServer.addService(gattService); 1401} catch (err) { 1402 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1403} 1404``` 1405 1406 1407### removeService 1408 1409removeService(serviceUuid: string): void 1410 1411删除已添加的服务。 1412 1413**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1414 1415**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1416 1417**系统能力**：SystemCapability.Communication.Bluetooth.Core 1418 1419**参数：** 1420 1421| 参数名 | 类型 | 必填 | 说明 | 1422| ----------- | ------ | ---- | ---------------------------------------- | 1423| serviceUuid | string | 是 | service的UUID。例如“00001810-0000-1000-8000-00805F9B34FB”。 | 1424 1425**错误码**： 1426 1427以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1428 1429| 错误码ID | 错误信息 | 1430| -------- | ---------------------------- | 1431|201 | Permission denied. | 1432|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1433|801 | Capability not supported. | 1434|2900001 | Service stopped. | 1435|2900003 | Bluetooth disabled. | 1436|2900004 | Profile not supported. | 1437|2900099 | Operation failed. | 1438 1439**示例：** 1440 1441```js 1442import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1443let server: ble.GattServer = ble.createGattServer(); 1444try { 1445 // 调用removeService接口前需要完成server端和client端的配对及连接。 1446 server.removeService('00001810-0000-1000-8000-00805F9B34FB'); 1447} catch (err) { 1448 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1449} 1450``` 1451 1452 1453### close 1454 1455close(): void 1456 1457关闭服务端功能，去掉server在协议栈的注册，调用该接口后[GattServer](#gattserver)实例将不能再使用。 1458 1459**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1460 1461**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1462 1463**系统能力**：SystemCapability.Communication.Bluetooth.Core 1464 1465**错误码**： 1466 1467以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1468 1469| 错误码ID | 错误信息 | 1470| -------- | ---------------------------- | 1471|201 | Permission denied. | 1472|801 | Capability not supported. | 1473|2900001 | Service stopped. | 1474|2900003 | Bluetooth disabled. | 1475|2900099 | Operation failed. | 1476 1477**示例：** 1478 1479```js 1480import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1481let server: ble.GattServer = ble.createGattServer(); 1482try { 1483 server.close(); 1484} catch (err) { 1485 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1486} 1487``` 1488 1489 1490### notifyCharacteristicChanged 1491 1492notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void 1493 1494server端特征值发生变化时，主动通知已连接的client设备。使用Callback异步回调。 1495 1496**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1497 1498**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1499 1500**系统能力**：SystemCapability.Communication.Bluetooth.Core 1501 1502**参数：** 1503 1504| 参数名 | 类型 | 必填 | 说明 | 1505| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1506| deviceId | string | 是 | 接收通知的client端设备地址。例如“XX:XX:XX:XX:XX:XX”。 | 1507| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 1508| callback | AsyncCallback<void> | 是 | 回调函数。当通知成功，err为undefined，否则为错误对象。 | 1509 1510**错误码**： 1511 1512以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1513 1514| 错误码ID | 错误信息 | 1515| -------- | ---------------------------- | 1516|201 | Permission denied. | 1517|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1518|801 | Capability not supported. | 1519|2900001 | Service stopped. | 1520|2900003 | Bluetooth disabled. | 1521|2900099 | Operation failed. | 1522 1523**示例：** 1524 1525```js 1526import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1527let arrayBufferC = new ArrayBuffer(8); 1528let notifyCharacter: ble.NotifyCharacteristic = { 1529 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1530 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1531 characteristicValue: arrayBufferC, 1532 confirm: true 1533}; 1534try { 1535 let gattServer: ble.GattServer = ble.createGattServer(); 1536 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => { 1537 if (err) { 1538 console.info('notifyCharacteristicChanged callback failed'); 1539 } else { 1540 console.info('notifyCharacteristicChanged callback successful'); 1541 } 1542 }); 1543} catch (err) { 1544 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1545} 1546``` 1547 1548 1549### notifyCharacteristicChanged 1550 1551notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> 1552 1553server端特征值发生变化时，主动通知已连接的client设备。使用Promise异步回调。 1554 1555**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1556 1557**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1558 1559**系统能力**：SystemCapability.Communication.Bluetooth.Core 1560 1561**参数：** 1562 1563| 参数名 | 类型 | 必填 | 说明 | 1564| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1565| deviceId | string | 是 | 接收通知的client端设备地址。例如“XX:XX:XX:XX:XX:XX”。 | 1566| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 1567 1568**返回值：** 1569 1570| 类型 | 说明 | 1571| ------------------- | ------------- | 1572| Promise<void> | 返回promise对象。 | 1573 1574**错误码**： 1575 1576以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1577 1578| 错误码ID | 错误信息 | 1579| -------- | ---------------------------- | 1580|201 | Permission denied. | 1581|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1582|801 | Capability not supported. | 1583|2900001 | Service stopped. | 1584|2900003 | Bluetooth disabled. | 1585|2900099 | Operation failed. | 1586 1587**示例：** 1588 1589```js 1590import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1591let arrayBufferC = new ArrayBuffer(8); 1592let notifyCharacter: ble.NotifyCharacteristic = { 1593 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1594 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1595 characteristicValue: arrayBufferC, 1596 confirm: true 1597}; 1598try { 1599 let gattServer: ble.GattServer = ble.createGattServer(); 1600 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { 1601 console.info('notifyCharacteristicChanged promise successful'); 1602 }); 1603} catch (err) { 1604 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1605} 1606``` 1607 1608 1609### sendResponse 1610 1611sendResponse(serverResponse: ServerResponse): void 1612 1613server端回复client端的读写请求。 1614 1615**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1616 1617**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1618 1619**系统能力**：SystemCapability.Communication.Bluetooth.Core 1620 1621**参数：** 1622 1623| 参数名 | 类型 | 必填 | 说明 | 1624| -------------- | --------------------------------- | ---- | --------------- | 1625| serverResponse | [ServerResponse](#serverresponse) | 是 | server端回复的响应数据。 | 1626 1627**错误码**： 1628 1629以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 1630 1631| 错误码ID | 错误信息 | 1632| -------- | ---------------------------- | 1633|201 | Permission denied. | 1634|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1635|801 | Capability not supported. | 1636|2900001 | Service stopped. | 1637|2900003 | Bluetooth disabled. | 1638|2900099 | Operation failed. | 1639 1640**示例：** 1641 1642```js 1643import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1644/* send response */ 1645let arrayBufferCCC = new ArrayBuffer(8); 1646let cccValue = new Uint8Array(arrayBufferCCC); 1647cccValue[0] = 1123; 1648let serverResponse: ble.ServerResponse = { 1649 deviceId: 'XX:XX:XX:XX:XX:XX', 1650 transId: 0, 1651 status: 0, 1652 offset: 0, 1653 value: arrayBufferCCC 1654}; 1655try { 1656 let gattServer: ble.GattServer = ble.createGattServer(); 1657 gattServer.sendResponse(serverResponse); 1658} catch (err) { 1659 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1660} 1661``` 1662 1663 1664### on('characteristicRead') 1665 1666on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void 1667 1668server端订阅特征值读请求事件。使用Callback异步回调。 1669 1670**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1671 1672**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1673 1674**系统能力**：SystemCapability.Communication.Bluetooth.Core 1675 1676**参数：** 1677 1678| 参数名 | 类型 | 必填 | 说明 | 1679| -------- | ---------------------------------------- | ---- | ------------------------------------- | 1680| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 1681| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 1682 1683**错误码**： 1684 1685以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1686 1687| 错误码ID | 错误信息 | 1688| -------- | ---------------------------- | 1689|201 | Permission denied. | 1690|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1691|801 | Capability not supported. | 1692 1693**示例：** 1694 1695```js 1696import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1697let arrayBufferCCC = new ArrayBuffer(8); 1698let cccValue = new Uint8Array(arrayBufferCCC); 1699cccValue[0] = 1123; 1700let gattServer: ble.GattServer = ble.createGattServer(); 1701function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) { 1702 let deviceId: string = characteristicReadRequest.deviceId; 1703 let transId: number = characteristicReadRequest.transId; 1704 let offset: number = characteristicReadRequest.offset; 1705 let characteristicUuid: string = characteristicReadRequest.characteristicUuid; 1706 1707 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1708 1709 try { 1710 gattServer.sendResponse(serverResponse); 1711 } catch (err) { 1712 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1713 } 1714} 1715gattServer.on('characteristicRead', ReadCharacteristicReq); 1716``` 1717 1718 1719### off('characteristicRead') 1720 1721off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void 1722 1723server端取消订阅特征值读请求事件。 1724 1725**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1726 1727**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1728 1729**系统能力**：SystemCapability.Communication.Bluetooth.Core 1730 1731**参数：** 1732 1733| 参数名 | 类型 | 必填 | 说明 | 1734| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1735| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 1736| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 否 | 表示取消订阅特征值读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1737 1738**错误码**： 1739 1740以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1741 1742| 错误码ID | 错误信息 | 1743| -------- | ---------------------------- | 1744|201 | Permission denied. | 1745|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1746|801 | Capability not supported. | 1747 1748**示例：** 1749 1750```js 1751import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1752try { 1753 let gattServer: ble.GattServer = ble.createGattServer(); 1754 gattServer.off('characteristicRead'); 1755} catch (err) { 1756 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1757} 1758``` 1759 1760 1761### on('characteristicWrite') 1762 1763on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void 1764 1765server端订阅特征值写请求事件。使用Callback异步回调。 1766 1767**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1768 1769**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1770 1771**系统能力**：SystemCapability.Communication.Bluetooth.Core 1772 1773**参数：** 1774 1775| 参数名 | 类型 | 必填 | 说明 | 1776| -------- | ---------------------------------------- | ---- | -------------------------------------- | 1777| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 1778| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 1779 1780**错误码**： 1781 1782以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1783 1784| 错误码ID | 错误信息 | 1785| -------- | ---------------------------- | 1786|201 | Permission denied. | 1787|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1788|801 | Capability not supported. | 1789 1790**示例：** 1791 1792```js 1793import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1794let arrayBufferCCC = new ArrayBuffer(8); 1795let cccValue = new Uint8Array(arrayBufferCCC); 1796let gattServer: ble.GattServer = ble.createGattServer(); 1797function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) { 1798 let deviceId: string = characteristicWriteRequest.deviceId; 1799 let transId: number = characteristicWriteRequest.transId; 1800 let offset: number = characteristicWriteRequest.offset; 1801 let isPrepared: boolean = characteristicWriteRequest.isPrepared; 1802 let needRsp: boolean = characteristicWriteRequest.needRsp; 1803 let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value); 1804 let characteristicUuid: string = characteristicWriteRequest.characteristicUuid; 1805 1806 cccValue[0] = value[0]; 1807 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1808 1809 try { 1810 gattServer.sendResponse(serverResponse); 1811 } catch (err) { 1812 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1813 } 1814} 1815gattServer.on('characteristicWrite', WriteCharacteristicReq); 1816``` 1817 1818 1819### off('characteristicWrite') 1820 1821off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void 1822 1823server端取消订阅特征值写请求事件。 1824 1825**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1826 1827**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1828 1829**系统能力**：SystemCapability.Communication.Bluetooth.Core 1830 1831**参数：** 1832 1833| 参数名 | 类型 | 必填 | 说明 | 1834| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1835| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 1836| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 否 | 表示取消订阅特征值写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1837 1838**错误码**： 1839 1840以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1841 1842| 错误码ID | 错误信息 | 1843| -------- | ---------------------------- | 1844|201 | Permission denied. | 1845|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1846|801 | Capability not supported. | 1847 1848**示例：** 1849 1850```js 1851import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1852try { 1853 let gattServer: ble.GattServer = ble.createGattServer(); 1854 gattServer.off('characteristicWrite'); 1855} catch (err) { 1856 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1857} 1858``` 1859 1860 1861### on('descriptorRead') 1862 1863on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void 1864 1865server端订阅描述符读请求事件。使用Callback异步回调。 1866 1867**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1868 1869**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1870 1871**系统能力**：SystemCapability.Communication.Bluetooth.Core 1872 1873**参数：** 1874 1875| 参数名 | 类型 | 必填 | 说明 | 1876| -------- | ---------------------------------------- | ---- | --------------------------------- | 1877| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 1878| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 1879 1880**错误码**： 1881 1882以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1883 1884| 错误码ID | 错误信息 | 1885| -------- | ---------------------------- | 1886|201 | Permission denied. | 1887|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1888|801 | Capability not supported. | 1889 1890**示例：** 1891 1892```js 1893import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1894let arrayBufferDesc = new ArrayBuffer(8); 1895let descValue = new Uint8Array(arrayBufferDesc); 1896descValue[0] = 1101; 1897let gattServer: ble.GattServer = ble.createGattServer(); 1898function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) { 1899 let deviceId: string = descriptorReadRequest.deviceId; 1900 let transId: number = descriptorReadRequest.transId; 1901 let offset: number = descriptorReadRequest.offset; 1902 let descriptorUuid: string = descriptorReadRequest.descriptorUuid; 1903 1904 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 1905 1906 try { 1907 gattServer.sendResponse(serverResponse); 1908 } catch (err) { 1909 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1910 } 1911} 1912gattServer.on('descriptorRead', ReadDescriptorReq); 1913``` 1914 1915 1916### off('descriptorRead') 1917 1918off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void 1919 1920server端取消订阅描述符读请求事件。 1921 1922**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1923 1924**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1925 1926**系统能力**：SystemCapability.Communication.Bluetooth.Core 1927 1928**参数：** 1929 1930| 参数名 | 类型 | 必填 | 说明 | 1931| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1932| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 1933| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 否 | 表示取消订阅描述符读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 1934 1935**错误码**： 1936 1937以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1938 1939| 错误码ID | 错误信息 | 1940| -------- | ---------------------------- | 1941|201 | Permission denied. | 1942|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1943|801 | Capability not supported. | 1944 1945**示例：** 1946 1947```js 1948import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1949try { 1950 let gattServer: ble.GattServer = ble.createGattServer(); 1951 gattServer.off('descriptorRead'); 1952} catch (err) { 1953 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1954} 1955``` 1956 1957 1958### on('descriptorWrite') 1959 1960on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void 1961 1962server端订阅描述符写请求事件。使用Callback异步回调。 1963 1964**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1965 1966**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 1967 1968**系统能力**：SystemCapability.Communication.Bluetooth.Core 1969 1970**参数：** 1971 1972| 参数名 | 类型 | 必填 | 说明 | 1973| -------- | ---------------------------------------- | ---- | ---------------------------------- | 1974| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 1975| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 1976 1977**错误码**： 1978 1979以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1980 1981| 错误码ID | 错误信息 | 1982| -------- | ---------------------------- | 1983|201 | Permission denied. | 1984|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 1985|801 | Capability not supported. | 1986 1987**示例：** 1988 1989```js 1990import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 1991let arrayBufferDesc = new ArrayBuffer(8); 1992let descValue = new Uint8Array(arrayBufferDesc); 1993let gattServer: ble.GattServer = ble.createGattServer(); 1994function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) { 1995 let deviceId: string = descriptorWriteRequest.deviceId; 1996 let transId: number = descriptorWriteRequest.transId; 1997 let offset: number = descriptorWriteRequest.offset; 1998 let isPrepared: boolean = descriptorWriteRequest.isPrepared; 1999 let needRsp: boolean = descriptorWriteRequest.needRsp; 2000 let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value); 2001 let descriptorUuid: string = descriptorWriteRequest.descriptorUuid; 2002 2003 descValue[0] = value[0]; 2004 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 2005 2006 try { 2007 gattServer.sendResponse(serverResponse); 2008 } catch (err) { 2009 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2010 } 2011} 2012gattServer.on('descriptorWrite', WriteDescriptorReq); 2013``` 2014 2015 2016### off('descriptorWrite') 2017 2018off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void 2019 2020server端取消订阅描述符写请求事件。 2021 2022**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2023 2024**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2025 2026**系统能力**：SystemCapability.Communication.Bluetooth.Core 2027 2028**参数：** 2029 2030| 参数名 | 类型 | 必填 | 说明 | 2031| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2032| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 2033| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 否 | 表示取消订阅描述符写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 2034 2035**错误码**： 2036 2037以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2038 2039| 错误码ID | 错误信息 | 2040| -------- | ---------------------------- | 2041|201 | Permission denied. | 2042|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2043|801 | Capability not supported. | 2044 2045**示例：** 2046 2047```js 2048import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2049try { 2050let gattServer: ble.GattServer = ble.createGattServer(); 2051gattServer.off('descriptorWrite'); 2052} catch (err) { 2053 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2054} 2055``` 2056 2057 2058### on('connectionStateChange') 2059 2060on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void 2061 2062server端订阅BLE连接状态变化事件。使用Callback异步回调。 2063 2064**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2065 2066**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2067 2068**系统能力**：SystemCapability.Communication.Bluetooth.Core 2069 2070**参数：** 2071 2072| 参数名 | 类型 | 必填 | 说明 | 2073| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2074| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 2075| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示回调函数的入参，连接状态。 | 2076 2077**错误码**： 2078 2079以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2080 2081| 错误码ID | 错误信息 | 2082| -------- | ---------------------------- | 2083|201 | Permission denied. | 2084|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2085|801 | Capability not supported. | 2086 2087**示例：** 2088 2089```js 2090import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2091import { constant } from '@kit.ConnectivityKit'; 2092let Connected = (bleConnectionChangeState: ble.BLEConnectionChangeState) => { 2093 let deviceId: string = bleConnectionChangeState.deviceId; 2094 let status: constant.ProfileConnectionState = bleConnectionChangeState.state; 2095} 2096try { 2097 let gattServer: ble.GattServer = ble.createGattServer(); 2098 gattServer.on('connectionStateChange', Connected); 2099} catch (err) { 2100 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2101} 2102``` 2103 2104 2105### off('connectionStateChange') 2106 2107off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 2108 2109server端取消订阅BLE连接状态变化事件。 2110 2111**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2112 2113**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2114 2115**系统能力**：SystemCapability.Communication.Bluetooth.Core 2116 2117**参数：** 2118 2119| 参数名 | 类型 | 必填 | 说明 | 2120| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2121| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 2122| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅BLE连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 2123 2124**错误码**： 2125 2126以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2127 2128| 错误码ID | 错误信息 | 2129| -------- | ---------------------------- | 2130|201 | Permission denied. | 2131|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2132|801 | Capability not supported. | 2133 2134**示例：** 2135 2136```js 2137import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2138try { 2139 let gattServer: ble.GattServer = ble.createGattServer(); 2140 gattServer.off('connectionStateChange'); 2141} catch (err) { 2142 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 2143} 2144``` 2145 2146 2147### on('BLEMtuChange') 2148 2149on(type: 'BLEMtuChange', callback: Callback<number>): void 2150 2151server端订阅MTU状态变化事件。使用Callback异步回调。 2152 2153**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2154 2155**系统能力**：SystemCapability.Communication.Bluetooth.Core 2156 2157**参数：** 2158 2159| 参数名 | 类型 | 必填 | 说明 | 2160| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2161| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2162| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 2163 2164**错误码**： 2165 2166以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2167 2168| 错误码ID | 错误信息 | 2169| -------- | ---------------------------- | 2170|201 | Permission denied. | 2171|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2172|801 | Capability not supported. | 2173 2174**示例：** 2175 2176```js 2177import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2178try { 2179 let gattServer: ble.GattServer = ble.createGattServer(); 2180 gattServer.on('BLEMtuChange', (mtu: number) => { 2181 console.info('BLEMtuChange, mtu: ' + mtu); 2182 }); 2183} catch (err) { 2184 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2185} 2186``` 2187 2188 2189### off('BLEMtuChange') 2190 2191off(type: 'BLEMtuChange', callback?: Callback<number>): void 2192 2193server端取消订阅MTU状态变化事件。 2194 2195**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2196 2197**系统能力**：SystemCapability.Communication.Bluetooth.Core 2198 2199**参数：** 2200 2201| 参数名 | 类型 | 必填 | 说明 | 2202| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2203| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2204| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 2205 2206**错误码**： 2207 2208以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2209 2210| 错误码ID | 错误信息 | 2211| -------- | ---------------------------- | 2212|201 | Permission denied. | 2213|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2214|801 | Capability not supported. | 2215 2216**示例：** 2217 2218```js 2219import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2220try { 2221 let gattServer: ble.GattServer = ble.createGattServer(); 2222 gattServer.off('BLEMtuChange'); 2223} catch (err) { 2224 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2225} 2226``` 2227 2228 2229## GattClientDevice 2230 2231client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。 2232 2233 2234### connect 2235 2236connect(): void 2237 2238client端发起连接远端蓝牙低功耗设备。 2239 2240**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2241 2242**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2243 2244**系统能力**：SystemCapability.Communication.Bluetooth.Core 2245 2246**错误码**： 2247 2248以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2249 2250| 错误码ID | 错误信息 | 2251| -------- | ---------------------------- | 2252|201 | Permission denied. | 2253|801 | Capability not supported. | 2254|2900001 | Service stopped. | 2255|2900003 | Bluetooth disabled. | 2256|2900099 | Operation failed. | 2257 2258**示例：** 2259 2260```js 2261import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2262try { 2263 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2264 device.connect(); 2265} catch (err) { 2266 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2267} 2268``` 2269 2270 2271### disconnect 2272 2273disconnect(): void 2274 2275client端断开与远端蓝牙低功耗设备的连接。 2276 2277**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2278 2279**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2280 2281**系统能力**：SystemCapability.Communication.Bluetooth.Core 2282 2283**错误码**： 2284 2285以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2286 2287| 错误码ID | 错误信息 | 2288| -------- | ---------------------------- | 2289|201 | Permission denied. | 2290|801 | Capability not supported. | 2291|2900001 | Service stopped. | 2292|2900003 | Bluetooth disabled. | 2293|2900099 | Operation failed. | 2294 2295**示例：** 2296 2297```js 2298import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2299try { 2300 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2301 device.disconnect(); 2302} catch (err) { 2303 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2304} 2305``` 2306 2307 2308### close 2309 2310close(): void 2311 2312关闭客户端功能，注销client在协议栈的注册，调用该接口后[GattClientDevice](#gattclientdevice)实例将不能再使用。 2313 2314**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2315 2316**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2317 2318**系统能力**：SystemCapability.Communication.Bluetooth.Core 2319 2320**错误码**： 2321 2322以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2323 2324| 错误码ID | 错误信息 | 2325| -------- | ---------------------------- | 2326|201 | Permission denied. | 2327|801 | Capability not supported. | 2328|2900001 | Service stopped. | 2329|2900003 | Bluetooth disabled. | 2330|2900099 | Operation failed. | 2331 2332**示例：** 2333 2334```js 2335import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2336try { 2337 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2338 device.close(); 2339} catch (err) { 2340 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2341} 2342``` 2343 2344 2345### getDeviceName 2346 2347getDeviceName(callback: AsyncCallback<string>): void 2348 2349client获取远端蓝牙低功耗设备名。使用Callback异步回调。 2350 2351**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2352 2353**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2354 2355**系统能力**：SystemCapability.Communication.Bluetooth.Core 2356 2357**参数：** 2358 2359| 参数名 | 类型 | 必填 | 说明 | 2360| -------- | --------------------------- | ---- | ------------------------------- | 2361| callback | AsyncCallback<string> | 是 | client获取对端server设备名，通过注册回调函数获取。 | 2362 2363**错误码**： 2364 2365以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2366 2367| 错误码ID | 错误信息 | 2368| -------- | ---------------------------- | 2369|201 | Permission denied. | 2370|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2371|801 | Capability not supported. | 2372|2900001 | Service stopped. | 2373|2900099 | Operation failed. | 2374 2375**示例：** 2376 2377```js 2378import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2379// callback 2380try { 2381 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2382 gattClient.connect(); 2383 gattClient.getDeviceName((err: BusinessError, data: string)=> { 2384 console.info('device name err ' + JSON.stringify(err)); 2385 console.info('device name' + JSON.stringify(data)); 2386 }) 2387} catch (err) { 2388 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2389} 2390``` 2391 2392 2393### getDeviceName 2394 2395getDeviceName(): Promise<string> 2396 2397client获取远端蓝牙低功耗设备名。使用Promise异步回调。 2398 2399**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2400 2401**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2402 2403**系统能力**：SystemCapability.Communication.Bluetooth.Core 2404 2405**返回值：** 2406 2407| 类型 | 说明 | 2408| --------------------- | ---------------------------------- | 2409| Promise<string> | client获取对端server设备名，通过promise形式获取。 | 2410 2411**错误码**： 2412 2413以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2414 2415| 错误码ID | 错误信息 | 2416| -------- | ---------------------------- | 2417|201 | Permission denied. | 2418|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2419|801 | Capability not supported. | 2420|2900001 | Service stopped. | 2421|2900099 | Operation failed. | 2422 2423**示例：** 2424 2425```js 2426import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2427// promise 2428try { 2429 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2430 gattClient.connect(); 2431 gattClient.getDeviceName().then((data: string) => { 2432 console.info('device name' + JSON.stringify(data)); 2433 }) 2434} catch (err) { 2435 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2436} 2437``` 2438 2439 2440### getServices 2441 2442getServices(callback: AsyncCallback<Array<GattService>>): void 2443 2444client端获取蓝牙低功耗设备的所有服务，即服务发现。使用Callback异步回调。 2445 2446**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2447 2448**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2449 2450**系统能力**：SystemCapability.Communication.Bluetooth.Core 2451 2452**参数：** 2453 2454| 参数名 | 类型 | 必填 | 说明 | 2455| -------- | ---------------------------------------- | ---- | ------------------------ | 2456| callback | AsyncCallback<Array<[GattService](#gattservice)>> | 是 | client进行服务发现，通过注册回调函数获取。 | 2457 2458**错误码**： 2459 2460以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2461 2462| 错误码ID | 错误信息 | 2463| -------- | ---------------------------- | 2464|201 | Permission denied. | 2465|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 2466|801 | Capability not supported. | 2467|2900001 | Service stopped. | 2468|2900099 | Operation failed. | 2469 2470**示例：** 2471 2472```js 2473import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2474// callback 模式。 2475let getServices = (code: BusinessError, gattServices: Array<ble.GattService>) => { 2476 if (code && code.code != 0) { 2477 console.info('bluetooth code is ' + code.code); 2478 return; 2479 } 2480 let services: Array<ble.GattService> = gattServices; 2481 console.info('bluetooth services size is ', services.length); 2482 for (let i = 0; i < services.length; i++) { 2483 console.info('bluetooth serviceUuid is ' + services[i].serviceUuid); 2484 } 2485} 2486 2487try { 2488 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2489 device.connect(); 2490 device.getServices(getServices); 2491} catch (err) { 2492 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2493} 2494``` 2495 2496 2497### getServices 2498 2499getServices(): Promise<Array<GattService>> 2500 2501client端获取蓝牙低功耗设备的所有服务，即服务发现。使用Promise异步回调。 2502 2503**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2504 2505**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2506 2507**系统能力**：SystemCapability.Communication.Bluetooth.Core 2508 2509**返回值：** 2510 2511| 类型 | 说明 | 2512| ---------------------------------------- | --------------------------- | 2513| Promise<Array<[GattService](#gattservice)>> | client进行服务发现，通过promise形式获取。 | 2514 2515**错误码**： 2516 2517以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2518 2519| 错误码ID | 错误信息 | 2520| -------- | ---------------------------- | 2521|201 | Permission denied. | 2522|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2523|801 | Capability not supported. | 2524|2900001 | Service stopped. | 2525|2900099 | Operation failed. | 2526 2527**示例：** 2528 2529```js 2530import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2531// Promise 模式。 2532try { 2533 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2534 device.connect(); 2535 device.getServices().then((result: Array<ble.GattService>) => { 2536 console.info('getServices successfully:' + JSON.stringify(result)); 2537 }); 2538} catch (err) { 2539 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2540} 2541``` 2542 2543 2544### readCharacteristicValue 2545 2546readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void 2547 2548client端读取蓝牙低功耗设备特定服务的特征值。使用Callback异步回调。 2549 2550**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2551 2552**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2553 2554**系统能力**：SystemCapability.Communication.Bluetooth.Core 2555 2556**参数：** 2557 2558| 参数名 | 类型 | 必填 | 说明 | 2559| -------------- | ---------------------------------------- | ---- | ----------------------- | 2560| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 2561| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | 是 | client读取特征值，通过注册回调函数获取。 | 2562 2563**错误码**： 2564 2565以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2566 2567| 错误码ID | 错误信息 | 2568| -------- | ---------------------------- | 2569|201 | Permission denied. | 2570|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2571|801 | Capability not supported. | 2572|2900001 | Service stopped. | 2573|2901000 | Read forbidden. | 2574|2900099 | Operation failed. | 2575 2576**示例：** 2577 2578```js 2579import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2580function readCcc(code: BusinessError, BLECharacteristic: ble.BLECharacteristic) { 2581 if (code.code != 0) { 2582 return; 2583 } 2584 console.info('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); 2585 let value = new Uint8Array(BLECharacteristic.characteristicValue); 2586 console.info('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2587} 2588 2589let descriptors: Array<ble.BLEDescriptor> = []; 2590let bufferDesc = new ArrayBuffer(8); 2591let descV = new Uint8Array(bufferDesc); 2592descV[0] = 11; 2593let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2594characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2595descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2596descriptors[0] = descriptor; 2597 2598let bufferCCC = new ArrayBuffer(8); 2599let cccV = new Uint8Array(bufferCCC); 2600cccV[0] = 1; 2601let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2602characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2603characteristicValue: bufferCCC, descriptors:descriptors}; 2604 2605try { 2606 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2607 device.readCharacteristicValue(characteristic, readCcc); 2608} catch (err) { 2609 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2610} 2611``` 2612 2613 2614### readCharacteristicValue 2615 2616readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> 2617 2618client端读取蓝牙低功耗设备特定服务的特征值。使用Promise异步回调。 2619 2620**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2621 2622**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2623 2624**系统能力**：SystemCapability.Communication.Bluetooth.Core 2625 2626**参数：** 2627 2628| 参数名 | 类型 | 必填 | 说明 | 2629| -------------- | --------------------------------------- | ---- | -------- | 2630| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 2631 2632**返回值：** 2633 2634| 类型 | 说明 | 2635| ---------------------------------------- | -------------------------- | 2636| Promise<[BLECharacteristic](#blecharacteristic)> | client读取特征值，通过promise形式获取。 | 2637 2638**错误码**： 2639 2640以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2641 2642| 错误码ID | 错误信息 | 2643| -------- | ---------------------------- | 2644|201 | Permission denied. | 2645|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2646|801 | Capability not supported. | 2647|2900001 | Service stopped. | 2648|2901000 | Read forbidden. | 2649|2900099 | Operation failed. | 2650 2651**示例：** 2652 2653```js 2654import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2655let descriptors: Array<ble.BLEDescriptor> = []; 2656let bufferDesc = new ArrayBuffer(8); 2657let descV = new Uint8Array(bufferDesc); 2658descV[0] = 11; 2659let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2660characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2661descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2662descriptors[0] = descriptor; 2663 2664let bufferCCC = new ArrayBuffer(8); 2665let cccV = new Uint8Array(bufferCCC); 2666cccV[0] = 1; 2667let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2668characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2669characteristicValue: bufferCCC, descriptors:descriptors}; 2670 2671try { 2672 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2673 device.readCharacteristicValue(characteristic); 2674} catch (err) { 2675 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2676} 2677``` 2678 2679 2680### readDescriptorValue 2681 2682readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void 2683 2684client端读取蓝牙低功耗设备特定的特征包含的描述符。使用Callback异步回调。 2685 2686**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2687 2688**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2689 2690**系统能力**：SystemCapability.Communication.Bluetooth.Core 2691 2692**参数：** 2693 2694| 参数名 | 类型 | 必填 | 说明 | 2695| ---------- | ---------------------------------------- | ---- | ----------------------- | 2696| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 2697| callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | 是 | client读取描述符，通过注册回调函数获取。 | 2698 2699**错误码**： 2700 2701以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2702 2703| 错误码ID | 错误信息 | 2704| -------- | ---------------------------- | 2705|201 | Permission denied. | 2706|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2707|801 | Capability not supported. | 2708|2900001 | Service stopped. | 2709|2901000 | Read forbidden. | 2710|2900099 | Operation failed. | 2711 2712**示例：** 2713 2714```js 2715import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2716function readDesc(code: BusinessError, BLEDescriptor: ble.BLEDescriptor) { 2717 if (code.code != 0) { 2718 return; 2719 } 2720 console.info('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); 2721 let value = new Uint8Array(BLEDescriptor.descriptorValue); 2722 console.info('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2723} 2724 2725let bufferDesc = new ArrayBuffer(8); 2726let descV = new Uint8Array(bufferDesc); 2727descV[0] = 11; 2728let descriptor: ble.BLEDescriptor = { 2729 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2730 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2731 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2732 descriptorValue: bufferDesc 2733}; 2734try { 2735 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2736 device.readDescriptorValue(descriptor, readDesc); 2737} catch (err) { 2738 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2739} 2740``` 2741 2742 2743### readDescriptorValue 2744 2745readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> 2746 2747client端读取蓝牙低功耗设备特定的特征包含的描述符。使用Promise异步回调。 2748 2749**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2750 2751**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2752 2753**系统能力**：SystemCapability.Communication.Bluetooth.Core 2754 2755**参数：** 2756 2757| 参数名 | 类型 | 必填 | 说明 | 2758| ---------- | ------------------------------- | ---- | -------- | 2759| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 2760 2761**返回值：** 2762 2763| 类型 | 说明 | 2764| ---------------------------------------- | -------------------------- | 2765| Promise<[BLEDescriptor](#bledescriptor)> | client读取描述符，通过promise形式获取。 | 2766 2767**错误码**： 2768 2769以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2770 2771| 错误码ID | 错误信息 | 2772| -------- | ---------------------------- | 2773|201 | Permission denied. | 2774|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2775|801 | Capability not supported. | 2776|2900001 | Service stopped. | 2777|2901000 | Read forbidden. | 2778|2900099 | Operation failed. | 2779 2780**示例：** 2781 2782```js 2783import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2784let bufferDesc = new ArrayBuffer(8); 2785let descV = new Uint8Array(bufferDesc); 2786descV[0] = 11; 2787let descriptor: ble.BLEDescriptor = { 2788 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2789 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2790 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2791 descriptorValue: bufferDesc 2792}; 2793try { 2794 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2795 device.readDescriptorValue(descriptor); 2796} catch (err) { 2797 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2798} 2799``` 2800 2801 2802### writeCharacteristicValue 2803 2804writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void 2805 2806client端向低功耗蓝牙设备写入特定的特征值。使用Callback异步回调。 2807 2808**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2809 2810**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2811 2812**系统能力**：SystemCapability.Communication.Bluetooth.Core 2813 2814**参数：** 2815 2816| 参数名 | 类型 | 必填 | 说明 | 2817| -------------- | --------------------------------------- | ---- | ------------------- | 2818| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 2819| writeType | [GattWriteType](#gattwritetype) | 是 | 蓝牙设备特征的写入类型。 | 2820| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 2821 2822**错误码**： 2823 2824以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2825 2826| 错误码ID | 错误信息 | 2827| -------- | ---------------------------- | 2828|201 | Permission denied. | 2829|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2830|801 | Capability not supported. | 2831|2900001 | Service stopped. | 2832|2901001 | Write forbidden. | 2833|2900099 | Operation failed. | 2834 2835**示例：** 2836 2837```js 2838import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2839let descriptors: Array<ble.BLEDescriptor> = []; 2840let bufferDesc = new ArrayBuffer(8); 2841let descV = new Uint8Array(bufferDesc); 2842descV[0] = 11; 2843let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2844 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2845 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2846descriptors[0] = descriptor; 2847 2848let bufferCCC = new ArrayBuffer(8); 2849let cccV = new Uint8Array(bufferCCC); 2850cccV[0] = 1; 2851let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2852 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2853 characteristicValue: bufferCCC, descriptors:descriptors}; 2854function writeCharacteristicValueCallBack(code: BusinessError) { 2855 if (code != null) { 2856 return; 2857 } 2858 console.info('bluetooth writeCharacteristicValue success'); 2859} 2860try { 2861 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2862 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack); 2863} catch (err) { 2864 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2865} 2866``` 2867 2868 2869### writeCharacteristicValue 2870 2871writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> 2872 2873client端向低功耗蓝牙设备写入特定的特征值。使用Promise异步回调。 2874 2875**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2876 2877**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2878 2879**系统能力**：SystemCapability.Communication.Bluetooth.Core 2880 2881**参数：** 2882 2883| 参数名 | 类型 | 必填 | 说明 | 2884| -------------- | --------------------------------------- | ---- | ------------------- | 2885| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 2886| writeType | [GattWriteType](#gattwritetype) | 是 | 蓝牙设备特征的写入类型。 | 2887 2888**返回值：** 2889 2890| 类型 | 说明 | 2891| ---------------------------------------- | -------------------------- | 2892| Promise<void> | client读取描述符，通过promise形式获取。 | 2893 2894**错误码**： 2895 2896以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2897 2898| 错误码ID | 错误信息 | 2899| -------- | ---------------------------- | 2900|201 | Permission denied. | 2901|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2902|801 | Capability not supported. | 2903|2900001 | Service stopped. | 2904|2901001 | Write forbidden. | 2905|2900099 | Operation failed. | 2906 2907**示例：** 2908 2909```js 2910import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2911let descriptors: Array<ble.BLEDescriptor> = []; 2912let bufferDesc = new ArrayBuffer(8); 2913let descV = new Uint8Array(bufferDesc); 2914descV[0] = 11; 2915let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2916 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2917 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2918descriptors[0] = descriptor; 2919 2920let bufferCCC = new ArrayBuffer(8); 2921let cccV = new Uint8Array(bufferCCC); 2922cccV[0] = 1; 2923let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2924 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2925 characteristicValue: bufferCCC, descriptors:descriptors}; 2926try { 2927 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2928 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE); 2929} catch (err) { 2930 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2931} 2932``` 2933 2934 2935### writeDescriptorValue 2936 2937writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void 2938 2939client端向低功耗蓝牙设备特定的描述符写入二进制数据。使用Callback异步回调。 2940 2941**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2942 2943**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2944 2945**系统能力**：SystemCapability.Communication.Bluetooth.Core 2946 2947**参数：** 2948 2949| 参数名 | 类型 | 必填 | 说明 | 2950| ---------- | ------------------------------- | ---- | ------------------ | 2951| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 2952| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 2953 2954**错误码**： 2955 2956以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 2957 2958| 错误码ID | 错误信息 | 2959| -------- | ---------------------------- | 2960|201 | Permission denied. | 2961|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 2962|801 | Capability not supported. | 2963|2900001 | Service stopped. | 2964|2901001 | Write forbidden. | 2965|2900099 | Operation failed. | 2966 2967**示例：** 2968 2969```js 2970import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 2971let bufferDesc = new ArrayBuffer(8); 2972let descV = new Uint8Array(bufferDesc); 2973descV[0] = 22; 2974let descriptor: ble.BLEDescriptor = { 2975 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2976 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2977 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2978 descriptorValue: bufferDesc 2979}; 2980try { 2981 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2982 device.writeDescriptorValue(descriptor, (err: BusinessError) => { 2983 if (err) { 2984 console.info('notifyCharacteristicChanged callback failed'); 2985 } else { 2986 console.info('notifyCharacteristicChanged callback successful'); 2987 } 2988 }); 2989} catch (err) { 2990 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2991} 2992``` 2993 2994 2995### writeDescriptorValue 2996 2997writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> 2998 2999client端向低功耗蓝牙设备特定的描述符写入二进制数据。使用Promise异步回调。 3000 3001**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3002 3003**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3004 3005**系统能力**：SystemCapability.Communication.Bluetooth.Core 3006 3007**参数：** 3008 3009| 参数名 | 类型 | 必填 | 说明 | 3010| ---------- | ------------------------------- | ---- | ------------------ | 3011| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 3012 3013**返回值：** 3014 3015| 类型 | 说明 | 3016| ---------------------------------------- | -------------------------- | 3017| Promise<void> | client读取描述符，通过promise形式获取。 | 3018 3019**错误码**： 3020 3021以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3022 3023| 错误码ID | 错误信息 | 3024| -------- | ---------------------------- | 3025|201 | Permission denied. | 3026|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3027|801 | Capability not supported. | 3028|2900001 | Service stopped. | 3029|2901001 | Write forbidden. | 3030|2900099 | Operation failed. | 3031 3032**示例：** 3033 3034```js 3035import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3036let bufferDesc = new ArrayBuffer(8); 3037let descV = new Uint8Array(bufferDesc); 3038descV[0] = 22; 3039let descriptor: ble.BLEDescriptor = { 3040 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3041 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3042 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 3043 descriptorValue: bufferDesc 3044}; 3045try { 3046 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3047 device.writeDescriptorValue(descriptor).then(() => { 3048 console.info('writeDescriptorValue promise success'); 3049 }); 3050} catch (err) { 3051 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3052} 3053``` 3054 3055 3056### getRssiValue 3057 3058getRssiValue(callback: AsyncCallback<number>): void 3059 3060client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。使用Callback异步回调。 3061 3062**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3063 3064**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3065 3066**系统能力**：SystemCapability.Communication.Bluetooth.Core 3067 3068**参数：** 3069 3070| 参数名 | 类型 | 必填 | 说明 | 3071| -------- | --------------------------- | ---- | ------------------------------ | 3072| callback | AsyncCallback<number> | 是 | 返回信号强度。单位 dBm，通过注册回调函数获取。 | 3073 3074**错误码**： 3075 3076以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3077 3078| 错误码ID | 错误信息 | 3079| -------- | ---------------------------- | 3080|201 | Permission denied. | 3081|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3082|801 | Capability not supported. | 3083|2900099 | Operation failed. | 3084 3085**示例：** 3086 3087```js 3088import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3089// callback 3090try { 3091 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 3092 gattClient.connect(); 3093 let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> { 3094 console.info('rssi err ' + JSON.stringify(err)); 3095 console.info('rssi value' + JSON.stringify(data)); 3096 }) 3097} catch (err) { 3098 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3099} 3100``` 3101 3102 3103### getRssiValue 3104 3105getRssiValue(): Promise<number> 3106 3107client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。使用Promise异步回调。 3108 3109**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3110 3111**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3112 3113**系统能力**：SystemCapability.Communication.Bluetooth.Core 3114 3115**返回值：** 3116 3117| 类型 | 说明 | 3118| --------------------- | --------------------------------- | 3119| Promise<number> | 返回信号强度。单位 dBm，通过promise形式获取。 | 3120 3121**错误码**： 3122 3123以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3124 3125| 错误码ID | 错误信息 | 3126| -------- | ---------------------------- | 3127|201 | Permission denied. | 3128|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 3129|801 | Capability not supported. | 3130|2900099 | Operation failed. | 3131 3132**示例：** 3133 3134```js 3135import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3136// promise 3137try { 3138 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 3139 gattClient.getRssiValue().then((data: number) => { 3140 console.info('rssi' + JSON.stringify(data)); 3141 }) 3142} catch (err) { 3143 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3144} 3145``` 3146 3147 3148### setBLEMtuSize 3149 3150setBLEMtuSize(mtu: number): void 3151 3152client协商远端蓝牙低功耗设备的最大传输单元(Maximum Transmission Unit, MTU)，调用[connect](#connect)接口连接成功后才能使用。 3153> **说明：** 3154> - 该接口通过[on('BLEMtuChange')](#onblemtuchange-1)，订阅client端MTU状态变化事件。 3155 3156**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3157 3158**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3159 3160**系统能力**：SystemCapability.Communication.Bluetooth.Core 3161 3162**参数：** 3163 3164| 参数名 | 类型 | 必填 | 说明 | 3165| ---- | ------ | ---- | -------------- | 3166| mtu | number | 是 | 设置范围为22~512字节。 | 3167 3168**错误码**： 3169 3170以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3171 3172| 错误码ID | 错误信息 | 3173| -------- | ---------------------------- | 3174|201 | Permission denied. | 3175|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3176|801 | Capability not supported. | 3177|2900001 | Service stopped. | 3178|2900099 | Operation failed. | 3179 3180**示例：** 3181 3182```js 3183import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3184try { 3185 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3186 device.setBLEMtuSize(128); 3187} catch (err) { 3188 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3189} 3190``` 3191 3192 3193### setCharacteristicChangeNotification 3194 3195setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 3196 3197向服务端发送设置通知此特征值请求。使用Callback异步回调。 3198 3199**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3200 3201**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3202 3203**系统能力**：SystemCapability.Communication.Bluetooth.Core 3204 3205**参数：** 3206 3207| 参数名 | 类型 | 必填 | 说明 | 3208| -------------- | --------------------------------------- | ---- | ----------------------------- | 3209| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3210| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3211| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 3212 3213**错误码**： 3214 3215以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3216 3217| 错误码ID | 错误信息 | 3218| -------- | ---------------------------- | 3219|201 | Permission denied. | 3220|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3221|801 | Capability not supported. | 3222|2900001 | Service stopped. | 3223|2900099 | Operation failed. | 3224 3225**示例：** 3226 3227```js 3228import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3229// 创建descriptors。 3230let descriptors: Array<ble.BLEDescriptor> = []; 3231let arrayBuffer = new ArrayBuffer(8); 3232let descV = new Uint8Array(arrayBuffer); 3233descV[0] = 11; 3234let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3235 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3236 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3237descriptors[0] = descriptor; 3238let arrayBufferC = new ArrayBuffer(8); 3239let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3240 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3241try { 3242 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3243 device.setCharacteristicChangeNotification(characteristic, false, (err: BusinessError) => { 3244 if (err) { 3245 console.info('notifyCharacteristicChanged callback failed'); 3246 } else { 3247 console.info('notifyCharacteristicChanged callback successful'); 3248 } 3249 }); 3250} catch (err) { 3251 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3252} 3253 3254``` 3255 3256 3257### setCharacteristicChangeNotification 3258 3259setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> 3260 3261向服务端发送设置通知此特征值请求。使用Promise异步回调。 3262 3263**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3264 3265**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3266 3267**系统能力**：SystemCapability.Communication.Bluetooth.Core 3268 3269**参数：** 3270 3271| 参数名 | 类型 | 必填 | 说明 | 3272| -------------- | --------------------------------------- | ---- | ----------------------------- | 3273| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3274| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3275 3276**返回值：** 3277 3278| 类型 | 说明 | 3279| ---------------------------------------- | -------------------------- | 3280| Promise<void> | 返回Promise对象。 | 3281 3282**错误码**： 3283 3284以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3285 3286| 错误码ID | 错误信息 | 3287| -------- | ---------------------------- | 3288|201 | Permission denied. | 3289|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3290|801 | Capability not supported. | 3291|2900001 | Service stopped. | 3292|2900099 | Operation failed. | 3293 3294**示例：** 3295 3296```js 3297import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3298// 创建descriptors。 3299let descriptors: Array<ble.BLEDescriptor> = []; 3300let arrayBuffer = new ArrayBuffer(8); 3301let descV = new Uint8Array(arrayBuffer); 3302descV[0] = 11; 3303let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3304 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3305 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3306descriptors[0] = descriptor; 3307let arrayBufferC = new ArrayBuffer(8); 3308let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3309 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3310try { 3311 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3312 device.setCharacteristicChangeNotification(characteristic, false); 3313} catch (err) { 3314 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3315} 3316 3317``` 3318 3319 3320### setCharacteristicChangeIndication 3321 3322setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 3323 3324向服务端发送设置通知此特征值请求，需要对端设备的回复。使用Callback异步回调。 3325 3326**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3327 3328**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3329 3330**系统能力**：SystemCapability.Communication.Bluetooth.Core 3331 3332**参数：** 3333 3334| 参数名 | 类型 | 必填 | 说明 | 3335| -------------- | --------------------------------------- | ---- | ----------------------------- | 3336| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3337| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3338| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 3339 3340**错误码**： 3341 3342以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3343 3344| 错误码ID | 错误信息 | 3345| -------- | ---------------------------- | 3346|201 | Permission denied. | 3347|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3348|801 | Capability not supported. | 3349|2900001 | Service stopped. | 3350|2900099 | Operation failed. | 3351 3352**示例：** 3353 3354```js 3355import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3356// 创建descriptors。 3357let descriptors: Array<ble.BLEDescriptor> = []; 3358let arrayBuffer = new ArrayBuffer(8); 3359let descV = new Uint8Array(arrayBuffer); 3360descV[0] = 11; 3361let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3362 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3363 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3364descriptors[0] = descriptor; 3365let arrayBufferC = new ArrayBuffer(8); 3366let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3367 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3368try { 3369 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3370 device.setCharacteristicChangeIndication(characteristic, false, (err: BusinessError) => { 3371 if (err) { 3372 console.info('notifyCharacteristicChanged callback failed'); 3373 } else { 3374 console.info('notifyCharacteristicChanged callback successful'); 3375 } 3376 }); 3377} catch (err) { 3378 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3379} 3380 3381``` 3382 3383 3384### setCharacteristicChangeIndication 3385 3386setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> 3387 3388向服务端发送设置通知此特征值请求，需要对端设备的回复。使用Promise异步回调。 3389 3390**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3391 3392**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3393 3394**系统能力**：SystemCapability.Communication.Bluetooth.Core 3395 3396**参数：** 3397 3398| 参数名 | 类型 | 必填 | 说明 | 3399| -------------- | --------------------------------------- | ---- | ----------------------------- | 3400| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 3401| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 3402 3403**返回值：** 3404 3405| 类型 | 说明 | 3406| ---------------------------------------- | -------------------------- | 3407| Promise<void> | 返回Promise对象。 | 3408 3409**错误码**： 3410 3411以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3412 3413| 错误码ID | 错误信息 | 3414| -------- | ---------------------------- | 3415|201 | Permission denied. | 3416|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3417|801 | Capability not supported. | 3418|2900001 | Service stopped. | 3419|2900099 | Operation failed. | 3420 3421**示例：** 3422 3423```js 3424import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3425// 创建descriptors。 3426let descriptors: Array<ble.BLEDescriptor> = []; 3427let arrayBuffer = new ArrayBuffer(8); 3428let descV = new Uint8Array(arrayBuffer); 3429descV[0] = 11; 3430let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3431 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3432 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3433descriptors[0] = descriptor; 3434let arrayBufferC = new ArrayBuffer(8); 3435let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3436 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3437try { 3438 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3439 device.setCharacteristicChangeIndication(characteristic, false); 3440} catch (err) { 3441 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3442} 3443 3444``` 3445 3446 3447### on('BLECharacteristicChange') 3448 3449on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void 3450 3451订阅蓝牙低功耗设备的特征值变化事件。需要先调用[setCharacteristicChangeNotification](#setcharacteristicchangenotification)接口或[setCharacteristicChangeIndication](#setcharacteristicchangeindication)接口才能接收server端的通知。使用Callback异步回调。 3452 3453**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3454 3455**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3456 3457**系统能力**：SystemCapability.Communication.Bluetooth.Core 3458 3459**参数：** 3460 3461| 参数名 | 类型 | 必填 | 说明 | 3462| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3463| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 3464| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 是 | 表示蓝牙低功耗设备的特征值变化事件的回调函数。 | 3465 3466**错误码**： 3467 3468以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3469 3470| 错误码ID | 错误信息 | 3471| -------- | ---------------------------- | 3472|201 | Permission denied. | 3473|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3474|801 | Capability not supported. | 3475 3476**示例：** 3477 3478```js 3479import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3480function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) { 3481 let serviceUuid: string = characteristicChangeReq.serviceUuid; 3482 let characteristicUuid: string = characteristicChangeReq.characteristicUuid; 3483 let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue); 3484} 3485try { 3486 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3487 device.on('BLECharacteristicChange', CharacteristicChange); 3488} catch (err) { 3489 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3490} 3491``` 3492 3493 3494### off('BLECharacteristicChange') 3495 3496off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void 3497 3498取消订阅蓝牙低功耗设备的特征值变化事件。 3499 3500**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3501 3502**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3503 3504**系统能力**：SystemCapability.Communication.Bluetooth.Core 3505 3506**参数：** 3507 3508| 参数名 | 类型 | 必填 | 说明 | 3509| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3510| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 3511| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 否 | 表示取消订阅蓝牙低功耗设备的特征值变化事件。不填该参数则取消订阅该type对应的所有回调。 | 3512 3513**错误码**： 3514 3515以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3516 3517| 错误码ID | 错误信息 | 3518| -------- | ---------------------------- | 3519|201 | Permission denied. | 3520|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3521|801 | Capability not supported. | 3522 3523**示例：** 3524 3525```js 3526import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3527try { 3528 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3529 device.off('BLECharacteristicChange'); 3530} catch (err) { 3531 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3532} 3533``` 3534 3535 3536### on('BLEConnectionStateChange') 3537 3538on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void 3539 3540client端订阅蓝牙低功耗设备的连接状态变化事件。使用Callback异步回调。 3541 3542**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3543 3544**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3545 3546**系统能力**：SystemCapability.Communication.Bluetooth.Core 3547 3548**参数：** 3549 3550| 参数名 | 类型 | 必填 | 说明 | 3551| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3552| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 3553| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示连接状态，已连接或断开。 | 3554 3555**错误码**： 3556 3557以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3558 3559| 错误码ID | 错误信息 | 3560| -------- | ---------------------------- | 3561|201 | Permission denied. | 3562|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3563|801 | Capability not supported. | 3564 3565**示例：** 3566 3567```js 3568import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3569function ConnectStateChanged(state: ble.BLEConnectionChangeState) { 3570 console.info('bluetooth connect state changed'); 3571 let connectState: ble.ProfileConnectionState = state.state; 3572} 3573try { 3574 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3575 device.on('BLEConnectionStateChange', ConnectStateChanged); 3576} catch (err) { 3577 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3578} 3579``` 3580 3581 3582### off('BLEConnectionStateChange') 3583 3584off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 3585 3586取消订阅蓝牙低功耗设备的连接状态变化事件。 3587 3588**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3589 3590**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3591 3592**系统能力**：SystemCapability.Communication.Bluetooth.Core 3593 3594**参数：** 3595 3596| 参数名 | 类型 | 必填 | 说明 | 3597| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3598| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 3599| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅蓝牙低功耗设备的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 3600 3601**错误码**： 3602 3603以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3604 3605| 错误码ID | 错误信息 | 3606| -------- | ---------------------------- | 3607|201 | Permission denied. | 3608|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3609|801 | Capability not supported. | 3610 3611**示例：** 3612 3613```js 3614import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3615try { 3616 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3617 device.off('BLEConnectionStateChange'); 3618} catch (err) { 3619 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3620} 3621``` 3622 3623 3624### on('BLEMtuChange') 3625 3626on(type: 'BLEMtuChange', callback: Callback<number>): void 3627 3628client端订阅MTU状态变化事件。使用Callback异步回调。 3629 3630**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3631 3632**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3633 3634**系统能力**：SystemCapability.Communication.Bluetooth.Core 3635 3636**参数：** 3637 3638| 参数名 | 类型 | 必填 | 说明 | 3639| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3640| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 3641| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 3642 3643**错误码**： 3644 3645以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3646 3647| 错误码ID | 错误信息 | 3648| -------- | ---------------------------- | 3649|201 | Permission denied. | 3650|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3651|801 | Capability not supported. | 3652 3653**示例：** 3654 3655```js 3656import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3657try { 3658 let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3659 gattClient.on('BLEMtuChange', (mtu: number) => { 3660 console.info('BLEMtuChange, mtu: ' + mtu); 3661 }); 3662} catch (err) { 3663 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3664} 3665``` 3666 3667 3668### off('BLEMtuChange') 3669 3670off(type: 'BLEMtuChange', callback?: Callback<number>): void 3671 3672client端取消订阅MTU状态变化事件。 3673 3674**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3675 3676**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3677 3678**系统能力**：SystemCapability.Communication.Bluetooth.Core 3679 3680**参数：** 3681 3682| 参数名 | 类型 | 必填 | 说明 | 3683| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3684| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 3685| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 3686 3687**错误码**： 3688 3689以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3690 3691| 错误码ID | 错误信息 | 3692| -------- | ---------------------------- | 3693|201 | Permission denied. | 3694|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3695|801 | Capability not supported. | 3696 3697**示例：** 3698 3699```js 3700import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3701try { 3702 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3703 device.off('BLEMtuChange'); 3704} catch (err) { 3705 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3706} 3707``` 3708 3709## ble.createBleScanner<sup>15+</sup> 3710 3711createBleScanner(): BleScanner 3712 3713**原子化服务API**: 从API version 15开始，该接口支持在原子化服务中使用。 3714 3715**系统能力**：SystemCapability.Communication.Bluetooth.Core 3716 3717**返回值：** 3718 3719| 类型 | 说明 | 3720| ------------ | ------------- | 3721| [BleScanner](#blescanner15) | 返回一个BleScanner的实例。 | 3722 3723**示例：** 3724 3725```js 3726import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3727import { ble } from '@kit.ConnectivityKit'; 3728let bleScanner: ble.BleScanner = ble.createBleScanner(); 3729console.info('create bleScanner success'); 3730``` 3731 3732## BleScanner<sup>15+</sup> 3733 3734BLE多路扫描类，使用BleScanner类中的方法之前需要创建该类的实例进行操作，通过createBleScanner()方法构造此实例。 3735 3736### startScan<sup>15+</sup> 3737 3738startScan(filters: Array<ScanFilter>, options?: ScanOptions): Promise<void> 3739 3740发起BLE扫描流程，使用Promise异步回调。 3741 3742**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3743 3744**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3745 3746**系统能力**：SystemCapability.Communication.Bluetooth.Core 3747 3748**参数：** 3749 3750| 参数名 | 类型 | 必填 | 说明 | 3751| ------- | -------------------------------------- | ---- | ----------------------------------- | 3752| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，符合过滤条件的设备会被保留。如果不使用过滤的方式，该参数设置为null。 | 3753| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的可选参数配置。 | 3754 3755**错误码**： 3756 3757以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3758 3759| 错误码ID | 错误信息 | 3760| -------- | ---------------------------- | 3761|201 | Permission denied. | 3762|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3763|801 | Capability not supported. | 3764|2900001 | Service stopped. | 3765|2900003 | Bluetooth disabled. | 3766|2900009 | Fails to start scan as it is out of hardware resources. | 3767|2900099 | Operation failed. | 3768|2902050 | Failed to start scan as Ble scan is already started by the app.| 3769 3770**示例：** 3771 3772```js 3773import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3774import { ble } from '@kit.ConnectivityKit'; 3775let bleScanner: ble.BleScanner = ble.createBleScanner(); 3776function onReceiveEvent(scanReport: ble.ScanReport) { 3777 console.info('BLE scan device find result = '+ JSON.stringify(scanReport)); 3778} 3779try { 3780 bleScanner.on("BLEDeviceFind", onReceiveEvent); 3781 let scanFilter: ble.ScanFilter = { 3782 deviceId:"XX:XX:XX:XX:XX:XX", 3783 name:"test", 3784 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 3785 }; 3786 let scanOptions: ble.ScanOptions = { 3787 interval: 500, 3788 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 3789 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE, 3790 reportMode: ble.ScanReportMode.FENCE_SENSITIVITY_LOW 3791 } 3792 bleScanner.startScan([scanFilter],scanOptions); 3793 console.info('startScan success'); 3794} catch (err) { 3795 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3796} 3797``` 3798 3799### stopScan<sup>15+</sup> 3800 3801stopScan(): Promise<void> 3802 3803停止BLE扫描流程。 3804 3805**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3806 3807**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3808 3809**系统能力**：SystemCapability.Communication.Bluetooth.Core 3810 3811**错误码**： 3812 3813以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3814 3815| 错误码ID | 错误信息 | 3816| -------- | ---------------------------- | 3817|201 | Permission denied. | 3818|801 | Capability not supported. | 3819|2900001 | Service stopped. | 3820|2900003 | Bluetooth disabled. | 3821|2900099 | Operation failed. | 3822 3823**示例：** 3824 3825```js 3826import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3827import { ble } from '@kit.ConnectivityKit'; 3828let bleScanner: ble.BleScanner = ble.createBleScanner(); 3829try { 3830 bleScanner.stopScan(); 3831 console.info('startScan success'); 3832} catch (err) { 3833 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3834} 3835``` 3836 3837### on('BLEDeviceFind')<sup>15+</sup> 3838 3839on(type: 'BLEDeviceFind', callback: Callback<ScanReport>): void 3840 3841订阅BLE设备发现上报事件。使用Callback异步回调。 3842 3843**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3844 3845**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3846 3847**系统能力**：SystemCapability.Communication.Bluetooth.Core 3848 3849**参数：** 3850 3851| 参数名 | 类型 | 必填 | 说明 | 3852| -------- | ---------------------------------------- | ---- | ----------------------------------- | 3853| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 3854| callback | Callback<[ScanReport](#scanreport15)> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 3855 3856**错误码**： 3857 3858以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3859 3860| 错误码ID | 错误信息 | 3861| -------- | ---------------------------- | 3862|201 | Permission denied. | 3863|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3864|801 | Capability not supported. | 3865|2900099 | Operation failed. | 3866 3867**示例：** 3868 3869```js 3870import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3871import { ble } from '@kit.ConnectivityKit'; 3872function onReceiveEvent(scanReport: ble.ScanReport) { 3873 console.info('bluetooth device find = '+ JSON.stringify(scanReport)); 3874} 3875let bleScanner: ble.BleScanner = ble.createBleScanner(); 3876try { 3877 bleScanner.on('BLEDeviceFind', onReceiveEvent); 3878} catch (err) { 3879 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3880} 3881``` 3882 3883### off('BLEDeviceFind')<sup>15+</sup> 3884 3885off(type: 'BLEDeviceFind', callback?: Callback<ScanReport>): void 3886 3887取消订阅BLE设备发现上报事件。 3888 3889**需要权限**：ohos.permission.ACCESS_BLUETOOTH 3890 3891**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 3892 3893**系统能力**：SystemCapability.Communication.Bluetooth.Core 3894 3895**参数：** 3896 3897| 参数名 | 类型 | 必填 | 说明 | 3898| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3899| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 3900| callback | Callback<[ScanReport](#scanreport15)> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 3901 3902**错误码**： 3903 3904以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 3905 3906| 错误码ID | 错误信息 | 3907| -------- | ---------------------------- | 3908|201 | Permission denied. | 3909|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 3910|801 | Capability not supported. | 3911|2900099 | Operation failed. | 3912 3913**示例：** 3914 3915```js 3916import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 3917import { ble } from '@kit.ConnectivityKit'; 3918function onReceiveEvent(scanReport: ble.ScanReport) { 3919 console.info('bluetooth device find = '+ JSON.stringify(scanReport)); 3920} 3921let bleScanner: ble.BleScanner = ble.createBleScanner(); 3922try { 3923 bleScanner.on('BLEDeviceFind', onReceiveEvent); 3924 bleScanner.off('BLEDeviceFind', onReceiveEvent); 3925} catch (err) { 3926 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3927} 3928``` 3929 3930## GattService 3931 3932描述service的接口参数定义。 3933 3934**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3935 3936**系统能力**：SystemCapability.Communication.Bluetooth.Core 3937 3938| 名称 | 类型 | 可读 | 可写 | 说明 | 3939| --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3940| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3941| isPrimary | boolean | 是 | 是 | 如果是主服务设置为true，否则设置为false。 | 3942| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | 是 | 是 | 当前服务包含的特征列表。 | 3943| includeServices | Array<[GattService](#gattservice)> | 是 | 是 | 当前服务依赖的其它服务。 | 3944 3945 3946## BLECharacteristic 3947 3948描述characteristic的接口参数定义 。 3949 3950**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3951 3952**系统能力**：SystemCapability.Communication.Bluetooth.Core 3953 3954| 名称 | 类型 | 可读 | 可写 | 说明 | 3955| ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3956| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3957| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3958| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 3959| descriptors | Array<[BLEDescriptor](#bledescriptor)> | 是 | 是 | 特定特征的描述符列表。 | 3960| properties | [GattProperties](#gattproperties) | 是 | 是 | 特定特征的属性描述。 | 3961 3962 3963## BLEDescriptor 3964 3965描述descriptor的接口参数定义。 3966 3967**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3968 3969**系统能力**：SystemCapability.Communication.Bluetooth.Core 3970 3971| 名称 | 类型 | 可读 | 可写 | 说明 | 3972| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 3973| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3974| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3975| descriptorUuid | string | 是 | 是 | 描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 3976| descriptorValue | ArrayBuffer | 是 | 是 | 描述符对应的二进制值。 | 3977 3978 3979## NotifyCharacteristic 3980 3981描述server端特征值变化时发送的特征通知参数定义。 3982 3983**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 3984 3985**系统能力**：SystemCapability.Communication.Bluetooth.Core 3986 3987| 名称 | 类型 | 可读 | 可写 | 说明 | 3988| ------------------- | ----------- | ---- | ---- | ---------------------------------------- | 3989| serviceUuid | string | 是 | 是 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 3990| characteristicUuid | string | 是 | 是 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 3991| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 3992| confirm | boolean | 是 | 是 | 如果是indication，对端需要回复确认，则设置为true。<br>如果是notification，对端不需要回复确认，则设置为false。 | 3993 3994 3995## CharacteristicReadRequest 3996 3997描述server端订阅后收到的特征值读请求事件参数结构。 3998 3999**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4000 4001**系统能力**：SystemCapability.Communication.Bluetooth.Core 4002 4003| 名称 | 类型 | 可读 | 可写 | 说明 | 4004| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 4005| deviceId | string | 是 | 否 | 表示发送特征值读请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4006| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4007| offset | number | 是 | 否 | 表示读特征值数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 4008| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4009| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4010 4011 4012## CharacteristicWriteRequest 4013 4014描述server端订阅后收到的特征值写请求事件参数结构。 4015 4016**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4017 4018**系统能力**：SystemCapability.Communication.Bluetooth.Core 4019 4020| 名称 | 类型 | 可读 | 可写 | 说明 | 4021| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 4022| deviceId | string | 是 | 否 | 表示发送特征值写请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4023| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4024| offset | number | 是 | 否 | 表示写特征值数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 4025| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。true表示立即执行。 | 4026| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。true表示需要回复。 | 4027| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 4028| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4029| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4030 4031 4032## DescriptorReadRequest 4033 4034描述server端订阅后收到的描述符读请求事件参数结构。 4035 4036**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4037 4038**系统能力**：SystemCapability.Communication.Bluetooth.Core 4039 4040| 名称 | 类型 | 可读 | 可写 | 说明 | 4041| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 4042| deviceId | string | 是 | 否 | 表示发送描述符读请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4043| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4044| offset | number | 是 | 否 | 表示读描述符数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 4045| descriptorUuid | string | 是 | 否 | 表示描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 4046| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4047| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4048 4049 4050## DescriptorWriteRequest 4051 4052描述server端订阅后收到的描述符写请求事件参数结构。 4053 4054**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4055 4056**系统能力**：SystemCapability.Communication.Bluetooth.Core 4057 4058| 名称 | 类型 | 可读 | 可写 | 说明 | 4059| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 4060| deviceId | string | 是 | 否 | 表示发送描述符写请求的远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4061| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 4062| offset | number | 是 | 否 | 表示写描述符数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 4063| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | 4064| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | 4065| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 4066| descriptorUuid | string | 是 | 否 | 表示描述符(descriptor)的UUID。例如：00002902-0000-1000-8000-00805f9b34fb。 | 4067| characteristicUuid | string | 是 | 否 | 特定特征(characteristic)的UUID。例如：00002a11-0000-1000-8000-00805f9b34fb。 | 4068| serviceUuid | string | 是 | 否 | 特定服务(service)的UUID。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4069 4070 4071## ServerResponse 4072 4073描述server端回复client端读/写请求的响应参数结构。 4074 4075**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4076 4077**系统能力**：SystemCapability.Communication.Bluetooth.Core 4078 4079| 名称 | 类型 | 可读 | 可写 | 说明 | 4080| -------- | ----------- | ---- | ---- | -------------------------------------- | 4081| deviceId | string | 是 | 否 | 表示远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4082| transId | number | 是 | 否 | 表示请求的传输ID，与订阅的读/写请求事件携带的ID保持一致。 | 4083| status | number | 是 | 否 | 表示响应的状态，设置为0即可，表示正常。 | 4084| offset | number | 是 | 否 | 表示请求的读/写起始位置，与订阅的读/写请求事件携带的offset保持一致。 | 4085| value | ArrayBuffer | 是 | 否 | 表示回复响应的二进制数据。 | 4086 4087 4088## BLEConnectionChangeState 4089 4090描述Gatt profile连接状态。 4091 4092**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4093 4094**系统能力**：SystemCapability.Communication.Bluetooth.Core 4095 4096| 名称 | 类型 | 可读 | 可写 | 说明 | 4097| -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | 4098| deviceId | string | 是 | 否 | 表示远端设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4099| state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 是 | 是 | 表示BLE连接状态的枚举。 | 4100 4101 4102## ScanResult 4103 4104扫描结果上报数据。 4105 4106**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4107 4108**系统能力**：SystemCapability.Communication.Bluetooth.Core 4109 4110| 名称 | 类型 | 可读 | 可写 | 说明 | 4111| -------- | ----------- | ---- | ---- | ---------------------------------- | 4112| deviceId | string | 是 | 否 | 表示扫描到的设备地址。例如："XX:XX:XX:XX:XX:XX"。<br>基于信息安全考虑，此处获取的设备地址为随机MAC地址。<br>- 配对成功后，该地址不会变更。<br>- 已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。 | 4113| rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | 4114| data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | 4115| deviceName | string | 是 | 否 | 表示扫描到的设备名称。 | 4116| connectable | boolean | 是 | 否 | 表示扫描到的设备是否可连接。true表示可连接，false表示不可连接。 | 4117 4118 4119## AdvertiseSetting 4120 4121描述蓝牙低功耗设备发送广播的参数。 4122 4123**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4124 4125**系统能力**：SystemCapability.Communication.Bluetooth.Core 4126 4127| 名称 | 类型 | 可读 | 可写 | 说明 | 4128| ----------- | ------- | ---- | ---- | ---------------------------------------- | 4129| interval | number | 是 | 是 | 表示广播间隔。<br>最小值设置32个slot表示20ms，最大值设置16777215个slot，默认值设置为1600个slot表示1s。(传统广播模式下最大值为16384个slot表示10.24s) | 4130| txPower | number | 是 | 是 | 表示发送功率。<br>最小值设置-127，最大值设置1，默认值设置-7，单位dbm。<br>推荐值：高档(1)，中档(-7)，低档(-15)。 | 4131| connectable | boolean | 是 | 是 | 表示是否是可连接广播。<br>默认值设置为true，表示可连接。false表示不可连接。 | 4132 4133 4134## AdvertiseData 4135 4136描述BLE广播数据包的内容，广播包数据长度为31个字节。 4137 4138**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4139 4140**系统能力**：SystemCapability.Communication.Bluetooth.Core 4141 4142| 名称 | 类型 | 可读 | 可写 | 说明 | 4143| --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | 4144| serviceUuids | Array<string> | 是 | 是 | 表示要广播的服务 UUID 列表。 | 4145| manufactureData | Array<[ManufactureData](#manufacturedata)> | 是 | 是 | 表示要广播的广播的制造商信息列表。 | 4146| serviceData | Array<[ServiceData](#servicedata)> | 是 | 是 | 表示要广播的服务数据列表。 | 4147| includeDeviceName | boolean | 是 | 是 | 表示是否携带设备名，可选参数。<br>true表示携带，false或未设置此参数表示不携带。<br>注意：带上设备名时广播包长度不能超出31个字节。 | 4148 4149## AdvertisingParams<sup>11+</sup> 4150 4151描述首次启动广播设置的参数。 4152 4153**系统能力**：SystemCapability.Communication.Bluetooth.Core 4154 4155| 名称 | 类型 | 可读 | 可写 | 说明 | 4156| ------------------- | ------------------------------- | ----- | ----- | ------------------------ | 4157| advertisingSettings<sup>11+</sup> | [AdvertiseSetting](#advertisesetting) | 是 | 是 | 表示发送广播的相关参数。 | 4158| advertisingData<sup>11+</sup> | [AdvertiseData](#advertisedata) | 是 | 是 | 表示广播的数据包内容。 | 4159| advertisingResponse<sup>11+</sup> | [AdvertiseData](#advertisedata) | 是 | 是 | 表示回复扫描请求的响应内容。 | 4160| duration<sup>11+</sup> | number | 是 | 是 | 表示发送广播持续的时间。<br>单位为10ms，有效范围为1(10ms)~65535(655350ms)。<br>如果未指定此参数或者将其设置为0，则会连续发送广播。 | 4161 4162## AdvertisingEnableParams<sup>11+</sup> 4163 4164描述临时启动广播设置的参数。 4165 4166**系统能力**：SystemCapability.Communication.Bluetooth.Core 4167 4168| 名称 | 类型 | 可读 | 可写 | 说明 | 4169| ------------------- | --------------------- | ----- | ----- | ------------------------ | 4170| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示当前广播的ID标识。 | 4171| duration<sup>11+</sup> | number | 是 | 是 | 表示发送广播持续的时间。<br>单位为10ms，有效范围为1(10ms)~65535(655350ms)。<br>如果未指定此参数或者将其设置为0，则会连续发送广播。 | 4172 4173## AdvertisingDisableParams<sup>11+</sup> 4174 4175描述临时停止广播设置的参数。 4176 4177**系统能力**：SystemCapability.Communication.Bluetooth.Core 4178 4179| 名称 | 类型 | 可读 | 可写 | 说明 | 4180| ------------------- | --------------------- | ----- | ----- | ------------------------ | 4181| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示当前广播的ID标识。 | 4182 4183## AdvertisingStateChangeInfo<sup>11+</sup> 4184 4185描述广播启动、停止等状态信息。 4186 4187**系统能力**：SystemCapability.Communication.Bluetooth.Core 4188 4189| 名称 | 类型 | 可读 | 可写 | 说明 | 4190| ------------------- | --------------------------------------- | ----- | ----- | ------------------------ | 4191| advertisingId<sup>11+</sup> | number | 是 | 是 | 表示广播ID标识。 | 4192| state<sup>11+</sup> | [AdvertisingState](#advertisingstate11) | 是 | 是 | 表示广播状态。 | 4193 4194## ManufactureData 4195 4196描述BLE广播数据包的内容。 4197 4198**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4199 4200**系统能力**：SystemCapability.Communication.Bluetooth.Core 4201 4202| 名称 | 类型 | 可读 | 可写 | 说明 | 4203| ---------------- | ------------------- | ---- | ---- | ------------------ | 4204| manufactureId | number | 是 | 是 | 表示制造商的ID，由蓝牙SIG分配。 | 4205| manufactureValue | ArrayBuffer | 是 | 是 | 表示制造商发送的制造商数据。 | 4206 4207 4208## ServiceData 4209 4210描述广播包中服务数据内容。 4211 4212**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4213 4214**系统能力**：SystemCapability.Communication.Bluetooth.Core 4215 4216| 名称 | 类型 | 可读 | 可写 | 说明 | 4217| ------------ | ----------- | ---- | ---- | ---------- | 4218| serviceUuid | string | 是 | 是 | 表示服务的UUID。 | 4219| serviceValue | ArrayBuffer | 是 | 是 | 表示服务数据。 | 4220 4221 4222## ScanFilter 4223 4224扫描过滤参数。 4225 4226**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4227 4228**系统能力**：SystemCapability.Communication.Bluetooth.Core 4229 4230| 名称 | 类型 | 必填 | 说明 | 4231| ------------------------------------------ | -------- | ---- | ------------------------------------------------------------ | 4232| deviceId | string | 否 | 表示过滤的BLE设备地址。例如："XX:XX:XX:XX:XX:XX"。 | 4233| name | string | 否 | 表示过滤的BLE设备名。 | 4234| serviceUuid | string | 否 | 表示过滤包含该UUID服务的设备。例如：00001888-0000-1000-8000-00805f9b34fb。 | 4235| serviceUuidMask | string | 否 | 表示过滤包含该UUID服务掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 4236| serviceSolicitationUuid | string | 否 | 表示过滤包含该UUID服务请求的设备。例如：00001888-0000-1000-8000-00805F9B34FB。 | 4237| serviceSolicitationUuidMask | string | 否 | 表示过滤包含该UUID服务请求掩码的设备。例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 4238| serviceData | ArrayBuffer | 否 | 表示过滤包含该服务相关数据的设备。例如：[0x90,0x00,0xF1,0xF2]。 | 4239| serviceDataMask | ArrayBuffer | 否 | 表示过滤包含该服务相关数据掩码的设备。例如：[0xFF,0xFF,0xFF,0xFF]。 | 4240| manufactureId | number | 否 | 表示过滤包含该制造商ID的设备。例如：0x0006。 | 4241| manufactureData | ArrayBuffer | 否 | 表示过滤包含该制造商相关数据的设备。例如：[0x1F,0x2F,0x3F]。 | 4242| manufactureDataMask | ArrayBuffer | 否 | 表示过滤包含该制造商相关数据掩码的设备。例如：[0xFF,0xFF,0xFF]。 | 4243 4244 4245## ScanOptions 4246 4247扫描的配置参数。 4248 4249**系统能力**：SystemCapability.Communication.Bluetooth.Core 4250 4251| 名称 | 类型 | 可读 | 可写 | 说明 | 4252| --------- | ----------------------- | ---- | ---- | -------------------------------------- | 4253| interval | number | 是 | 是 | 表示扫描结果上报延迟时间，默认值为0。**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 4254| dutyMode | [ScanDuty](#scanduty) | 是 | 是 | 表示扫描模式，默认值为SCAN_MODE_LOW_POWER。**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 4255| matchMode | [MatchMode](#matchmode) | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 4256| phyType<sup>12+</sup> | [PhyType](#phytype12) | 是 | 是 | 表示扫描中使用的PHY类型。**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 | 4257| reportMode<sup>15+</sup> | [ScanReportMode](#scanreportmode15) | 是 | 是 | 表示扫描结果数据上报模式。**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 | 4258 4259 4260## GattProperties 4261 4262描述gatt characteristic的属性。 4263 4264**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4265 4266**系统能力**：SystemCapability.Communication.Bluetooth.Core 4267 4268| 名称 | 类型 | 必填 | 说明 | 4269| -------- | ------ |---- | ----------- | 4270| write | boolean | 否 | 表示该特征支持写操作，true表示需要对端设备的回复。 | 4271| writeNoResponse | boolean | 否 | true表示该特征支持写操作，无需对端设备回复。 | 4272| read | boolean | 否 | true表示该特征支持读操作。 | 4273| notify | boolean | 否 | true表示该特征可通知对端设备。 | 4274| indicate | boolean | 否 | true表示该特征可通知对端设备，需要对端设备的回复。 | 4275 4276 4277## GattWriteType 4278 4279枚举，表示gatt写入类型。 4280 4281**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4282 4283**系统能力**：SystemCapability.Communication.Bluetooth.Core 4284 4285| 名称 | 值 | 说明 | 4286| ------------------------------------| ------ | --------------- | 4287| WRITE | 1 | 表示写入特征值，需要对端设备的回复。 | 4288| WRITE_NO_RESPONSE | 2 | 表示写入特征值，不需要对端设备的回复。 | 4289 4290 4291## ScanDuty 4292 4293枚举，扫描模式。 4294 4295**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4296 4297**系统能力**：SystemCapability.Communication.Bluetooth.Core 4298 4299| 名称 | 值 | 说明 | 4300| --------------------- | ---- | ------------ | 4301| SCAN_MODE_LOW_POWER | 0 | 表示低功耗模式，默认值。 | 4302| SCAN_MODE_BALANCED | 1 | 表示均衡模式。 | 4303| SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | 4304 4305 4306## MatchMode 4307 4308枚举，硬件过滤匹配模式。 4309 4310**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4311 4312**系统能力**：SystemCapability.Communication.Bluetooth.Core 4313 4314| 名称 | 值 | 说明 | 4315| --------------------- | ---- | ---------------------------------------- | 4316| MATCH_MODE_AGGRESSIVE | 1 | 表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。 | 4317| MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | 4318 4319## AdvertisingState<sup>11+</sup> 4320 4321枚举，广播状态。 4322 4323**系统能力**：SystemCapability.Communication.Bluetooth.Core 4324 4325| 名称 | 值 | 说明 | 4326| -------- | ---- | ------------------------------ | 4327| STARTED<sup>11+</sup> | 1 | 表示首次启动广播后的状态。 | 4328| ENABLED<sup>11+</sup> | 2 | 表示临时启动广播后的状态。 | 4329| DISABLED<sup>11+</sup> | 3 | 表示临时停止广播后的状态。 | 4330| STOPPED<sup>11+</sup> | 4 | 表示完全停止广播后的状态。 | 4331 4332## PhyType<sup>12+</sup> 4333 4334枚举，扫描中使用的PHY类型。 4335 4336**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 4337 4338**系统能力**：SystemCapability.Communication.Bluetooth.Core 4339 4340| 名称 | 值 | 说明 | 4341| -------- | ---- | ------------------------------ | 4342| PHY_LE_1M<sup>12+</sup> | 1 | 表示扫描中使用1M PHY。 | 4343| PHY_LE_ALL_SUPPORTED<sup>12+</sup> | 255 | 表示扫描中使用蓝牙协议支持的PHY模式。 | 4344 4345## ScanReport<sup>15+</sup> 4346 4347扫描结果数据上报。 4348 4349**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4350 4351**系统能力**：SystemCapability.Communication.Bluetooth.Core 4352 4353| 名称 | 类型 | 只读 | 可选 | 说明 | 4354| --------- | ----------------------- | ---- | ---- | ------------------------------ | 4355| reportType | [ScanReportType](#scanreporttype15) | 否 | 否 | 表示扫描报告类型。 | 4356| scanResult | Array<[ScanResult](#scanresult)> | 否 | 否 |扫描结果数据。 | 4357 4358## ScanReportType<sup>15+</sup> 4359 4360枚举，扫描结果数据上报类型。 4361 4362**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4363 4364**系统能力**：SystemCapability.Communication.Bluetooth.Core 4365 4366| 名称 | 值 | 说明 | 4367| -------- | ---- | ------------------------------ | 4368| ON_FOUND | 1 | 表示发现广播包。 | 4369| ON_LOST | 2 | 表示丢失广播包。 | 4370 4371## ScanReportMode<sup>15+</sup> 4372 4373枚举，扫描结果数据上报模式。 4374 4375**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 4376 4377**系统能力**：SystemCapability.Communication.Bluetooth.Core 4378 4379| 名称 | 值 | 说明 | 4380| -------- | ---- | ------------------------------ | 4381| NORMAL | 1 | 表示常规扫描上报模式。 | 4382| FENCE_SENSITIVITY_LOW<sup>18+</sup> | 10 | 表示低灵敏度围栏上报模式。只在首次收到广播包和丢失广播包时上报，灵敏度低。 | 4383| FENCE_SENSITIVITY_HIGH<sup>18+</sup> | 11 | 表示高灵敏度围栏上报模式。只在首次收到广播包和丢失广播包时上报，灵敏度高。 |