1# @ohos.bluetooth.ble (蓝牙ble模块) 2 3ble模块提供了对蓝牙操作和管理的方法。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10 11## 导入模块 12 13```js 14import ble from '@ohos.bluetooth.ble'; 15``` 16 17 18## ble.createGattServer<a name="createGattServer"></a> 19 20createGattServer(): GattServer 21 22创建GattServer实例。 23 24**系统能力**：SystemCapability.Communication.Bluetooth.Core。 25 26**返回值：** 27 28| 类型 | 说明 | 29| ----------------------------- | ---------- | 30| GattServer | 返回一个Gatt服务的实例。 | 31 32**示例：** 33 34```js 35let gattServer: ble.GattServer = ble.createGattServer(); 36console.info('gatt success'); 37``` 38 39 40## ble.createGattClientDevice<a name="createGattClientDevice"></a> 41 42createGattClientDevice(deviceId: string): GattClientDevice 43 44创建一个可使用的GattClientDevice实例。 45 46**系统能力**：SystemCapability.Communication.Bluetooth.Core。 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 说明 | 51| -------- | ------ | ---- | ------------------------------------ | 52| deviceId | string | 是 | 对端设备地址， 例如："XX:XX:XX:XX:XX:XX"。 | 53 54**返回值：** 55 56| 类型 | 说明 | 57| ------------------------------------- | ------------------------------------ | 58| [GattClientDevice](#gattclientdevice) | client端类，使用client端方法之前需要创建该类的实例进行操作。 | 59 60**示例：** 61 62```js 63import { BusinessError } from '@ohos.base'; 64try { 65 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 66} catch (err) { 67 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 68} 69``` 70 71 72## ble.getConnectedBLEDevices<a name="getConnectedBLEDevices"></a> 73 74getConnectedBLEDevices(): Array<string> 75 76获取和当前设备连接的BLE设备。 77 78**需要权限**：ohos.permission.ACCESS_BLUETOOTH 79 80**系统能力**：SystemCapability.Communication.Bluetooth.Core。 81 82**返回值：** 83 84| 类型 | 说明 | 85| ------------------- | ------------------- | 86| Array<string> | 返回当前设备作为Server端时连接BLE设备地址集合。 | 87 88**错误码**： 89 90以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 91 92| 错误码ID | 错误信息 | 93| -------- | ---------------------------- | 94|2900001 | Service stopped. | 95|2900003 | Bluetooth switch is off. | 96|2900099 | Operation failed. | 97 98**示例：** 99 100```js 101import { BusinessError } from '@ohos.base'; 102try { 103 let result: Array<string> = ble.getConnectedBLEDevices(); 104} catch (err) { 105 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 106} 107``` 108 109 110## ble.startBLEScan<a name="startBLEScan"></a> 111 112startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void 113 114发起BLE扫描流程。 115 116**需要权限**：ohos.permission.ACCESS_BLUETOOTH 117 118**系统能力**：SystemCapability.Communication.Bluetooth.Core。 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| ------- | -------------------------------------- | ---- | ----------------------------------- | 124| filters | Array<[ScanFilter](#scanfilter)> | 是 | 表示扫描结果过滤策略集合，如果不使用过滤的方式，该参数设置为null。 | 125| options | [ScanOptions](#scanoptions) | 否 | 表示扫描的参数配置，可选参数。 | 126 127**错误码**： 128 129以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 130 131| 错误码ID | 错误信息 | 132| -------- | ---------------------------- | 133|2900001 | Service stopped. | 134|2900003 | Bluetooth switch is off. | 135|2900099 | Operation failed. | 136 137**示例：** 138 139```js 140import { BusinessError } from '@ohos.base'; 141function onReceiveEvent(data: Array<ble.ScanResult>) { 142 console.info('BLE scan device find result = '+ JSON.stringify(data)); 143} 144try { 145 ble.on("BLEDeviceFind", onReceiveEvent); 146 let scanFilter: ble.ScanFilter = { 147 deviceId:"XX:XX:XX:XX:XX:XX", 148 name:"test", 149 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 150 }; 151 let scanOptions: ble.ScanOptions = { 152 interval: 500, 153 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 154 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE, 155 } 156 ble.startBLEScan([scanFilter],scanOptions); 157} catch (err) { 158 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 159} 160``` 161 162 163## ble.stopBLEScan<a name="stopBLEScan"></a> 164 165stopBLEScan(): void 166 167停止BLE扫描流程。 168 169**需要权限**：ohos.permission.ACCESS_BLUETOOTH 170 171**系统能力**：SystemCapability.Communication.Bluetooth.Core。 172 173**错误码**： 174 175以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 176 177| 错误码ID | 错误信息 | 178| -------- | ---------------------------- | 179|2900001 | Service stopped. | 180|2900003 | Bluetooth switch is off. | 181|2900099 | Operation failed. | 182 183**示例：** 184 185```js 186import { BusinessError } from '@ohos.base'; 187try { 188 ble.stopBLEScan(); 189} catch (err) { 190 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 191} 192``` 193 194 195## ble.startAdvertising<a name="startAdvertising"></a> 196 197startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void 198 199开始发送BLE广播。 200 201**需要权限**：ohos.permission.ACCESS_BLUETOOTH 202 203**系统能力**：SystemCapability.Communication.Bluetooth.Core。 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ----------- | ------------------------------------- | ---- | -------------- | 209| setting | [AdvertiseSetting](#advertisesetting) | 是 | BLE广播的相关参数。 | 210| advData | [AdvertiseData](#advertisedata) | 是 | BLE广播包内容。 | 211| advResponse | [AdvertiseData](#advertisedata) | 否 | BLE回复扫描请求回复响应。 | 212 213**错误码**： 214 215以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 216 217| 错误码ID | 错误信息 | 218| -------- | ---------------------------- | 219|2900001 | Service stopped. | 220|2900003 | Bluetooth switch is off. | 221|2900099 | Operation failed. | 222 223**示例：** 224 225```js 226import { BusinessError } from '@ohos.base'; 227let manufactureValueBuffer = new Uint8Array(4); 228manufactureValueBuffer[0] = 1; 229manufactureValueBuffer[1] = 2; 230manufactureValueBuffer[2] = 3; 231manufactureValueBuffer[3] = 4; 232 233let serviceValueBuffer = new Uint8Array(4); 234serviceValueBuffer[0] = 4; 235serviceValueBuffer[1] = 6; 236serviceValueBuffer[2] = 7; 237serviceValueBuffer[3] = 8; 238console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 239console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 240try { 241 let setting: ble.AdvertiseSetting = { 242 interval:150, 243 txPower:0, 244 connectable:true, 245 }; 246 let manufactureDataUnit: ble.ManufactureData = { 247 manufactureId:4567, 248 manufactureValue:manufactureValueBuffer.buffer 249 }; 250 let serviceDataUnit: ble.ServiceData = { 251 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 252 serviceValue:serviceValueBuffer.buffer 253 }; 254 let advData: ble.AdvertiseData = { 255 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 256 manufactureData:[manufactureDataUnit], 257 serviceData:[serviceDataUnit], 258 }; 259 let advResponse: ble.AdvertiseData = { 260 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 261 manufactureData:[manufactureDataUnit], 262 serviceData:[serviceDataUnit], 263 }; 264 ble.startAdvertising(setting, advData ,advResponse); 265} catch (err) { 266 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 267} 268``` 269 270 271## ble.stopAdvertising<a name="stopAdvertising"></a> 272 273stopAdvertising(): void 274 275停止发送BLE广播。 276 277**需要权限**：ohos.permission.ACCESS_BLUETOOTH 278 279**系统能力**：SystemCapability.Communication.Bluetooth.Core。 280 281**错误码**： 282 283以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 284 285| 错误码ID | 错误信息 | 286| -------- | ---------------------------- | 287|2900001 | Service stopped. | 288|2900003 | Bluetooth switch is off. | 289|2900099 | Operation failed. | 290 291**示例：** 292 293```js 294import { BusinessError } from '@ohos.base'; 295try { 296 ble.stopAdvertising(); 297} catch (err) { 298 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 299} 300``` 301 302 303## ble.on('BLEDeviceFind') 304 305on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void 306 307订阅BLE设备发现上报事件。 308 309**需要权限**：ohos.permission.ACCESS_BLUETOOTH 310 311**系统能力**：SystemCapability.Communication.Bluetooth.Core。 312 313**参数：** 314 315| 参数名 | 类型 | 必填 | 说明 | 316| -------- | ---------------------------------------- | ---- | ----------------------------------- | 317| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 318| callback | Callback<Array<[ScanResult](#scanresult)>> | 是 | 表示回调函数的入参，发现的设备集合。回调函数由用户创建通过该接口注册。 | 319 320**错误码**： 321 322以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 323 324| 错误码ID | 错误信息 | 325| -------- | ---------------------------- | 326|2900099 | Operation failed. | 327 328**示例：** 329 330```js 331import { BusinessError } from '@ohos.base'; 332function onReceiveEvent(data: Array<ble.ScanResult>) { 333 console.info('bluetooth device find = '+ JSON.stringify(data)); 334} 335try { 336 ble.on('BLEDeviceFind', onReceiveEvent); 337} catch (err) { 338 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 339} 340``` 341 342 343## ble.off('BLEDeviceFind') 344 345off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void 346 347取消订阅BLE设备发现上报事件。 348 349**需要权限**：ohos.permission.ACCESS_BLUETOOTH 350 351**系统能力**：SystemCapability.Communication.Bluetooth.Core。 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 357| type | string | 是 | 填写"BLEDeviceFind"字符串，表示BLE设备发现事件。 | 358| callback | Callback<Array<[ScanResult](#scanresult)>> | 否 | 表示取消订阅BLE设备发现事件上报。不填该参数则取消订阅该type对应的所有回调。 | 359 360**错误码**： 361 362以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 363 364| 错误码ID | 错误信息 | 365| -------- | ---------------------------- | 366|2900099 | Operation failed. | 367 368**示例：** 369 370```js 371import { BusinessError } from '@ohos.base'; 372function onReceiveEvent(data: Array<ble.ScanResult>) { 373 console.info('bluetooth device find = '+ JSON.stringify(data)); 374} 375try { 376 ble.on('BLEDeviceFind', onReceiveEvent); 377 ble.off('BLEDeviceFind', onReceiveEvent); 378} catch (err) { 379 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 380} 381``` 382 383 384## GattServer 385 386server端类，使用server端方法之前需要创建该类的实例进行操作，通过createGattServer()方法构造此实例。 387 388 389### addService 390 391addService(service: GattService): void 392 393server端添加服务。 394 395**需要权限**：ohos.permission.ACCESS_BLUETOOTH 396 397**系统能力**：SystemCapability.Communication.Bluetooth.Core。 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ------- | --------------------------- | ---- | ------------------------ | 403| service | [GattService](#gattservice) | 是 | 服务端的service数据。BLE广播的相关参数 | 404 405**错误码**： 406 407以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 408 409| 错误码ID | 错误信息 | 410| -------- | ---------------------------- | 411|2900001 | Service stopped. | 412|2900003 | Bluetooth switch is off. | 413|2900099 | Operation failed. | 414 415**示例：** 416 417```js 418import { BusinessError } from '@ohos.base'; 419// 创建descriptors 420let descriptors: Array<ble.BLEDescriptor> = []; 421let arrayBuffer = new ArrayBuffer(8); 422let descV = new Uint8Array(arrayBuffer); 423descV[0] = 11; 424let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 425 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 426 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 427descriptors[0] = descriptor; 428 429// 创建characteristics 430let characteristics: Array<ble.BLECharacteristic> = []; 431let arrayBufferC = new ArrayBuffer(8); 432let cccV = new Uint8Array(arrayBufferC); 433cccV[0] = 1; 434let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 435 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 436let characteristicN: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 437 characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 438characteristics[0] = characteristic; 439 440// 创建gattService 441let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; 442 443try { 444 let gattServer: ble.GattServer = ble.createGattServer(); 445 gattServer.addService(gattService); 446} catch (err) { 447 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 448} 449``` 450 451 452### removeService 453 454removeService(serviceUuid: string): void 455 456删除已添加的服务。 457 458**需要权限**：ohos.permission.ACCESS_BLUETOOTH 459 460**系统能力**：SystemCapability.Communication.Bluetooth.Core。 461 462**参数：** 463 464| 参数名 | 类型 | 必填 | 说明 | 465| ----------- | ------ | ---- | ---------------------------------------- | 466| serviceUuid | string | 是 | service的UUID，例如“00001810-0000-1000-8000-00805F9B34FB”。 | 467 468**错误码**： 469 470以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 471 472| 错误码ID | 错误信息 | 473| -------- | ---------------------------- | 474|2900001 | Service stopped. | 475|2900003 | Bluetooth switch is off. | 476|2900004 | Profile is not supported. | 477|2900099 | Operation failed. | 478 479**示例：** 480 481```js 482import { BusinessError } from '@ohos.base'; 483let server: ble.GattServer = ble.createGattServer(); 484try { 485 server.removeService('00001810-0000-1000-8000-00805F9B34FB'); 486} catch (err) { 487 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 488} 489``` 490 491 492### close 493 494close(): void 495 496关闭服务端功能，去注册server在协议栈的注册，调用该接口后[GattServer](#gattserver)实例将不能再使用。 497 498**需要权限**：ohos.permission.ACCESS_BLUETOOTH 499 500**系统能力**：SystemCapability.Communication.Bluetooth.Core。 501 502**错误码**： 503 504以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 505 506| 错误码ID | 错误信息 | 507| -------- | ---------------------------- | 508|2900001 | Service stopped. | 509|2900003 | Bluetooth switch is off. | 510|2900099 | Operation failed. | 511 512**示例：** 513 514```js 515import { BusinessError } from '@ohos.base'; 516let server: ble.GattServer = ble.createGattServer(); 517try { 518 server.close(); 519} catch (err) { 520 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 521} 522``` 523 524 525### notifyCharacteristicChanged 526 527notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void 528 529server端特征值发生变化时，主动通知已连接的client设备。 530 531**需要权限**：ohos.permission.ACCESS_BLUETOOTH 532 533**系统能力**：SystemCapability.Communication.Bluetooth.Core。 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 539| deviceId | string | 是 | 接收通知的client端设备地址，例如“XX:XX:XX:XX:XX:XX”。 | 540| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 541| callback | AsyncCallback<void> | 是 | 回调函数。当通知成功，err为undefined，否则为错误对象。 | 542 543**错误码**： 544 545以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 546 547| 错误码ID | 错误信息 | 548| -------- | ---------------------------- | 549|2900001 | Service stopped. | 550|2900003 | Bluetooth switch is off. | 551|2900099 | Operation failed. | 552 553**示例：** 554 555```js 556import { BusinessError } from '@ohos.base'; 557let arrayBufferC = new ArrayBuffer(8); 558let notifyCharacter: ble.NotifyCharacteristic = { 559 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 560 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 561 characteristicValue: arrayBufferC, 562 confirm: true, 563}; 564try { 565 let gattServer: ble.GattServer = ble.createGattServer(); 566 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => { 567 if (err) { 568 console.info('notifyCharacteristicChanged callback failed'); 569 } else { 570 console.info('notifyCharacteristicChanged callback successful'); 571 } 572 }); 573} catch (err) { 574 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 575} 576``` 577 578 579### notifyCharacteristicChanged 580 581notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> 582 583server端特征值发生变化时，主动通知已连接的client设备。 584 585**需要权限**：ohos.permission.ACCESS_BLUETOOTH 586 587**系统能力**：SystemCapability.Communication.Bluetooth.Core。 588 589**参数：** 590 591| 参数名 | 类型 | 必填 | 说明 | 592| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 593| deviceId | string | 是 | 接收通知的client端设备地址，例如“XX:XX:XX:XX:XX:XX”。 | 594| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | 是 | 通知的特征值数据。 | 595 596**返回值：** 597 598| 类型 | 说明 | 599| ------------------- | ------------- | 600| Promise<void> | 返回promise对象。 | 601 602**错误码**： 603 604以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 605 606| 错误码ID | 错误信息 | 607| -------- | ---------------------------- | 608|2900001 | Service stopped. | 609|2900003 | Bluetooth switch is off. | 610|2900099 | Operation failed. | 611 612**示例：** 613 614```js 615import { BusinessError } from '@ohos.base'; 616let arrayBufferC = new ArrayBuffer(8); 617let notifyCharacter: ble.NotifyCharacteristic = { 618 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 619 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 620 characteristicValue: arrayBufferC, 621 confirm: true, 622}; 623try { 624 let gattServer: ble.GattServer = ble.createGattServer(); 625 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { 626 console.info('notifyCharacteristicChanged promise successfull'); 627 }); 628} catch (err) { 629 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 630} 631``` 632 633 634### sendResponse 635 636sendResponse(serverResponse: ServerResponse): void 637 638server端回复client端的读写请求。 639 640**需要权限**：ohos.permission.ACCESS_BLUETOOTH 641 642**系统能力**：SystemCapability.Communication.Bluetooth.Core。 643 644**参数：** 645 646| 参数名 | 类型 | 必填 | 说明 | 647| -------------- | --------------------------------- | ---- | --------------- | 648| serverResponse | [ServerResponse](#serverresponse) | 是 | server端回复的响应数据。 | 649 650**错误码**： 651 652以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 653 654| 错误码ID | 错误信息 | 655| -------- | ---------------------------- | 656|2900001 | Service stopped. | 657|2900003 | Bluetooth switch is off. | 658|2900099 | Operation failed. | 659 660**示例：** 661 662```js 663import { BusinessError } from '@ohos.base'; 664/* send response */ 665let arrayBufferCCC = new ArrayBuffer(8); 666let cccValue = new Uint8Array(arrayBufferCCC); 667cccValue[0] = 1123; 668let serverResponse: ble.ServerResponse = { 669 deviceId: 'XX:XX:XX:XX:XX:XX', 670 transId: 0, 671 status: 0, 672 offset: 0, 673 value: arrayBufferCCC, 674}; 675try { 676 let gattServer: ble.GattServer = ble.createGattServer(); 677 gattServer.sendResponse(serverResponse); 678} catch (err) { 679 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 680} 681``` 682 683 684### on('characteristicRead') 685 686on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void 687 688server端订阅特征值读请求事件。 689 690**需要权限**：ohos.permission.ACCESS_BLUETOOTH 691 692**系统能力**：SystemCapability.Communication.Bluetooth.Core。 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| -------- | ---------------------------------------- | ---- | ------------------------------------- | 698| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 699| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 700 701**示例：** 702 703```js 704import { BusinessError } from '@ohos.base'; 705let arrayBufferCCC = new ArrayBuffer(8); 706let cccValue = new Uint8Array(arrayBufferCCC); 707cccValue[0] = 1123; 708let gattServer: ble.GattServer = ble.createGattServer(); 709function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) { 710 let deviceId: string = characteristicReadRequest.deviceId; 711 let transId: number = characteristicReadRequest.transId; 712 let offset: number = characteristicReadRequest.offset; 713 let characteristicUuid: string = characteristicReadRequest.characteristicUuid; 714 715 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 716 717 try { 718 gattServer.sendResponse(serverResponse); 719 } catch (err) { 720 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 721 } 722} 723gattServer.on('characteristicRead', ReadCharacteristicReq); 724``` 725 726 727### off('characteristicRead') 728 729off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void 730 731server端取消订阅特征值读请求事件。 732 733**需要权限**：ohos.permission.ACCESS_BLUETOOTH 734 735**系统能力**：SystemCapability.Communication.Bluetooth.Core。 736 737**参数：** 738 739| 参数名 | 类型 | 必填 | 说明 | 740| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 741| type | string | 是 | 填写"characteristicRead"字符串，表示特征值读请求事件。 | 742| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | 否 | 表示取消订阅特征值读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 743 744**示例：** 745 746```js 747import { BusinessError } from '@ohos.base'; 748try { 749let gattServer: ble.GattServer = ble.createGattServer(); 750gattServer.off('characteristicRead'); 751} catch (err) { 752 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 753} 754``` 755 756 757### on('characteristicWrite') 758 759on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void 760 761server端订阅特征值写请求事件。 762 763**需要权限**：ohos.permission.ACCESS_BLUETOOTH 764 765**系统能力**：SystemCapability.Communication.Bluetooth.Core。 766 767**参数：** 768 769| 参数名 | 类型 | 必填 | 说明 | 770| -------- | ---------------------------------------- | ---- | -------------------------------------- | 771| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 772| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 773 774**示例：** 775 776```js 777import { BusinessError } from '@ohos.base'; 778let arrayBufferCCC = new ArrayBuffer(8); 779let cccValue = new Uint8Array(arrayBufferCCC); 780let gattServer: ble.GattServer = ble.createGattServer(); 781function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) { 782 let deviceId: string = characteristicWriteRequest.deviceId; 783 let transId: number = characteristicWriteRequest.transId; 784 let offset: number = characteristicWriteRequest.offset; 785 let isPrepared: boolean = characteristicWriteRequest.isPrepared; 786 let needRsp: boolean = characteristicWriteRequest.needRsp; 787 let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value); 788 let characteristicUuid: string = characteristicWriteRequest.characteristicUuid; 789 790 cccValue[0] = value[0]; 791 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 792 793 try { 794 gattServer.sendResponse(serverResponse); 795 } catch (err) { 796 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 797 } 798} 799gattServer.on('characteristicWrite', WriteCharacteristicReq); 800``` 801 802 803### off('characteristicWrite') 804 805off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void 806 807server端取消订阅特征值写请求事件。 808 809**需要权限**：ohos.permission.ACCESS_BLUETOOTH 810 811**系统能力**：SystemCapability.Communication.Bluetooth.Core。 812 813**参数：** 814 815| 参数名 | 类型 | 必填 | 说明 | 816| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 817| type | string | 是 | 填写"characteristicWrite"字符串，表示特征值写请求事件。 | 818| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | 否 | 表示取消订阅特征值写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 819 820**示例：** 821 822```js 823import { BusinessError } from '@ohos.base'; 824try { 825let gattServer: ble.GattServer = ble.createGattServer(); 826gattServer.off('characteristicWrite'); 827} catch (err) { 828 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 829} 830``` 831 832 833### on('descriptorRead') 834 835on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void 836 837server端订阅描述符读请求事件。 838 839**需要权限**：ohos.permission.ACCESS_BLUETOOTH 840 841**系统能力**：SystemCapability.Communication.Bluetooth.Core。 842 843**参数：** 844 845| 参数名 | 类型 | 必填 | 说明 | 846| -------- | ---------------------------------------- | ---- | --------------------------------- | 847| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 848| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 是 | 表示回调函数的入参，client端发送的读请求数据。 | 849 850**示例：** 851 852```js 853import { BusinessError } from '@ohos.base'; 854let arrayBufferDesc = new ArrayBuffer(8); 855let descValue = new Uint8Array(arrayBufferDesc); 856descValue[0] = 1101; 857let gattServer: ble.GattServer = ble.createGattServer(); 858function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) { 859 let deviceId: string = descriptorReadRequest.deviceId; 860 let transId: number = descriptorReadRequest.transId; 861 let offset: number = descriptorReadRequest.offset; 862 let descriptorUuid: string = descriptorReadRequest.descriptorUuid; 863 864 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 865 866 try { 867 gattServer.sendResponse(serverResponse); 868 } catch (err) { 869 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 870 } 871} 872gattServer.on('descriptorRead', ReadDescriptorReq); 873``` 874 875 876### off('descriptorRead') 877 878off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void 879 880server端取消订阅描述符读请求事件。 881 882**需要权限**：ohos.permission.ACCESS_BLUETOOTH 883 884**系统能力**：SystemCapability.Communication.Bluetooth.Core。 885 886**参数：** 887 888| 参数名 | 类型 | 必填 | 说明 | 889| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 890| type | string | 是 | 填写"descriptorRead"字符串，表示描述符读请求事件。 | 891| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | 否 | 表示取消订阅描述符读请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 892 893**示例：** 894 895```js 896import { BusinessError } from '@ohos.base'; 897try { 898let gattServer: ble.GattServer = ble.createGattServer(); 899gattServer.off('descriptorRead'); 900} catch (err) { 901 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 902} 903``` 904 905 906### on('descriptorWrite') 907 908on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void 909 910server端订阅描述符写请求事件。 911 912**需要权限**：ohos.permission.ACCESS_BLUETOOTH 913 914**系统能力**：SystemCapability.Communication.Bluetooth.Core。 915 916**参数：** 917 918| 参数名 | 类型 | 必填 | 说明 | 919| -------- | ---------------------------------------- | ---- | ---------------------------------- | 920| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 921| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 是 | 表示回调函数的入参，client端发送的写请求数据。 | 922 923**示例：** 924 925```js 926import { BusinessError } from '@ohos.base'; 927let arrayBufferDesc = new ArrayBuffer(8); 928let descValue = new Uint8Array(arrayBufferDesc); 929let gattServer: ble.GattServer = ble.createGattServer(); 930function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) { 931 let deviceId: string = descriptorWriteRequest.deviceId; 932 let transId: number = descriptorWriteRequest.transId; 933 let offset: number = descriptorWriteRequest.offset; 934 let isPrepared: boolean = descriptorWriteRequest.isPrepared; 935 let needRsp: boolean = descriptorWriteRequest.needRsp; 936 let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value); 937 let descriptorUuid: string = descriptorWriteRequest.descriptorUuid; 938 939 descValue[0] = value[0]; 940 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 941 942 try { 943 gattServer.sendResponse(serverResponse); 944 } catch (err) { 945 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 946 } 947} 948gattServer.on('descriptorWrite', WriteDescriptorReq); 949``` 950 951 952### off('descriptorWrite') 953 954off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void 955 956server端取消订阅描述符写请求事件。 957 958**需要权限**：ohos.permission.ACCESS_BLUETOOTH 959 960**系统能力**：SystemCapability.Communication.Bluetooth.Core。 961 962**参数：** 963 964| 参数名 | 类型 | 必填 | 说明 | 965| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 966| type | string | 是 | 填写"descriptorWrite"字符串，表示描述符写请求事件。 | 967| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | 否 | 表示取消订阅描述符写请求事件上报。不填该参数则取消订阅该type对应的所有回调。 | 968 969**示例：** 970 971```js 972import { BusinessError } from '@ohos.base'; 973try { 974let gattServer: ble.GattServer = ble.createGattServer(); 975gattServer.off('descriptorWrite'); 976} catch (err) { 977 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 978} 979``` 980 981 982### on('connectionStateChange') 983 984on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void 985 986server端订阅BLE连接状态变化事件。 987 988**需要权限**：ohos.permission.ACCESS_BLUETOOTH 989 990**系统能力**：SystemCapability.Communication.Bluetooth.Core。 991 992**参数：** 993 994| 参数名 | 类型 | 必填 | 说明 | 995| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 996| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 997| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示回调函数的入参，连接状态。 | 998 999**示例：** 1000 1001```js 1002import { BusinessError } from '@ohos.base'; 1003import constant from '@ohos.bluetooth.constant'; 1004function Connected(bleConnectionChangeState: ble.BLEConnectionChangeState) { 1005 let deviceId: string = bleConnectionChangeState.deviceId; 1006 let status: constant.ProfileConnectionState = bleConnectionChangeState.state; 1007} 1008try { 1009let gattServer: ble.GattServer = ble.createGattServer(); 1010gattServer.on('connectionStateChange', Connected); 1011} catch (err) { 1012 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1013} 1014``` 1015 1016 1017### off('connectionStateChange') 1018 1019off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 1020 1021server端取消订阅BLE连接状态变化事件。 1022 1023**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1024 1025**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1026 1027**参数：** 1028 1029| 参数名 | 类型 | 必填 | 说明 | 1030| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1031| type | string | 是 | 填写"connectionStateChange"字符串，表示BLE连接状态变化事件。 | 1032| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅BLE连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 1033 1034**示例：** 1035 1036```js 1037import { BusinessError } from '@ohos.base'; 1038try { 1039let gattServer: ble.GattServer = ble.createGattServer(); 1040gattServer.off('connectionStateChange'); 1041} catch (err) { 1042 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1043} 1044``` 1045 1046 1047### on('BLEMtuChange') 1048 1049on(type: 'BLEMtuChange', callback: Callback<number>): void 1050 1051server端订阅MTU状态变化事件。 1052 1053**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1054 1055**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1056 1057**参数：** 1058 1059| 参数名 | 类型 | 必填 | 说明 | 1060| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1061| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 1062| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 1063 1064**示例：** 1065 1066```js 1067import { BusinessError } from '@ohos.base'; 1068try { 1069 let gattServer: ble.GattServer = ble.createGattServer(); 1070 gattServer.on('BLEMtuChange', (mtu: number) => { 1071 console.info('BLEMtuChange, mtu: ' + mtu); 1072 }); 1073} catch (err) { 1074 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1075} 1076``` 1077 1078 1079### off('BLEMtuChange') 1080 1081off(type: 'BLEMtuChange', callback?: Callback<number>): void 1082 1083server端取消订阅MTU状态变化事件。 1084 1085**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1086 1087**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1088 1089**参数：** 1090 1091| 参数名 | 类型 | 必填 | 说明 | 1092| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1093| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 1094| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 1095 1096**示例：** 1097 1098```js 1099import { BusinessError } from '@ohos.base'; 1100try { 1101 let gattServer: ble.GattServer = ble.createGattServer(); 1102 gattServer.off('BLEMtuChange'); 1103} catch (err) { 1104 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1105} 1106``` 1107 1108 1109## GattClientDevice 1110 1111client端类，使用client端方法之前需要创建该类的实例进行操作，通过createGattClientDevice(deviceId: string)方法构造此实例。 1112 1113 1114### connect 1115 1116connect(): void 1117 1118client端发起连接远端蓝牙低功耗设备。 1119 1120**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1121 1122**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1123 1124**错误码**： 1125 1126以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1127 1128| 错误码ID | 错误信息 | 1129| -------- | ---------------------------- | 1130|2900001 | Service stopped. | 1131|2900003 | Bluetooth switch is off. | 1132|2900099 | Operation failed. | 1133 1134**示例：** 1135 1136```js 1137import { BusinessError } from '@ohos.base'; 1138try { 1139 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1140 device.connect(); 1141} catch (err) { 1142 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1143} 1144``` 1145 1146 1147### disconnect 1148 1149disconnect(): void 1150 1151client端断开与远端蓝牙低功耗设备的连接。 1152 1153**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1154 1155**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1156 1157**错误码**： 1158 1159以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1160 1161| 错误码ID | 错误信息 | 1162| -------- | ---------------------------- | 1163|2900001 | Service stopped. | 1164|2900003 | Bluetooth switch is off. | 1165|2900099 | Operation failed. | 1166 1167**示例：** 1168 1169```js 1170import { BusinessError } from '@ohos.base'; 1171try { 1172 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1173 device.disconnect(); 1174} catch (err) { 1175 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1176} 1177``` 1178 1179 1180### close 1181 1182close(): void 1183 1184关闭客户端功能，注销client在协议栈的注册，调用该接口后[GattClientDevice](#gattclientdevice)实例将不能再使用。 1185 1186**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1187 1188**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1189 1190**错误码**： 1191 1192以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1193 1194| 错误码ID | 错误信息 | 1195| -------- | ---------------------------- | 1196|2900001 | Service stopped. | 1197|2900003 | Bluetooth switch is off. | 1198|2900099 | Operation failed. | 1199 1200**示例：** 1201 1202```js 1203import { BusinessError } from '@ohos.base'; 1204try { 1205 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1206 device.close(); 1207} catch (err) { 1208 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1209} 1210``` 1211 1212 1213### getDeviceName 1214 1215getDeviceName(callback: AsyncCallback<string>): void 1216 1217client获取远端蓝牙低功耗设备名。 1218 1219**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1220 1221**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1222 1223**参数：** 1224 1225| 参数名 | 类型 | 必填 | 说明 | 1226| -------- | --------------------------- | ---- | ------------------------------- | 1227| callback | AsyncCallback<string> | 是 | client获取对端server设备名，通过注册回调函数获取。 | 1228 1229**错误码**： 1230 1231以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1232 1233| 错误码ID | 错误信息 | 1234| -------- | ---------------------------- | 1235|2900001 | Service stopped. | 1236|2900099 | Operation failed. | 1237 1238**示例：** 1239 1240```js 1241import { BusinessError } from '@ohos.base'; 1242// callback 1243try { 1244 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 1245 gattClient.connect(); 1246 gattClient.getDeviceName((err: BusinessError, data: string)=> { 1247 console.info('device name err ' + JSON.stringify(err)); 1248 console.info('device name' + JSON.stringify(data)); 1249 }) 1250} catch (err) { 1251 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1252} 1253``` 1254 1255 1256### getDeviceName 1257 1258getDeviceName(): Promise<string> 1259 1260client获取远端蓝牙低功耗设备名。 1261 1262**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1263 1264**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1265 1266**返回值：** 1267 1268| 类型 | 说明 | 1269| --------------------- | ---------------------------------- | 1270| Promise<string> | client获取对端server设备名，通过promise形式获取。 | 1271 1272**错误码**： 1273 1274以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1275 1276| 错误码ID | 错误信息 | 1277| -------- | ---------------------------- | 1278|2900001 | Service stopped. | 1279|2900099 | Operation failed. | 1280 1281**示例：** 1282 1283```js 1284import { BusinessError } from '@ohos.base'; 1285// promise 1286try { 1287 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 1288 gattClient.connect(); 1289 gattClient.getDeviceName().then((data: string) => { 1290 console.info('device name' + JSON.stringify(data)); 1291 }) 1292} catch (err) { 1293 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1294} 1295``` 1296 1297 1298### getServices 1299 1300getServices(callback: AsyncCallback<Array<GattService>>): void 1301 1302client端获取蓝牙低功耗设备的所有服务，即服务发现 。 1303 1304**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1305 1306**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1307 1308**参数：** 1309 1310| 参数名 | 类型 | 必填 | 说明 | 1311| -------- | ---------------------------------------- | ---- | ------------------------ | 1312| callback | AsyncCallback<Array<[GattService](#gattservice)>> | 是 | client进行服务发现，通过注册回调函数获取。 | 1313 1314**错误码**： 1315 1316以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1317 1318| 错误码ID | 错误信息 | 1319| -------- | ---------------------------- | 1320|2900001 | Service stopped. | 1321|2900099 | Operation failed. | 1322 1323**示例：** 1324 1325```js 1326import { BusinessError } from '@ohos.base'; 1327// callkback 模式 1328function getServices(code: BusinessError, gattServices: Array<ble.GattService>) { 1329 if (code.code == 0) { 1330 let services: Array<ble.GattService> = gattServices; 1331 console.log('bluetooth code is ' + code.code); 1332 console.log('bluetooth services size is ', services.length); 1333 1334 for (let i = 0; i < services.length; i++) { 1335 console.log('bluetooth serviceUuid is ' + services[i].serviceUuid); 1336 } 1337 } 1338} 1339 1340try { 1341 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1342 device.connect(); 1343 device.getServices(getServices); 1344} catch (err) { 1345 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1346} 1347``` 1348 1349 1350### getServices 1351 1352getServices(): Promise<Array<GattService>> 1353 1354client端获取蓝牙低功耗设备的所有服务，即服务发现。 1355 1356**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1357 1358**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1359 1360**返回值：** 1361 1362| 类型 | 说明 | 1363| ---------------------------------------- | --------------------------- | 1364| Promise<Array<[GattService](#gattservice)>> | client进行服务发现，通过promise形式获取。 | 1365 1366**错误码**： 1367 1368以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1369 1370| 错误码ID | 错误信息 | 1371| -------- | ---------------------------- | 1372|2900001 | Service stopped. | 1373|2900099 | Operation failed. | 1374 1375**示例：** 1376 1377```js 1378import { BusinessError } from '@ohos.base'; 1379// Promise 模式 1380try { 1381 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1382 device.connect(); 1383 device.getServices().then((result: Array<ble.GattService>) => { 1384 console.info('getServices successfully:' + JSON.stringify(result)); 1385 }); 1386} catch (err) { 1387 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1388} 1389``` 1390 1391 1392### readCharacteristicValue 1393 1394readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void 1395 1396client端读取蓝牙低功耗设备特定服务的特征值。 1397 1398**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1399 1400**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1401 1402**参数：** 1403 1404| 参数名 | 类型 | 必填 | 说明 | 1405| -------------- | ---------------------------------------- | ---- | ----------------------- | 1406| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 1407| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | 是 | client读取特征值，通过注册回调函数获取。 | 1408 1409**错误码**： 1410 1411以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1412 1413| 错误码ID | 错误信息 | 1414| -------- | ---------------------------- | 1415|2900001 | Service stopped. | 1416|2901000 | Read forbidden. | 1417|2900099 | Operation failed. | 1418 1419**示例：** 1420 1421```js 1422import { BusinessError } from '@ohos.base'; 1423function readCcc(code: BusinessError, BLECharacteristic: ble.BLECharacteristic) { 1424 if (code.code != 0) { 1425 return; 1426 } 1427 console.log('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); 1428 let value = new Uint8Array(BLECharacteristic.characteristicValue); 1429 console.log('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 1430} 1431 1432let descriptors: Array<ble.BLEDescriptor> = []; 1433let bufferDesc = new ArrayBuffer(8); 1434let descV = new Uint8Array(bufferDesc); 1435descV[0] = 11; 1436let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1437characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1438descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 1439descriptors[0] = descriptor; 1440 1441let bufferCCC = new ArrayBuffer(8); 1442let cccV = new Uint8Array(bufferCCC); 1443cccV[0] = 1; 1444let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1445characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1446characteristicValue: bufferCCC, descriptors:descriptors}; 1447 1448try { 1449 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1450 device.readCharacteristicValue(characteristic, readCcc); 1451} catch (err) { 1452 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1453} 1454``` 1455 1456 1457### readCharacteristicValue 1458 1459readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> 1460 1461client端读取蓝牙低功耗设备特定服务的特征值。 1462 1463**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1464 1465**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1466 1467**参数：** 1468 1469| 参数名 | 类型 | 必填 | 说明 | 1470| -------------- | --------------------------------------- | ---- | -------- | 1471| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 待读取的特征值。 | 1472 1473**返回值：** 1474 1475| 类型 | 说明 | 1476| ---------------------------------------- | -------------------------- | 1477| Promise<[BLECharacteristic](#blecharacteristic)> | client读取特征值，通过promise形式获取。 | 1478 1479**错误码**： 1480 1481以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1482 1483| 错误码ID | 错误信息 | 1484| -------- | ---------------------------- | 1485|2900001 | Service stopped. | 1486|2901000 | Read forbidden. | 1487|2900099 | Operation failed. | 1488 1489**示例：** 1490 1491```js 1492import { BusinessError } from '@ohos.base'; 1493let descriptors: Array<ble.BLEDescriptor> = []; 1494let bufferDesc = new ArrayBuffer(8); 1495let descV = new Uint8Array(bufferDesc); 1496descV[0] = 11; 1497let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1498characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1499descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 1500descriptors[0] = descriptor; 1501 1502let bufferCCC = new ArrayBuffer(8); 1503let cccV = new Uint8Array(bufferCCC); 1504cccV[0] = 1; 1505let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1506characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1507characteristicValue: bufferCCC, descriptors:descriptors}; 1508 1509try { 1510 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1511 device.readCharacteristicValue(characteristic); 1512} catch (err) { 1513 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1514} 1515``` 1516 1517 1518### readDescriptorValue 1519 1520readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void 1521 1522client端读取蓝牙低功耗设备特定的特征包含的描述符。 1523 1524**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1525 1526**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1527 1528**参数：** 1529 1530| 参数名 | 类型 | 必填 | 说明 | 1531| ---------- | ---------------------------------------- | ---- | ----------------------- | 1532| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 1533| callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | 是 | client读取描述符，通过注册回调函数获取。 | 1534 1535**错误码**： 1536 1537以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1538 1539| 错误码ID | 错误信息 | 1540| -------- | ---------------------------- | 1541|2900001 | Service stopped. | 1542|2901000 | Read forbidden. | 1543|2900099 | Operation failed. | 1544 1545**示例：** 1546 1547```js 1548import { BusinessError } from '@ohos.base'; 1549function readDesc(code: BusinessError, BLEDescriptor: ble.BLEDescriptor) { 1550 if (code.code != 0) { 1551 return; 1552 } 1553 console.log('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); 1554 let value = new Uint8Array(BLEDescriptor.descriptorValue); 1555 console.log('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 1556} 1557 1558let bufferDesc = new ArrayBuffer(8); 1559let descV = new Uint8Array(bufferDesc); 1560descV[0] = 11; 1561let descriptor: ble.BLEDescriptor = { 1562 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1563 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1564 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 1565 descriptorValue: bufferDesc 1566}; 1567try { 1568 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1569 device.readDescriptorValue(descriptor, readDesc); 1570} catch (err) { 1571 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1572} 1573``` 1574 1575 1576### readDescriptorValue 1577 1578readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> 1579 1580client端读取蓝牙低功耗设备特定的特征包含的描述符。 1581 1582**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1583 1584**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1585 1586**参数：** 1587 1588| 参数名 | 类型 | 必填 | 说明 | 1589| ---------- | ------------------------------- | ---- | -------- | 1590| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 待读取的描述符。 | 1591 1592**返回值：** 1593 1594| 类型 | 说明 | 1595| ---------------------------------------- | -------------------------- | 1596| Promise<[BLEDescriptor](#bledescriptor)> | client读取描述符，通过promise形式获取。 | 1597 1598**错误码**： 1599 1600以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1601 1602| 错误码ID | 错误信息 | 1603| -------- | ---------------------------- | 1604|2900001 | Service stopped. | 1605|2901000 | Read forbidden. | 1606|2900099 | Operation failed. | 1607 1608**示例：** 1609 1610```js 1611import { BusinessError } from '@ohos.base'; 1612let bufferDesc = new ArrayBuffer(8); 1613let descV = new Uint8Array(bufferDesc); 1614descV[0] = 11; 1615let descriptor: ble.BLEDescriptor = { 1616 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1617 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1618 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 1619 descriptorValue: bufferDesc 1620}; 1621try { 1622 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1623 device.readDescriptorValue(descriptor); 1624} catch (err) { 1625 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1626} 1627``` 1628 1629 1630### writeCharacteristicValue 1631 1632writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void 1633 1634client端向低功耗蓝牙设备写入特定的特征值。 1635 1636**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1637 1638**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1639 1640**参数：** 1641 1642| 参数名 | 类型 | 必填 | 说明 | 1643| -------------- | --------------------------------------- | ---- | ------------------- | 1644| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 1645| writeType | GattWriteType | 是 | 蓝牙设备特征的写入类型。 | 1646| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 1647 1648**错误码**： 1649 1650以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1651 1652| 错误码ID | 错误信息 | 1653| -------- | ---------------------------- | 1654|2900001 | Service stopped. | 1655|2901001 | Write forbidden. | 1656|2900099 | Operation failed. | 1657 1658**示例：** 1659 1660```js 1661import { BusinessError } from '@ohos.base'; 1662let descriptors: Array<ble.BLEDescriptor> = []; 1663let bufferDesc = new ArrayBuffer(8); 1664let descV = new Uint8Array(bufferDesc); 1665descV[0] = 11; 1666let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1667 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1668 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 1669descriptors[0] = descriptor; 1670 1671let bufferCCC = new ArrayBuffer(8); 1672let cccV = new Uint8Array(bufferCCC); 1673cccV[0] = 1; 1674let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1675 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1676 characteristicValue: bufferCCC, descriptors:descriptors}; 1677function writeCharacteristicValueCallBack(code: BusinessError) { 1678 if (code.code != 0) { 1679 return; 1680 } 1681 console.log('bluetooth writeCharacteristicValue success'); 1682} 1683try { 1684 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1685 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack); 1686} catch (err) { 1687 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1688} 1689``` 1690 1691 1692### writeCharacteristicValue 1693 1694writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> 1695 1696client端向低功耗蓝牙设备写入特定的特征值。 1697 1698**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1699 1700**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1701 1702**参数：** 1703 1704| 参数名 | 类型 | 必填 | 说明 | 1705| -------------- | --------------------------------------- | ---- | ------------------- | 1706| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙设备特征对应的二进制值及其它参数。 | 1707| writeType | GattWriteType | 是 | 蓝牙设备特征的写入类型。 | 1708 1709**返回值：** 1710 1711| 类型 | 说明 | 1712| ---------------------------------------- | -------------------------- | 1713| Promise<void> | client读取描述符，通过promise形式获取。 | 1714 1715**错误码**： 1716 1717以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1718 1719| 错误码ID | 错误信息 | 1720| -------- | ---------------------------- | 1721|2900001 | Service stopped. | 1722|2901001 | Write forbidden. | 1723|2900099 | Operation failed. | 1724 1725**示例：** 1726 1727```js 1728import { BusinessError } from '@ohos.base'; 1729let descriptors: Array<ble.BLEDescriptor> = []; 1730let bufferDesc = new ArrayBuffer(8); 1731let descV = new Uint8Array(bufferDesc); 1732descV[0] = 11; 1733let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1734 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1735 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 1736descriptors[0] = descriptor; 1737 1738let bufferCCC = new ArrayBuffer(8); 1739let cccV = new Uint8Array(bufferCCC); 1740cccV[0] = 1; 1741let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1742 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1743 characteristicValue: bufferCCC, descriptors:descriptors}; 1744try { 1745 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1746 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE); 1747} catch (err) { 1748 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1749} 1750``` 1751 1752 1753### writeDescriptorValue 1754 1755writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void 1756 1757client端向低功耗蓝牙设备特定的描述符写入二进制数据。 1758 1759**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1760 1761**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1762 1763**参数：** 1764 1765| 参数名 | 类型 | 必填 | 说明 | 1766| ---------- | ------------------------------- | ---- | ------------------ | 1767| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 1768| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 1769 1770**错误码**： 1771 1772以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1773 1774| 错误码ID | 错误信息 | 1775| -------- | ---------------------------- | 1776|2900001 | Service stopped. | 1777|2901001 | Write forbidden. | 1778|2900099 | Operation failed. | 1779 1780**示例：** 1781 1782```js 1783import { BusinessError } from '@ohos.base'; 1784let bufferDesc = new ArrayBuffer(8); 1785let descV = new Uint8Array(bufferDesc); 1786descV[0] = 22; 1787let descriptor: ble.BLEDescriptor = { 1788 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1789 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1790 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 1791 descriptorValue: bufferDesc 1792}; 1793try { 1794 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1795 device.writeDescriptorValue(descriptor); 1796} catch (err) { 1797 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1798} 1799``` 1800 1801 1802### writeDescriptorValue 1803 1804writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> 1805 1806client端向低功耗蓝牙设备特定的描述符写入二进制数据。 1807 1808**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1809 1810**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1811 1812**参数：** 1813 1814| 参数名 | 类型 | 必填 | 说明 | 1815| ---------- | ------------------------------- | ---- | ------------------ | 1816| descriptor | [BLEDescriptor](#bledescriptor) | 是 | 蓝牙设备描述符的二进制值及其它参数。 | 1817 1818**返回值：** 1819 1820| 类型 | 说明 | 1821| ---------------------------------------- | -------------------------- | 1822| Promise<void> | client读取描述符，通过promise形式获取。 | 1823 1824**错误码**： 1825 1826以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1827 1828| 错误码ID | 错误信息 | 1829| -------- | ---------------------------- | 1830|2900001 | Service stopped. | 1831|2901001 | Write forbidden. | 1832|2900099 | Operation failed. | 1833 1834**示例：** 1835 1836```js 1837import { BusinessError } from '@ohos.base'; 1838let bufferDesc = new ArrayBuffer(8); 1839let descV = new Uint8Array(bufferDesc); 1840descV[0] = 22; 1841let descriptor: ble.BLEDescriptor = { 1842 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1843 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1844 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 1845 descriptorValue: bufferDesc 1846}; 1847try { 1848 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1849 device.writeDescriptorValue(descriptor); 1850} catch (err) { 1851 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1852} 1853``` 1854 1855 1856### getRssiValue 1857 1858getRssiValue(callback: AsyncCallback<number>): void 1859 1860client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 1861 1862**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1863 1864**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1865 1866**参数：** 1867 1868| 参数名 | 类型 | 必填 | 说明 | 1869| -------- | --------------------------- | ---- | ------------------------------ | 1870| callback | AsyncCallback<number> | 是 | 返回信号强度，单位 dBm，通过注册回调函数获取。 | 1871 1872**错误码**： 1873 1874以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1875 1876| 错误码ID | 错误信息 | 1877| -------- | ---------------------------- | 1878|2900099 | Operation failed. | 1879 1880**示例：** 1881 1882```js 1883import { BusinessError } from '@ohos.base'; 1884// callback 1885try { 1886 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 1887 gattClient.connect(); 1888 let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> { 1889 console.info('rssi err ' + JSON.stringify(err)); 1890 console.info('rssi value' + JSON.stringify(data)); 1891 }) 1892} catch (err) { 1893 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1894} 1895``` 1896 1897 1898### getRssiValue 1899 1900getRssiValue(): Promise<number> 1901 1902client获取远端蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)，调用[connect](#connect)接口连接成功后才能使用。 1903 1904**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1905 1906**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1907 1908**返回值：** 1909 1910| 类型 | 说明 | 1911| --------------------- | --------------------------------- | 1912| Promise<number> | 返回信号强度，单位 dBm，通过promise形式获取。 | 1913 1914**错误码**： 1915 1916以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1917 1918| 错误码ID | 错误信息 | 1919| -------- | ---------------------------- | 1920|2900099 | Operation failed. | 1921 1922**示例：** 1923 1924```js 1925import { BusinessError } from '@ohos.base'; 1926// promise 1927try { 1928 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 1929 gattClient.getRssiValue().then((data: number) => { 1930 console.info('rssi' + JSON.stringify(data)); 1931 }) 1932} catch (err) { 1933 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1934} 1935``` 1936 1937 1938### setBLEMtuSize 1939 1940setBLEMtuSize(mtu: number): void 1941 1942client协商远端蓝牙低功耗设备的最大传输单元（Maximum Transmission Unit, MTU），调用[connect](#connect)接口连接成功后才能使用。 1943 1944**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1945 1946**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1947 1948**参数：** 1949 1950| 参数名 | 类型 | 必填 | 说明 | 1951| ---- | ------ | ---- | -------------- | 1952| mtu | number | 是 | 设置范围为22~512字节。 | 1953 1954**错误码**： 1955 1956以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1957 1958| 错误码ID | 错误信息 | 1959| -------- | ---------------------------- | 1960|2900001 | Service stopped. | 1961|2900099 | Operation failed. | 1962 1963**示例：** 1964 1965```js 1966import { BusinessError } from '@ohos.base'; 1967try { 1968 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 1969 device.setBLEMtuSize(128); 1970} catch (err) { 1971 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1972} 1973``` 1974 1975 1976### setCharacteristicChangeNotification 1977 1978setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 1979 1980向服务端发送设置通知此特征值请求。 1981 1982**需要权限**：ohos.permission.ACCESS_BLUETOOTH 1983 1984**系统能力**：SystemCapability.Communication.Bluetooth.Core。 1985 1986**参数：** 1987 1988| 参数名 | 类型 | 必填 | 说明 | 1989| -------------- | --------------------------------------- | ---- | ----------------------------- | 1990| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 1991| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 1992| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 1993 1994**错误码**： 1995 1996以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 1997 1998| 错误码ID | 错误信息 | 1999| -------- | ---------------------------- | 2000|2900001 | Service stopped. | 2001|2900099 | Operation failed. | 2002 2003**示例：** 2004 2005```js 2006import { BusinessError } from '@ohos.base'; 2007// 创建descriptors 2008let descriptors: Array<ble.BLEDescriptor> = []; 2009let arrayBuffer = new ArrayBuffer(8); 2010let descV = new Uint8Array(arrayBuffer); 2011descV[0] = 11; 2012let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2013 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2014 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2015descriptors[0] = descriptor; 2016let arrayBufferC = new ArrayBuffer(8); 2017let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2018 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2019try { 2020 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2021 device.setCharacteristicChangeNotification(characteristic, false); 2022} catch (err) { 2023 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2024} 2025 2026``` 2027 2028 2029### setCharacteristicChangeNotification 2030 2031setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> 2032 2033向服务端发送设置通知此特征值请求。 2034 2035**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2036 2037**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2038 2039**参数：** 2040 2041| 参数名 | 类型 | 必填 | 说明 | 2042| -------------- | --------------------------------------- | ---- | ----------------------------- | 2043| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 2044| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 2045 2046**返回值：** 2047 2048| 类型 | 说明 | 2049| ---------------------------------------- | -------------------------- | 2050| Promise<void> | 返回Promise对象。 | 2051 2052**错误码**： 2053 2054以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 2055 2056| 错误码ID | 错误信息 | 2057| -------- | ---------------------------- | 2058|2900001 | Service stopped. | 2059|2900099 | Operation failed. | 2060 2061**示例：** 2062 2063```js 2064import { BusinessError } from '@ohos.base'; 2065// 创建descriptors 2066let descriptors: Array<ble.BLEDescriptor> = []; 2067let arrayBuffer = new ArrayBuffer(8); 2068let descV = new Uint8Array(arrayBuffer); 2069descV[0] = 11; 2070let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2071 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2072 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2073descriptors[0] = descriptor; 2074let arrayBufferC = new ArrayBuffer(8); 2075let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2076 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2077try { 2078 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2079 device.setCharacteristicChangeNotification(characteristic, false); 2080} catch (err) { 2081 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2082} 2083 2084``` 2085 2086 2087### setCharacteristicChangeIndication 2088 2089setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 2090 2091向服务端发送设置通知此特征值请求。 2092 2093**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2094 2095**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2096 2097**参数：** 2098 2099| 参数名 | 类型 | 必填 | 说明 | 2100| -------------- | --------------------------------------- | ---- | ----------------------------- | 2101| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 2102| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 2103| callback | AsyncCallback<void> | 是 | 回调函数。当发送成功，err为undefined，否则为错误对象。 | 2104 2105**返回值：** 2106 2107| 类型 | 说明 | 2108| ---------------------------------------- | -------------------------- | 2109| Promise<void> | 返回Promise对象。 | 2110 2111**错误码**： 2112 2113以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 2114 2115| 错误码ID | 错误信息 | 2116| -------- | ---------------------------- | 2117|2900001 | Service stopped. | 2118|2900099 | Operation failed. | 2119 2120**示例：** 2121 2122```js 2123import { BusinessError } from '@ohos.base'; 2124// 创建descriptors 2125let descriptors: Array<ble.BLEDescriptor> = []; 2126let arrayBuffer = new ArrayBuffer(8); 2127let descV = new Uint8Array(arrayBuffer); 2128descV[0] = 11; 2129let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2130 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2131 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2132descriptors[0] = descriptor; 2133let arrayBufferC = new ArrayBuffer(8); 2134let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2135 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2136try { 2137 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2138 device.setCharacteristicChangeIndication(characteristic, false); 2139} catch (err) { 2140 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2141} 2142 2143``` 2144 2145 2146### setCharacteristicChangeIndication 2147 2148setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> 2149 2150向服务端发送设置通知此特征值请求。 2151 2152**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2153 2154**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2155 2156**参数：** 2157 2158| 参数名 | 类型 | 必填 | 说明 | 2159| -------------- | --------------------------------------- | ---- | ----------------------------- | 2160| characteristic | [BLECharacteristic](#blecharacteristic) | 是 | 蓝牙低功耗特征。 | 2161| enable | boolean | 是 | 启用接收notify设置为true，否则设置为false。 | 2162 2163**返回值：** 2164 2165| 类型 | 说明 | 2166| ---------------------------------------- | -------------------------- | 2167| Promise<void> | 返回Promise对象。 | 2168 2169**错误码**： 2170 2171以下错误码的详细介绍请参见[蓝牙服务子系统错误码](../errorcodes/errorcode-bluetoothManager.md)。 2172 2173| 错误码ID | 错误信息 | 2174| -------- | ---------------------------- | 2175|2900001 | Service stopped. | 2176|2900099 | Operation failed. | 2177 2178**示例：** 2179 2180```js 2181import { BusinessError } from '@ohos.base'; 2182// 创建descriptors 2183let descriptors: Array<ble.BLEDescriptor> = []; 2184let arrayBuffer = new ArrayBuffer(8); 2185let descV = new Uint8Array(arrayBuffer); 2186descV[0] = 11; 2187let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2188 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2189 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2190descriptors[0] = descriptor; 2191let arrayBufferC = new ArrayBuffer(8); 2192let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2193 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2194try { 2195 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2196 device.setCharacteristicChangeIndication(characteristic, false); 2197} catch (err) { 2198 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2199} 2200 2201``` 2202 2203 2204### on('BLECharacteristicChange') 2205 2206on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void 2207 2208订阅蓝牙低功耗设备的特征值变化事件。需要先调用setNotifyCharacteristicChanged接口才能接收server端的通知。 2209 2210**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2211 2212**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2213 2214**参数：** 2215 2216| 参数名 | 类型 | 必填 | 说明 | 2217| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2218| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 2219| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 是 | 表示蓝牙低功耗设备的特征值变化事件的回调函数。 | 2220 2221**示例：** 2222 2223```js 2224import { BusinessError } from '@ohos.base'; 2225function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) { 2226 let serviceUuid: string = characteristicChangeReq.serviceUuid; 2227 let characteristicUuid: string = characteristicChangeReq.characteristicUuid; 2228 let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue); 2229} 2230try { 2231 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2232 device.on('BLECharacteristicChange', CharacteristicChange); 2233} catch (err) { 2234 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2235} 2236``` 2237 2238 2239### off('BLECharacteristicChange') 2240 2241off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void 2242 2243取消订阅蓝牙低功耗设备的特征值变化事件。 2244 2245**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2246 2247**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2248 2249**参数：** 2250 2251| 参数名 | 类型 | 必填 | 说明 | 2252| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2253| type | string | 是 | 填写"BLECharacteristicChange"字符串，表示特征值变化事件。 | 2254| callback | Callback<[BLECharacteristic](#blecharacteristic)> | 否 | 表示取消订阅蓝牙低功耗设备的特征值变化事件。不填该参数则取消订阅该type对应的所有回调。 | 2255 2256**示例：** 2257 2258```js 2259import { BusinessError } from '@ohos.base'; 2260try { 2261 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2262 device.off('BLECharacteristicChange'); 2263} catch (err) { 2264 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2265} 2266``` 2267 2268 2269### on('BLEConnectionStateChange') 2270 2271on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void 2272 2273client端订阅蓝牙低功耗设备的连接状态变化事件。 2274 2275**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2276 2277**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2278 2279**参数：** 2280 2281| 参数名 | 类型 | 必填 | 说明 | 2282| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2283| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 2284| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 是 | 表示连接状态，已连接或断开。 | 2285 2286**示例：** 2287 2288```js 2289import { BusinessError } from '@ohos.base'; 2290function ConnectStateChanged(state: ble.BLEConnectionChangeState) { 2291 console.log('bluetooth connect state changed'); 2292 let connectState: ble.ProfileConnectionState = state.state; 2293} 2294try { 2295 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2296 device.on('BLEConnectionStateChange', ConnectStateChanged); 2297} catch (err) { 2298 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2299} 2300``` 2301 2302 2303### off('BLEConnectionStateChange') 2304 2305off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 2306 2307取消订阅蓝牙低功耗设备的连接状态变化事件。 2308 2309**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2310 2311**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2312 2313**参数：** 2314 2315| 参数名 | 类型 | 必填 | 说明 | 2316| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2317| type | string | 是 | 填写"BLEConnectionStateChange"字符串，表示连接状态变化事件。 | 2318| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | 否 | 表示取消订阅蓝牙低功耗设备的连接状态变化事件。不填该参数则取消订阅该type对应的所有回调。 | 2319 2320**示例：** 2321 2322```js 2323import { BusinessError } from '@ohos.base'; 2324try { 2325 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2326 device.off('BLEConnectionStateChange'); 2327} catch (err) { 2328 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2329} 2330``` 2331 2332 2333### on('BLEMtuChange') 2334 2335on(type: 'BLEMtuChange', callback: Callback<number>): void 2336 2337client端订阅MTU状态变化事件。 2338 2339**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2340 2341**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2342 2343**参数：** 2344 2345| 参数名 | 类型 | 必填 | 说明 | 2346| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2347| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2348| callback | Callback<number> | 是 | 返回MTU字节数的值，通过注册回调函数获取。 | 2349 2350**示例：** 2351 2352```js 2353import { BusinessError } from '@ohos.base'; 2354try { 2355 let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2356 gattClient.on('BLEMtuChange', (mtu: number) => { 2357 console.info('BLEMtuChange, mtu: ' + mtu); 2358 }); 2359} catch (err) { 2360 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2361} 2362``` 2363 2364 2365### off('BLEMtuChange') 2366 2367off(type: 'BLEMtuChange', callback?: Callback<number>): void 2368 2369client端取消订阅MTU状态变化事件。 2370 2371**需要权限**：ohos.permission.ACCESS_BLUETOOTH 2372 2373**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2374 2375**参数：** 2376 2377| 参数名 | 类型 | 必填 | 说明 | 2378| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 2379| type | string | 是 | 必须填写"BLEMtuChange"字符串，表示MTU状态变化事件。填写不正确将导致回调无法注册。 | 2380| callback | Callback<number> | 否 | 返回MTU字节数的值，通过注册回调函数获取。不填该参数则取消订阅该type对应的所有回调。 | 2381 2382**示例：** 2383 2384```js 2385import { BusinessError } from '@ohos.base'; 2386try { 2387 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2388 device.off('BLEMtuChange'); 2389} catch (err) { 2390 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2391} 2392``` 2393 2394 2395## GattService 2396 2397描述service的接口参数定义。 2398 2399**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2400 2401| 名称 | 类型 | 可读 | 可写 | 说明 | 2402| --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 2403| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2404| isPrimary | boolean | 是 | 是 | 如果是主服务设置为true，否则设置为false。 | 2405| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | 是 | 是 | 当前服务包含的特征列表。 | 2406| includeServices | Array<[GattService](#gattservice)> | 是 | 是 | 当前服务依赖的其它服务。 | 2407 2408 2409## BLECharacteristic 2410 2411描述characteristic的接口参数定义 。 2412 2413**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2414 2415| 名称 | 类型 | 可读 | 可写 | 说明 | 2416| ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 2417| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2418| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2419| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 2420| descriptors | Array<[BLEDescriptor](#bledescriptor)> | 是 | 是 | 特定特征的描述符列表。 | 2421| properties | [GattProperties](#gattproperties) | 是 | 是 | 特定特征的属性描述。 | 2422 2423 2424## BLEDescriptor 2425 2426描述descriptor的接口参数定义 。 2427 2428**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2429 2430| 名称 | 类型 | 可读 | 可写 | 说明 | 2431| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 2432| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2433| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2434| descriptorUuid | string | 是 | 是 | 描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | 2435| descriptorValue | ArrayBuffer | 是 | 是 | 描述符对应的二进制值。 | 2436 2437 2438## NotifyCharacteristic 2439 2440描述server端特征值变化时发送的特征通知参数定义。 2441 2442**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2443 2444| 名称 | 类型 | 可读 | 可写 | 说明 | 2445| ------------------- | ----------- | ---- | ---- | ---------------------------------------- | 2446| serviceUuid | string | 是 | 是 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2447| characteristicUuid | string | 是 | 是 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2448| characteristicValue | ArrayBuffer | 是 | 是 | 特征对应的二进制值。 | 2449| confirm | boolean | 是 | 是 | 如果是notification则对端回复确认设置为true，如果是indication则对端不需要回复确认设置为false。 | 2450 2451 2452## CharacteristicReadRequest 2453 2454描述server端订阅后收到的特征值读请求事件参数结构。 2455 2456**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2457 2458| 名称 | 类型 | 可读 | 可写 | 说明 | 2459| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 2460| deviceId | string | 是 | 否 | 表示发送特征值读请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2461| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 2462| offset | number | 是 | 否 | 表示读特征值数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 2463| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2464| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2465 2466 2467## CharacteristicWriteRequest 2468 2469描述server端订阅后收到的特征值写请求事件参数结构。 2470 2471**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2472 2473| 名称 | 类型 | 可读 | 可写 | 说明 | 2474| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 2475| deviceId | string | 是 | 否 | 表示发送特征值写请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2476| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 2477| offset | number | 是 | 否 | 表示写特征值数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 2478| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | 2479| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | 2480| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 2481| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2482| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2483 2484 2485## DescriptorReadRequest 2486 2487描述server端订阅后收到的描述符读请求事件参数结构。 2488 2489**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2490 2491| 名称 | 类型 | 可读 | 可写 | 说明 | 2492| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 2493| deviceId | string | 是 | 否 | 表示发送描述符读请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2494| transId | number | 是 | 否 | 表示读请求的传输ID，server端回复响应时需填写相同的传输ID。 | 2495| offset | number | 是 | 否 | 表示读描述符数据的起始位置。例如：k表示从第k个字节开始读，server端回复响应时需填写相同的offset。 | 2496| descriptorUuid | string | 是 | 否 | 表示描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | 2497| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2498| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2499 2500 2501## DescriptorWriteRequest 2502 2503描述server端订阅后收到的描述符写请求事件参数结构。 2504 2505**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2506 2507| 名称 | 类型 | 可读 | 可写 | 说明 | 2508| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 2509| deviceId | string | 是 | 否 | 表示发送描述符写请求的远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2510| transId | number | 是 | 否 | 表示写请求的传输ID，server端回复响应时需填写相同的传输ID。 | 2511| offset | number | 是 | 否 | 表示写描述符数据的起始位置。例如：k表示从第k个字节开始写，server端回复响应时需填写相同的offset。 | 2512| isPrepared | boolean | 是 | 否 | 表示写请求是否立即执行。 | 2513| needRsp | boolean | 是 | 否 | 表示是否要给client端回复响应。 | 2514| value | ArrayBuffer | 是 | 否 | 表示写入的描述符二进制数据。 | 2515| descriptorUuid | string | 是 | 否 | 表示描述符（descriptor）的UUID，例如：00002902-0000-1000-8000-00805f9b34fb。 | 2516| characteristicUuid | string | 是 | 否 | 特定特征（characteristic）的UUID，例如：00002a11-0000-1000-8000-00805f9b34fb。 | 2517| serviceUuid | string | 是 | 否 | 特定服务（service）的UUID，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2518 2519 2520## ServerResponse 2521 2522描述server端回复client端读/写请求的响应参数结构。 2523 2524**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2525 2526| 名称 | 类型 | 可读 | 可写 | 说明 | 2527| -------- | ----------- | ---- | ---- | -------------------------------------- | 2528| deviceId | string | 是 | 否 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2529| transId | number | 是 | 否 | 表示请求的传输ID，与订阅的读/写请求事件携带的ID保持一致。 | 2530| status | number | 是 | 否 | 表示响应的状态，设置为0即可，表示正常。 | 2531| offset | number | 是 | 否 | 表示请求的读/写起始位置，与订阅的读/写请求事件携带的offset保持一致。 | 2532| value | ArrayBuffer | 是 | 否 | 表示回复响应的二进制数据。 | 2533 2534 2535## BLEConnectionChangeState 2536 2537描述Gatt profile连接状态 。 2538 2539**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2540 2541| 名称 | 类型 | 可读 | 可写 | 说明 | 2542| -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | 2543| deviceId | string | 是 | 否 | 表示远端设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2544| state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 是 | 是 | 表示BLE连接状态的枚举。 | 2545 2546 2547## ScanResult 2548 2549扫描结果上报数据。 2550 2551**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2552 2553| 名称 | 类型 | 可读 | 可写 | 说明 | 2554| -------- | ----------- | ---- | ---- | ---------------------------------- | 2555| deviceId | string | 是 | 否 | 表示扫描到的设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2556| rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | 2557| data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | 2558| deviceName | string | 是 | 否 | 表示扫描到的设备名称。 | 2559| connectable | boolean | 是 | 否 | 表示扫描到的设备是否可连接。 | 2560 2561 2562## AdvertiseSetting 2563 2564描述蓝牙低功耗设备发送广播的参数。 2565 2566**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2567 2568| 名称 | 类型 | 可读 | 可写 | 说明 | 2569| ----------- | ------- | ---- | ---- | ---------------------------------------- | 2570| interval | number | 是 | 是 | 表示广播间隔，最小值设置32个slot表示20ms，最大值设置16384个slot，默认值设置为1600个slot表示1s。 | 2571| txPower | number | 是 | 是 | 表示发送功率，最小值设置-127，最大值设置1，默认值设置-7，单位dbm。 | 2572| connectable | boolean | 是 | 是 | 表示是否是可连接广播，默认值设置为true。 | 2573 2574 2575## AdvertiseData 2576 2577描述BLE广播数据包的内容。 2578 2579**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2580 2581| 名称 | 类型 | 可读 | 可写 | 说明 | 2582| --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | 2583| serviceUuids | Array<string> | 是 | 是 | 表示要广播的服务 UUID 列表。 | 2584| manufactureData | Array<[ManufactureData](#manufacturedata)> | 是 | 是 | 表示要广播的广播的制造商信息列表。 | 2585| serviceData | Array<[ServiceData](#servicedata)> | 是 | 是 | 表示要广播的服务数据列表。 | 2586| includeDeviceName | boolean | 是 | 是 | 表示是否携带设备名，可选参数。 | 2587 2588 2589## ManufactureData 2590 2591描述BLE广播数据包的内容。 2592 2593**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2594 2595| 名称 | 类型 | 可读 | 可写 | 说明 | 2596| ---------------- | ------------------- | ---- | ---- | ------------------ | 2597| manufactureId | number | 是 | 是 | 表示制造商的ID，由蓝牙SIG分配。 | 2598| manufactureValue | ArrayBuffer | 是 | 是 | 表示制造商发送的制造商数据。 | 2599 2600 2601## ServiceData 2602 2603描述广播包中服务数据内容。 2604 2605**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2606 2607| 名称 | 类型 | 可读 | 可写 | 说明 | 2608| ------------ | ----------- | ---- | ---- | ---------- | 2609| serviceUuid | string | 是 | 是 | 表示服务的UUID。 | 2610| serviceValue | ArrayBuffer | 是 | 是 | 表示服务数据。 | 2611 2612 2613## ScanFilter 2614 2615扫描过滤参数。 2616 2617**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2618 2619| 名称 | 类型 | 可读 | 可写 | 说明 | 2620| ---------------------------------------- | ----------- | ---- | ---- | ------------------------------------------------------------ | 2621| deviceId | string | 是 | 是 | 表示过滤的BLE设备地址，例如："XX:XX:XX:XX:XX:XX"。 | 2622| name | string | 是 | 是 | 表示过滤的BLE设备名。 | 2623| serviceUuid | string | 是 | 是 | 表示过滤包含该UUID服务的设备，例如：00001888-0000-1000-8000-00805f9b34fb。 | 2624| serviceUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 2625| serviceSolicitationUuid | string | 是 | 是 | 表示过滤包含该UUID服务请求的设备，例如：00001888-0000-1000-8000-00805F9B34FB。 | 2626| serviceSolicitationUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务请求掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 2627| serviceData | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据的设备，例如：[0x90,0x00,0xF1,0xF2]。 | 2628| serviceDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据掩码的设备，例如：[0xFF,0xFF,0xFF,0xFF]。 | 2629| manufactureId | number | 是 | 是 | 表示过滤包含该制造商ID的设备，例如：0x0006。 | 2630| manufactureData | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据的设备，例如：[0x1F,0x2F,0x3F]。 | 2631| manufactureDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据掩码的设备，例如：[0xFF,0xFF,0xFF]。 | 2632 2633 2634## ScanOptions 2635 2636扫描的配置参数。 2637 2638**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2639 2640| 名称 | 类型 | 可读 | 可写 | 说明 | 2641| --------- | ----------------------- | ---- | ---- | -------------------------------------- | 2642| interval | number | 是 | 是 | 表示扫描结果上报延迟时间，默认值为0。 | 2643| dutyMode | [ScanDuty](#scanduty) | 是 | 是 | 表示扫描模式，默认值为SCAN_MODE_LOW_POWER。 | 2644| matchMode | [MatchMode](#matchmode) | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。 | 2645 2646 2647## GattProperties<a name="GattProperties"></a> 2648 2649描述gatt characteristic的属性。 2650 2651**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2652 2653| 名称 | 类型 | 必填 | 说明 | 2654| -------- | ------ |---- | ----------- | 2655| write | boolean | 是 | 表示该特征支持写操作，需要对端设备的回复。 | 2656| writeNoResponse | boolean | 是 | 表示该特征支持写操作，无需对端设备回复。 | 2657| read | boolean | 是 | 表示该特征支持读操作。 | 2658| notify | boolean | 是 | 表示该特征可通知对端设备。 | 2659| indicate | boolean | 是 | 表示该特征可通知对端设备，需要对端设备的回复。 | 2660 2661 2662## GattWriteType<a name="GattWriteType"></a> 2663 2664枚举，表示gatt写入类型。 2665 2666**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2667 2668| 名称 | 值 | 说明 | 2669| ------------------------------------| ------ | --------------- | 2670| WRITE | 1 | 表示写入特征值，需要对端设备的回复。 | 2671| WRITE_NO_RESPONSE | 2 | 表示写入特征值，不需要对端设备的回复。 | 2672 2673 2674## ScanDuty 2675 2676枚举，扫描模式。 2677 2678**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2679 2680| 名称 | 值 | 说明 | 2681| --------------------- | ---- | ------------ | 2682| SCAN_MODE_LOW_POWER | 0 | 表示低功耗模式，默认值。 | 2683| SCAN_MODE_BALANCED | 1 | 表示均衡模式。 | 2684| SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | 2685 2686 2687## MatchMode 2688 2689枚举，硬件过滤匹配模式。 2690 2691**系统能力**：SystemCapability.Communication.Bluetooth.Core。 2692 2693| 名称 | 值 | 说明 | 2694| --------------------- | ---- | ---------------------------------------- | 2695| MATCH_MODE_AGGRESSIVE | 1 | 表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。 | 2696| MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | 2697