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