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'; 15``` 16 17 18## ble.createGattServer<a name="createGattServer"></a> 19 20createGattServer(): GattServer 21 22Creates a **GattServer** instance. 23 24**System capability**: SystemCapability.Communication.Bluetooth.Core 25 26**Return value** 27 28| Type | Description | 29| ----------------------------- | ---------- | 30| GattServer | **GattServer** instance created.| 31 32**Example** 33 34```js 35let gattServer: ble.GattServer = ble.createGattServer(); 36console.info('gatt success'); 37``` 38 39 40## ble.createGattClientDevice<a name="createGattClientDevice"></a> 41 42createGattClientDevice(deviceId: string): GattClientDevice 43 44Creates a **GattClientDevice** instance. 45 46**System capability**: SystemCapability.Communication.Bluetooth.Core 47 48**Parameters** 49 50| Name | Type | Mandatory | Description | 51| -------- | ------ | ---- | ------------------------------------ | 52| deviceId | string | Yes | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 53 54**Return value** 55 56| Type | Description | 57| ------------------------------------- | ------------------------------------ | 58| [GattClientDevice](#gattclientdevice) | **GattClientDevice** instance created. Before using an API of the client, you must create a **GattClientDevice** instance.| 59 60**Example** 61 62```js 63import { BusinessError } from '@ohos.base'; 64try { 65 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 66} catch (err) { 67 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 68} 69``` 70 71 72## ble.getConnectedBLEDevices<a name="getConnectedBLEDevices"></a> 73 74getConnectedBLEDevices(): Array<string> 75 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 101import { BusinessError } from '@ohos.base'; 102try { 103 let result: Array<string> = ble.getConnectedBLEDevices(); 104} catch (err) { 105 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 106} 107``` 108 109 110## ble.startBLEScan<a name="startBLEScan"></a> 111 112startBLEScan(filters: Array<ScanFilter>, options?: ScanOptions): void 113 114Starts BLE scanning. 115 116**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 117 118**System capability**: SystemCapability.Communication.Bluetooth.Core 119 120**Parameters** 121 122| Name | Type | Mandatory | Description | 123| ------- | -------------------------------------- | ---- | ----------------------------------- | 124| 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.| 125| options | [ScanOptions](#scanoptions) | No | Scan options. | 126 127**Error codes** 128 129For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 130 131| ID| Error Message| 132| -------- | ---------------------------- | 133|2900001 | Service stopped. | 134|2900003 | Bluetooth switch is off. | 135|2900099 | Operation failed. | 136 137**Example** 138 139```js 140import { BusinessError } from '@ohos.base'; 141function onReceiveEvent(data: Array<ble.ScanResult>) { 142 console.info('BLE scan device find result = '+ JSON.stringify(data)); 143} 144try { 145 ble.on("BLEDeviceFind", onReceiveEvent); 146 let scanFilter: ble.ScanFilter = { 147 deviceId:"XX:XX:XX:XX:XX:XX", 148 name:"test", 149 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb" 150 }; 151 let scanOptions: ble.ScanOptions = { 152 interval: 500, 153 dutyMode: ble.ScanDuty.SCAN_MODE_LOW_POWER, 154 matchMode: ble.MatchMode.MATCH_MODE_AGGRESSIVE, 155 } 156 ble.startBLEScan([scanFilter],scanOptions); 157} catch (err) { 158 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 159} 160``` 161 162 163## ble.stopBLEScan<a name="stopBLEScan"></a> 164 165stopBLEScan(): void 166 167Stops BLE scanning. 168 169**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 170 171**System capability**: SystemCapability.Communication.Bluetooth.Core 172 173**Error codes** 174 175For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 176 177| ID| Error Message| 178| -------- | ---------------------------- | 179|2900001 | Service stopped. | 180|2900003 | Bluetooth switch is off. | 181|2900099 | Operation failed. | 182 183**Example** 184 185```js 186import { BusinessError } from '@ohos.base'; 187try { 188 ble.stopBLEScan(); 189} catch (err) { 190 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 191} 192``` 193 194 195## ble.startAdvertising<a name="startAdvertising"></a> 196 197startAdvertising(setting: AdvertiseSetting, advData: AdvertiseData, advResponse?: AdvertiseData): void 198 199Starts BLE advertising. 200 201**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 202 203**System capability**: SystemCapability.Communication.Bluetooth.Core 204 205**Parameters** 206 207| Name | Type | Mandatory | Description | 208| ----------- | ------------------------------------- | ---- | -------------- | 209| setting | [AdvertiseSetting](#advertisesetting) | Yes | Settings related to BLE advertising. | 210| advData | [AdvertiseData](#advertisedata) | Yes | Content of the BLE advertisement packet. | 211| advResponse | [AdvertiseData](#advertisedata) | No | Response to the BLE scan request.| 212 213**Error codes** 214 215For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 216 217| ID| Error Message| 218| -------- | ---------------------------- | 219|2900001 | Service stopped. | 220|2900003 | Bluetooth switch is off. | 221|2900099 | Operation failed. | 222 223**Example** 224 225```js 226import { BusinessError } from '@ohos.base'; 227let manufactureValueBuffer = new Uint8Array(4); 228manufactureValueBuffer[0] = 1; 229manufactureValueBuffer[1] = 2; 230manufactureValueBuffer[2] = 3; 231manufactureValueBuffer[3] = 4; 232 233let serviceValueBuffer = new Uint8Array(4); 234serviceValueBuffer[0] = 4; 235serviceValueBuffer[1] = 6; 236serviceValueBuffer[2] = 7; 237serviceValueBuffer[3] = 8; 238console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 239console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 240try { 241 let setting: ble.AdvertiseSetting = { 242 interval:150, 243 txPower:0, 244 connectable:true, 245 }; 246 let manufactureDataUnit: ble.ManufactureData = { 247 manufactureId:4567, 248 manufactureValue:manufactureValueBuffer.buffer 249 }; 250 let serviceDataUnit: ble.ServiceData = { 251 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 252 serviceValue:serviceValueBuffer.buffer 253 }; 254 let advData: ble.AdvertiseData = { 255 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 256 manufactureData:[manufactureDataUnit], 257 serviceData:[serviceDataUnit], 258 }; 259 let advResponse: ble.AdvertiseData = { 260 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 261 manufactureData:[manufactureDataUnit], 262 serviceData:[serviceDataUnit], 263 }; 264 ble.startAdvertising(setting, advData ,advResponse); 265} catch (err) { 266 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 267} 268``` 269 270 271## ble.stopAdvertising<a name="stopAdvertising"></a> 272 273stopAdvertising(): void 274 275Stops BLE advertising. 276 277**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 278 279**System capability**: SystemCapability.Communication.Bluetooth.Core 280 281**Error codes** 282 283For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 284 285| ID| Error Message| 286| -------- | ---------------------------- | 287|2900001 | Service stopped. | 288|2900003 | Bluetooth switch is off. | 289|2900099 | Operation failed. | 290 291**Example** 292 293```js 294import { BusinessError } from '@ohos.base'; 295try { 296 ble.stopAdvertising(); 297} catch (err) { 298 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 299} 300``` 301 302 303## ble.startAdvertising<sup>11+</sup><a name="startAdvertising"></a> 304 305startAdvertising(advertisingParams: AdvertisingParams, callback: AsyncCallback<number>): void 306 307Starts BLE advertising. 308 309**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 310 311**System capability**: SystemCapability.Communication.Bluetooth.Core 312 313**Parameters** 314 315| Name | Type | Mandatory | Description | 316| ------------------- | --------------------------------------- | ----- | ------------------------------- | 317| advertisingParams | [AdvertisingParams](#advertisingparams11) | Yes | Parameters for starting BLE advertising. | 318| callback | AsyncCallback<number> | Yes | Callback invoked to return the advertisement ID.| 319 320**Error codes** 321 322For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 323 324| ID| Error Message| 325| -------- | -------------------------------------- | 326|201 | Permission denied. | 327|401 | Invalid parameter. | 328|801 | Capability not supported. | 329|2900001 | Service stopped. | 330|2900003 | Bluetooth switch is off. | 331|2900099 | Operation failed. | 332 333**Example** 334 335```js 336import { BusinessError } from '@ohos.base'; 337let manufactureValueBuffer = new Uint8Array(4); 338manufactureValueBuffer[0] = 1; 339manufactureValueBuffer[1] = 2; 340manufactureValueBuffer[2] = 3; 341manufactureValueBuffer[3] = 4; 342 343let serviceValueBuffer = new Uint8Array(4); 344serviceValueBuffer[0] = 4; 345serviceValueBuffer[1] = 6; 346serviceValueBuffer[2] = 7; 347serviceValueBuffer[3] = 8; 348console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 349console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 350try { 351 let setting: ble.AdvertiseSetting = { 352 interval:150, 353 txPower:0, 354 connectable:true, 355 }; 356 let manufactureDataUnit: ble.ManufactureData = { 357 manufactureId:4567, 358 manufactureValue:manufactureValueBuffer.buffer 359 }; 360 let serviceDataUnit: ble.ServiceData = { 361 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 362 serviceValue:serviceValueBuffer.buffer 363 }; 364 let advData: ble.AdvertiseData = { 365 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 366 manufactureData:[manufactureDataUnit], 367 serviceData:[serviceDataUnit], 368 }; 369 let advResponse: ble.AdvertiseData = { 370 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 371 manufactureData:[manufactureDataUnit], 372 serviceData:[serviceDataUnit], 373 }; 374 let advertisingParams: ble.AdvertisingParams = { 375 advertisingSettings: setting, 376 advertisingData: advData, 377 advertisingResponse: advResponse, 378 duration: 0, 379 } 380 let advHandle = 0xFF; 381 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 382 if (err) { 383 return; 384 } else { 385 advHandle = outAdvHandle; 386 console.log("advHandle: " + advHandle); 387 } 388 }); 389} catch (err) { 390 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 391} 392``` 393 394 395## ble.startAdvertising<sup>11+</sup><a name="startAdvertising"></a> 396 397startAdvertising(advertisingParams: AdvertisingParams): Promise<number> 398 399Starts BLE advertising. 400 401**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 402 403**System capability**: SystemCapability.Communication.Bluetooth.Core 404 405**Parameters** 406 407| Name | Type | Mandatory | Description | 408| ------------------- | -------------------------------------- | ----- | ----------------------- | 409| advertisingParams | [AdvertisingParams](#advertisingparams11) | Yes | Parameters for starting BLE advertising. | 410 411**Return value** 412 413| Type | Description | 414| -------------------------- | ------------------------------- | 415| Promise<number> | Promise used to return the BLE advertisement ID.| 416 417**Error codes** 418 419For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 420 421| ID| Error Message| 422| -------- | -------------------------------------- | 423|201 | Permission denied. | 424|401 | Invalid parameter. | 425|801 | Capability not supported. | 426|2900001 | Service stopped. | 427|2900003 | Bluetooth switch is off. | 428|2900099 | Operation failed. | 429 430**Example** 431 432```js 433import { BusinessError } from '@ohos.base'; 434let manufactureValueBuffer = new Uint8Array(4); 435manufactureValueBuffer[0] = 1; 436manufactureValueBuffer[1] = 2; 437manufactureValueBuffer[2] = 3; 438manufactureValueBuffer[3] = 4; 439 440let serviceValueBuffer = new Uint8Array(4); 441serviceValueBuffer[0] = 4; 442serviceValueBuffer[1] = 6; 443serviceValueBuffer[2] = 7; 444serviceValueBuffer[3] = 8; 445console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 446console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 447try { 448 let setting: ble.AdvertiseSetting = { 449 interval:150, 450 txPower:0, 451 connectable:true, 452 }; 453 let manufactureDataUnit: ble.ManufactureData = { 454 manufactureId:4567, 455 manufactureValue:manufactureValueBuffer.buffer 456 }; 457 let serviceDataUnit: ble.ServiceData = { 458 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 459 serviceValue:serviceValueBuffer.buffer 460 }; 461 let advData: ble.AdvertiseData = { 462 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 463 manufactureData:[manufactureDataUnit], 464 serviceData:[serviceDataUnit], 465 }; 466 let advResponse: ble.AdvertiseData = { 467 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 468 manufactureData:[manufactureDataUnit], 469 serviceData:[serviceDataUnit], 470 }; 471 let advertisingParams: ble.AdvertisingParams = { 472 advertisingSettings: setting, 473 advertisingData: advData, 474 advertisingResponse: advResponse, 475 duration: 0, 476 } 477 let advHandle = 0xFF; 478 ble.startAdvertising(advertisingParams) 479 .then(outAdvHandle => { 480 advHandle = outAdvHandle; 481 }); 482} catch (err) { 483 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 484} 485``` 486 487 488## ble.enableAdvertising<sup>11+</sup><a name="enableAdvertising"></a> 489 490enableAdvertising(advertisingEnableParams: AdvertisingEnableParams, callback: AsyncCallback<void>): void 491 492Temporarily enables BLE advertising. 493 494**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 495 496**System capability**: SystemCapability.Communication.Bluetooth.Core 497 498**Parameters** 499 500| Name | Type | Mandatory | Description | 501| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 502| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | Yes | Parameters for temporarily enabling BLE advertising. | 503| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 504 505**Error codes** 506 507For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 508 509| ID| Error Message| 510| ------- | -------------------------------------- | 511|201 | Permission denied. | 512|401 | Invalid parameter. | 513|801 | Capability not supported. | 514|2900001 | Service stopped. | 515|2900003 | Bluetooth switch is off. | 516|2900099 | Operation failed. | 517 518**Example** 519 520```js 521import { BusinessError } from '@ohos.base'; 522let manufactureValueBuffer = new Uint8Array(4); 523manufactureValueBuffer[0] = 1; 524manufactureValueBuffer[1] = 2; 525manufactureValueBuffer[2] = 3; 526manufactureValueBuffer[3] = 4; 527 528let serviceValueBuffer = new Uint8Array(4); 529serviceValueBuffer[0] = 4; 530serviceValueBuffer[1] = 6; 531serviceValueBuffer[2] = 7; 532serviceValueBuffer[3] = 8; 533console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 534console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 535try { 536 let setting: ble.AdvertiseSetting = { 537 interval:150, 538 txPower:0, 539 connectable:true, 540 }; 541 let manufactureDataUnit: ble.ManufactureData = { 542 manufactureId:4567, 543 manufactureValue:manufactureValueBuffer.buffer 544 }; 545 let serviceDataUnit: ble.ServiceData = { 546 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 547 serviceValue:serviceValueBuffer.buffer 548 }; 549 let advData: ble.AdvertiseData = { 550 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 551 manufactureData:[manufactureDataUnit], 552 serviceData:[serviceDataUnit], 553 }; 554 let advResponse: ble.AdvertiseData = { 555 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 556 manufactureData:[manufactureDataUnit], 557 serviceData:[serviceDataUnit], 558 }; 559 let advertisingParams: ble.AdvertisingParams = { 560 advertisingSettings: setting, 561 advertisingData: advData, 562 advertisingResponse: advResponse, 563 duration: 300, 564 } 565 let advHandle = 0xFF; 566 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 567 if (err) { 568 return; 569 } else { 570 advHandle = outAdvHandle; 571 console.log("advHandle: " + advHandle); 572 } 573 }); 574 575 let advertisingEnableParams: ble.AdvertisingEnableParams = { 576 advertisingId: advHandle, 577 duration: 0 578 } 579 580 // after 3s, advertising disabled, then enable the advertising 581 ble.enableAdvertising(advertisingEnableParams, (err) => { 582 if (err) { 583 return; 584 } 585 }); 586} catch (err) { 587 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 588} 589``` 590 591 592## ble.enableAdvertising<sup>11+</sup><a name="enableAdvertising"></a> 593 594enableAdvertising(advertisingEnableParams: AdvertisingEnableParams): Promise<void> 595 596Temporarily enables BLE advertising. 597 598**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 599 600**System capability**: SystemCapability.Communication.Bluetooth.Core 601 602**Parameters** 603 604| Name | Type | Mandatory | Description | 605| ------------------------- | --------------------------------------------------- | ----- | ------------------------------- | 606| advertisingEnableParams | [AdvertisingEnableParams](#advertisingenableparams11) | Yes | Parameters for temporarily enabling BLE advertising. | 607 608**Return value** 609 610| Type | Description | 611| -------------------------- | ------------ | 612| Promise<void> | Promise used to return the result. | 613 614**Error codes** 615 616For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 617 618| ID| Error Message| 619| ------- | -------------------------------------- | 620|201 | Permission denied. | 621|401 | Invalid parameter. | 622|801 | Capability not supported. | 623|2900001 | Service stopped. | 624|2900003 | Bluetooth switch is off. | 625|2900099 | Operation failed. | 626 627**Example** 628 629```js 630import { BusinessError } from '@ohos.base'; 631let manufactureValueBuffer = new Uint8Array(4); 632manufactureValueBuffer[0] = 1; 633manufactureValueBuffer[1] = 2; 634manufactureValueBuffer[2] = 3; 635manufactureValueBuffer[3] = 4; 636 637let serviceValueBuffer = new Uint8Array(4); 638serviceValueBuffer[0] = 4; 639serviceValueBuffer[1] = 6; 640serviceValueBuffer[2] = 7; 641serviceValueBuffer[3] = 8; 642console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 643console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 644try { 645 let setting: ble.AdvertiseSetting = { 646 interval:150, 647 txPower:0, 648 connectable:true, 649 }; 650 let manufactureDataUnit: ble.ManufactureData = { 651 manufactureId:4567, 652 manufactureValue:manufactureValueBuffer.buffer 653 }; 654 let serviceDataUnit: ble.ServiceData = { 655 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 656 serviceValue:serviceValueBuffer.buffer 657 }; 658 let advData: ble.AdvertiseData = { 659 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 660 manufactureData:[manufactureDataUnit], 661 serviceData:[serviceDataUnit], 662 }; 663 let advResponse: ble.AdvertiseData = { 664 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 665 manufactureData:[manufactureDataUnit], 666 serviceData:[serviceDataUnit], 667 }; 668 let advertisingParams: ble.AdvertisingParams = { 669 advertisingSettings: setting, 670 advertisingData: advData, 671 advertisingResponse: advResponse, 672 duration: 300, 673 } 674 let advHandle = 0xFF; 675 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 676 if (err) { 677 return; 678 } else { 679 advHandle = outAdvHandle; 680 console.log("advHandle: " + advHandle); 681 } 682 }); 683 684 let advertisingEnableParams: ble.AdvertisingEnableParams = { 685 advertisingId: advHandle, 686 duration: 0 687 } 688 689 // after 3s, advertising disabled, then enable the advertising 690 ble.enableAdvertising(advertisingEnableParams) 691 .then(() => { 692 console.info("enable success"); 693 }); 694} catch (err) { 695 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 696} 697``` 698 699 700## ble.disableAdvertising<sup>11+</sup><a name="disableAdvertising"></a> 701 702disableAdvertising(advertisingDisableParams: AdvertisingDisableParams, callback: AsyncCallback<void>): void 703 704Disables BLE advertising temporarily. 705 706**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 707 708**System capability**: SystemCapability.Communication.Bluetooth.Core 709 710**Parameters** 711 712| Name | Type | Mandatory | Description | 713| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 714| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | Yes | Parameters for temporarily disabling BLE advertising. | 715| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 716 717**Error codes** 718 719For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 720 721| ID| Error Message| 722| ------- | -------------------------------------- | 723|201 | Permission denied. | 724|401 | Invalid parameter. | 725|801 | Capability not supported. | 726|2900001 | Service stopped. | 727|2900003 | Bluetooth switch is off. | 728|2900099 | Operation failed. | 729 730**Example** 731 732```js 733import { BusinessError } from '@ohos.base'; 734let manufactureValueBuffer = new Uint8Array(4); 735manufactureValueBuffer[0] = 1; 736manufactureValueBuffer[1] = 2; 737manufactureValueBuffer[2] = 3; 738manufactureValueBuffer[3] = 4; 739 740let serviceValueBuffer = new Uint8Array(4); 741serviceValueBuffer[0] = 4; 742serviceValueBuffer[1] = 6; 743serviceValueBuffer[2] = 7; 744serviceValueBuffer[3] = 8; 745console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 746console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 747try { 748 let setting: ble.AdvertiseSetting = { 749 interval:150, 750 txPower:0, 751 connectable:true, 752 }; 753 let manufactureDataUnit: ble.ManufactureData = { 754 manufactureId:4567, 755 manufactureValue:manufactureValueBuffer.buffer 756 }; 757 let serviceDataUnit: ble.ServiceData = { 758 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 759 serviceValue:serviceValueBuffer.buffer 760 }; 761 let advData: ble.AdvertiseData = { 762 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 763 manufactureData:[manufactureDataUnit], 764 serviceData:[serviceDataUnit], 765 }; 766 let advResponse: ble.AdvertiseData = { 767 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 768 manufactureData:[manufactureDataUnit], 769 serviceData:[serviceDataUnit], 770 }; 771 let advertisingParams: ble.AdvertisingParams = { 772 advertisingSettings: setting, 773 advertisingData: advData, 774 advertisingResponse: advResponse, 775 duration: 0, 776 } 777 let advHandle = 0xFF; 778 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 779 if (err) { 780 return; 781 } else { 782 advHandle = outAdvHandle; 783 console.log("advHandle: " + advHandle); 784 } 785 }); 786 787 let advertisingDisableParams: ble.AdvertisingDisableParams = { 788 advertisingId: advHandle 789 } 790 ble.disableAdvertising(advertisingDisableParams, (err) => { 791 if (err) { 792 return; 793 } 794 }); 795} catch (err) { 796 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 797} 798``` 799 800 801## ble.disableAdvertising<sup>11+</sup><a name="disableAdvertising"></a> 802 803disableAdvertising(advertisingDisableParams: AdvertisingDisableParams): Promise<void> 804 805Disables BLE advertising temporarily. 806 807**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 808 809**System capability**: SystemCapability.Communication.Bluetooth.Core 810 811**Parameters** 812 813| Name | Type | Mandatory | Description | 814| ------------------------- | ----------------------------------------------------- | ----- | ------------------------------- | 815| advertisingDisableParams | [AdvertisingDisableParams](#advertisingdisableparams11) | Yes | Parameters for temporarily disabling BLE advertising. | 816 817**Return value** 818 819| Type | Description | 820| -------------------------- | ------------ | 821| Promise<void> | Promise used to return the result. | 822 823**Error codes** 824 825For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 826 827| ID| Error Message| 828| ------- | -------------------------------------- | 829|201 | Permission denied. | 830|401 | Invalid parameter. | 831|801 | Capability not supported. | 832|2900001 | Service stopped. | 833|2900003 | Bluetooth switch is off. | 834|2900099 | Operation failed. | 835 836**Example** 837 838```js 839import { BusinessError } from '@ohos.base'; 840let manufactureValueBuffer = new Uint8Array(4); 841manufactureValueBuffer[0] = 1; 842manufactureValueBuffer[1] = 2; 843manufactureValueBuffer[2] = 3; 844manufactureValueBuffer[3] = 4; 845 846let serviceValueBuffer = new Uint8Array(4); 847serviceValueBuffer[0] = 4; 848serviceValueBuffer[1] = 6; 849serviceValueBuffer[2] = 7; 850serviceValueBuffer[3] = 8; 851console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 852console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 853try { 854 let setting: ble.AdvertiseSetting = { 855 interval:150, 856 txPower:0, 857 connectable:true, 858 }; 859 let manufactureDataUnit: ble.ManufactureData = { 860 manufactureId:4567, 861 manufactureValue:manufactureValueBuffer.buffer 862 }; 863 let serviceDataUnit: ble.ServiceData = { 864 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 865 serviceValue:serviceValueBuffer.buffer 866 }; 867 let advData: ble.AdvertiseData = { 868 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 869 manufactureData:[manufactureDataUnit], 870 serviceData:[serviceDataUnit], 871 }; 872 let advResponse: ble.AdvertiseData = { 873 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 874 manufactureData:[manufactureDataUnit], 875 serviceData:[serviceDataUnit], 876 }; 877 let advertisingParams: ble.AdvertisingParams = { 878 advertisingSettings: setting, 879 advertisingData: advData, 880 advertisingResponse: advResponse, 881 duration: 0, 882 } 883 let advHandle = 0xFF; 884 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 885 if (err) { 886 return; 887 } else { 888 advHandle = outAdvHandle; 889 console.log("advHandle: " + advHandle); 890 } 891 }); 892 893 let advertisingDisableParams: ble.AdvertisingDisableParams = { 894 advertisingId: advHandle 895 } 896 ble.disableAdvertising(advertisingDisableParams) 897 .then(() => { 898 console.info("enable success"); 899 }); 900} catch (err) { 901 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 902} 903``` 904 905## ble.stopAdvertising<sup>11+</sup><a name="stopAdvertising"></a> 906 907stopAdvertising(advertisingId: number, callback: AsyncCallback<void>): void 908 909Stops BLE advertising. 910 911**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 912 913**System capability**: SystemCapability.Communication.Bluetooth.Core 914 915**Parameters** 916 917| Name | Type | Mandatory | Description | 918| ------------------------- | ---------------------------- | ----- | --------------------------- | 919| advertisingId | number | Yes | ID of the advertisement to stop. | 920| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 921 922**Error codes** 923 924For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 925 926| ID| Error Message| 927| -------- | ---------------------------- | 928|201 | Permission denied. | 929|401 | Invalid parameter. | 930|801 | Capability not supported. | 931|2900001 | Service stopped. | 932|2900003 | Bluetooth switch is off. | 933|2900099 | Operation failed. | 934 935**Example** 936 937```js 938import { BusinessError } from '@ohos.base'; 939let manufactureValueBuffer = new Uint8Array(4); 940manufactureValueBuffer[0] = 1; 941manufactureValueBuffer[1] = 2; 942manufactureValueBuffer[2] = 3; 943manufactureValueBuffer[3] = 4; 944 945let serviceValueBuffer = new Uint8Array(4); 946serviceValueBuffer[0] = 4; 947serviceValueBuffer[1] = 6; 948serviceValueBuffer[2] = 7; 949serviceValueBuffer[3] = 8; 950console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 951console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 952try { 953 let setting: ble.AdvertiseSetting = { 954 interval:150, 955 txPower:0, 956 connectable:true, 957 }; 958 let manufactureDataUnit: ble.ManufactureData = { 959 manufactureId:4567, 960 manufactureValue:manufactureValueBuffer.buffer 961 }; 962 let serviceDataUnit: ble.ServiceData = { 963 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 964 serviceValue:serviceValueBuffer.buffer 965 }; 966 let advData: ble.AdvertiseData = { 967 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 968 manufactureData:[manufactureDataUnit], 969 serviceData:[serviceDataUnit], 970 }; 971 let advResponse: ble.AdvertiseData = { 972 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 973 manufactureData:[manufactureDataUnit], 974 serviceData:[serviceDataUnit], 975 }; 976 let advertisingParams: ble.AdvertisingParams = { 977 advertisingSettings: setting, 978 advertisingData: advData, 979 advertisingResponse: advResponse, 980 duration: 0, 981 } 982 let advHandle = 0xFF; 983 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 984 if (err) { 985 return; 986 } else { 987 advHandle = outAdvHandle; 988 console.log("advHandle: " + advHandle); 989 } 990 }); 991 992 ble.stopAdvertising(advHandle, (err) => { 993 if (err) { 994 return; 995 } 996 }); 997} catch (err) { 998 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 999} 1000``` 1001 1002 1003## ble.stopAdvertising<sup>11+</sup><a name="stopAdvertising"></a> 1004 1005stopAdvertising(advertisingId: number): Promise<void> 1006 1007Stops BLE advertising. 1008 1009**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1010 1011**System capability**: SystemCapability.Communication.Bluetooth.Core 1012 1013**Parameters** 1014 1015| Name | Type | Mandatory | Description | 1016| ------------------------- | ---------------------------- | ----- | --------------------------- | 1017| advertisingId | number | Yes | ID of the advertisement to stop. | 1018 1019**Return value** 1020 1021| Type | Description | 1022| -------------------------- | ------------ | 1023| Promise<void> | Promise used to return the result. | 1024 1025**Error codes** 1026 1027For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1028 1029| ID| Error Message| 1030| -------- | ---------------------------- | 1031|201 | Permission denied. | 1032|401 | Invalid parameter. | 1033|801 | Capability not supported. | 1034|2900001 | Service stopped. | 1035|2900003 | Bluetooth switch is off. | 1036|2900099 | Operation failed. | 1037 1038**Example** 1039 1040```js 1041import { BusinessError } from '@ohos.base'; 1042let manufactureValueBuffer = new Uint8Array(4); 1043manufactureValueBuffer[0] = 1; 1044manufactureValueBuffer[1] = 2; 1045manufactureValueBuffer[2] = 3; 1046manufactureValueBuffer[3] = 4; 1047 1048let serviceValueBuffer = new Uint8Array(4); 1049serviceValueBuffer[0] = 4; 1050serviceValueBuffer[1] = 6; 1051serviceValueBuffer[2] = 7; 1052serviceValueBuffer[3] = 8; 1053console.info('manufactureValueBuffer = '+ JSON.stringify(manufactureValueBuffer)); 1054console.info('serviceValueBuffer = '+ JSON.stringify(serviceValueBuffer)); 1055try { 1056 let setting: ble.AdvertiseSetting = { 1057 interval:150, 1058 txPower:0, 1059 connectable:true, 1060 }; 1061 let manufactureDataUnit: ble.ManufactureData = { 1062 manufactureId:4567, 1063 manufactureValue:manufactureValueBuffer.buffer 1064 }; 1065 let serviceDataUnit: ble.ServiceData = { 1066 serviceUuid:"00001888-0000-1000-8000-00805f9b34fb", 1067 serviceValue:serviceValueBuffer.buffer 1068 }; 1069 let advData: ble.AdvertiseData = { 1070 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1071 manufactureData:[manufactureDataUnit], 1072 serviceData:[serviceDataUnit], 1073 }; 1074 let advResponse: ble.AdvertiseData = { 1075 serviceUuids:["00001888-0000-1000-8000-00805f9b34fb"], 1076 manufactureData:[manufactureDataUnit], 1077 serviceData:[serviceDataUnit], 1078 }; 1079 let advertisingParams: ble.AdvertisingParams = { 1080 advertisingSettings: setting, 1081 advertisingData: advData, 1082 advertisingResponse: advResponse, 1083 duration: 0, 1084 } 1085 let advHandle = 0xFF; 1086 ble.startAdvertising(advertisingParams, (err, outAdvHandle) => { 1087 if (err) { 1088 return; 1089 } else { 1090 advHandle = outAdvHandle; 1091 console.log("advHandle: " + advHandle); 1092 } 1093 }); 1094 1095 ble.stopAdvertising(advHandle) 1096 .then(() => { 1097 console.info("enable success"); 1098 }); 1099} catch (err) { 1100 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1101} 1102``` 1103 1104 1105## ble.on('advertisingStateChange')<sup>11+</sup> 1106 1107on(type: 'advertisingStateChange', callback: Callback<AdvertisingStateChangeInfo>): void 1108 1109Subscribes to BLE advertising status. 1110 1111**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1112 1113**System capability**: SystemCapability.Communication.Bluetooth.Core 1114 1115**Parameters** 1116 1117| Name | Type | Mandatory | Description | 1118| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1119| type | string | Yes | Event type. The value is **advertisingStateChange**, which indicates the advertising status change. | 1120| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | Yes | Callback invoked to return the advertising status. You need to implement this callback.| 1121 1122**Error codes** 1123 1124For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1125 1126| ID| Error Message| 1127| -------- | ---------------------------- | 1128|201 | Permission denied. | 1129|401 | Invalid parameter. | 1130|801 | Capability not supported. | 1131|2900099 | Operation failed. | 1132 1133**Example** 1134 1135```js 1136import { BusinessError } from '@ohos.base'; 1137function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1138 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1139} 1140try { 1141 ble.on('advertisingStateChange', onReceiveEvent); 1142} catch (err) { 1143 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1144} 1145``` 1146 1147 1148## ble.off('advertisingStateChange')<sup>11+</sup> 1149 1150off(type: 'advertisingStateChange', callback?: Callback<AdvertisingStateChangeInfo>): void 1151 1152Unsubscribes from BLE advertising status. 1153 1154**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1155 1156**System capability**: SystemCapability.Communication.Bluetooth.Core 1157 1158**Parameters** 1159 1160| Name | Type | Mandatory | Description | 1161| -------- | ------------------------------------------------------------------------- | ----- | ---------------------------------------------------------- | 1162| type | string | Yes | Event type. The value is **advertisingStateChange**, which indicates the advertising status change. | 1163| callback | Callback<[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)> | No | Callback for the advertising status change. If this parameter is not set, this API unsubscribes from all callbacks corresponding to **type**.| 1164 1165**Error codes** 1166 1167For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1168 1169| ID| Error Message| 1170| -------- | ---------------------------- | 1171|201 | Permission denied. | 1172|401 | Invalid parameter. | 1173|801 | Capability not supported. | 1174|2900099 | Operation failed. | 1175 1176**Example** 1177 1178```js 1179import { BusinessError } from '@ohos.base'; 1180function onReceiveEvent(data: ble.AdvertisingStateChangeInfo) { 1181 console.info('bluetooth advertising state = ' + JSON.stringify(data)); 1182} 1183try { 1184 ble.on('advertisingStateChange', onReceiveEvent); 1185 ble.off('advertisingStateChange', onReceiveEvent); 1186} catch (err) { 1187 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1188} 1189``` 1190 1191 1192## ble.on('BLEDeviceFind') 1193 1194on(type: 'BLEDeviceFind', callback: Callback<Array<ScanResult>>): void 1195 1196Subscribes to BLE device discovery events. 1197 1198**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1199 1200**System capability**: SystemCapability.Communication.Bluetooth.Core 1201 1202**Parameters** 1203 1204| Name | Type | Mandatory | Description | 1205| -------- | ---------------------------------------- | ---- | ----------------------------------- | 1206| type | string | Yes | Event type. The value is **BLEDeviceFind**, which indicates an event of discovering a BLE device. | 1207| callback | Callback<Array<[ScanResult](#scanresult)>> | Yes | Callback invoked to return the discovered devices. You need to implement this callback.| 1208 1209**Error codes** 1210 1211For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1212 1213| ID| Error Message| 1214| -------- | ---------------------------- | 1215|2900099 | Operation failed. | 1216 1217**Example** 1218 1219```js 1220import { BusinessError } from '@ohos.base'; 1221function onReceiveEvent(data: Array<ble.ScanResult>) { 1222 console.info('bluetooth device find = '+ JSON.stringify(data)); 1223} 1224try { 1225 ble.on('BLEDeviceFind', onReceiveEvent); 1226} catch (err) { 1227 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1228} 1229``` 1230 1231 1232## ble.off('BLEDeviceFind') 1233 1234off(type: 'BLEDeviceFind', callback?: Callback<Array<ScanResult>>): void 1235 1236Unsubscribes from the BLE device discovery events. 1237 1238**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1239 1240**System capability**: SystemCapability.Communication.Bluetooth.Core 1241 1242**Parameters** 1243 1244| Name | Type | Mandatory | Description | 1245| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1246| type | string | Yes | Event type. The value is **BLEDeviceFind**, which indicates an event of discovering a BLE device. | 1247| 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**.| 1248 1249**Error codes** 1250 1251For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1252 1253 1254| ID| Error Message| 1255| -------- | ---------------------------- | 1256|2900099 | Operation failed. | 1257 1258**Example** 1259 1260```js 1261import { BusinessError } from '@ohos.base'; 1262function onReceiveEvent(data: Array<ble.ScanResult>) { 1263 console.info('bluetooth device find = '+ JSON.stringify(data)); 1264} 1265try { 1266 ble.on('BLEDeviceFind', onReceiveEvent); 1267 ble.off('BLEDeviceFind', onReceiveEvent); 1268} catch (err) { 1269 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1270} 1271``` 1272 1273 1274## GattServer 1275 1276Implements the Generic Attribute Profile (GATT) server. Before using an API of this class, you need to create a **GattServer** instance using **createGattServer()**. 1277 1278 1279### addService 1280 1281addService(service: GattService): void 1282 1283Adds a service to this GATT server. 1284 1285**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1286 1287**System capability**: SystemCapability.Communication.Bluetooth.Core 1288 1289**Parameters** 1290 1291| Name | Type | Mandatory | Description | 1292| ------- | --------------------------- | ---- | ------------------------ | 1293| service | [GattService](#gattservice) | Yes | Service to add. Settings related to BLE advertising.| 1294 1295**Error codes** 1296 1297For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1298 1299| ID| Error Message| 1300| -------- | ---------------------------- | 1301|2900001 | Service stopped. | 1302|2900003 | Bluetooth switch is off. | 1303|2900099 | Operation failed. | 1304 1305**Example** 1306 1307```js 1308import { BusinessError } from '@ohos.base'; 1309// Create descriptors. 1310let descriptors: Array<ble.BLEDescriptor> = []; 1311let arrayBuffer = new ArrayBuffer(8); 1312let descV = new Uint8Array(arrayBuffer); 1313descV[0] = 11; 1314let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1315 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1316 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 1317descriptors[0] = descriptor; 1318 1319// Create characteristics. 1320let characteristics: Array<ble.BLECharacteristic> = []; 1321let arrayBufferC = new ArrayBuffer(8); 1322let cccV = new Uint8Array(arrayBufferC); 1323cccV[0] = 1; 1324let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1325 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 1326let characteristicN: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1327 characteristicUuid: '00001821-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 1328characteristics[0] = characteristic; 1329 1330// Create a gattService instance. 1331let gattService: ble.GattService = {serviceUuid:'00001810-0000-1000-8000-00805F9B34FB', isPrimary: true, characteristics:characteristics, includeServices:[]}; 1332 1333try { 1334 let gattServer: ble.GattServer = ble.createGattServer(); 1335 gattServer.addService(gattService); 1336} catch (err) { 1337 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1338} 1339``` 1340 1341 1342### removeService 1343 1344removeService(serviceUuid: string): void 1345 1346Removes a service from this GATT server. 1347 1348**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1349 1350**System capability**: SystemCapability.Communication.Bluetooth.Core 1351 1352**Parameters** 1353 1354| Name | Type | Mandatory | Description | 1355| ----------- | ------ | ---- | ---------------------------------------- | 1356| serviceUuid | string | Yes | Universally unique identifier (UUID) of the service to remove, for example, **00001810-0000-1000-8000-00805F9B34FB**.| 1357 1358**Error codes** 1359 1360For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1361 1362| ID| Error Message| 1363| -------- | ---------------------------- | 1364|2900001 | Service stopped. | 1365|2900003 | Bluetooth switch is off. | 1366|2900004 | Profile is not supported. | 1367|2900099 | Operation failed. | 1368 1369**Example** 1370 1371```js 1372import { BusinessError } from '@ohos.base'; 1373let server: ble.GattServer = ble.createGattServer(); 1374try { 1375 server.removeService('00001810-0000-1000-8000-00805F9B34FB'); 1376} catch (err) { 1377 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1378} 1379``` 1380 1381 1382### close 1383 1384close(): void 1385 1386Closes this GATT server to unregister it from the protocol stack. The closed [GattServer](#gattserver) instance will no longer be used. 1387 1388**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1389 1390**System capability**: SystemCapability.Communication.Bluetooth.Core 1391 1392**Error codes** 1393 1394For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1395 1396| ID| Error Message| 1397| -------- | ---------------------------- | 1398|2900001 | Service stopped. | 1399|2900003 | Bluetooth switch is off. | 1400|2900099 | Operation failed. | 1401 1402**Example** 1403 1404```js 1405import { BusinessError } from '@ohos.base'; 1406let server: ble.GattServer = ble.createGattServer(); 1407try { 1408 server.close(); 1409} catch (err) { 1410 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1411} 1412``` 1413 1414 1415### notifyCharacteristicChanged 1416 1417notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic, callback: AsyncCallback<void>): void 1418 1419Notifies a connected client device when a characteristic value changes. This API uses an asynchronous callback to return the result. 1420 1421**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1422 1423**System capability**: SystemCapability.Communication.Bluetooth.Core 1424 1425**Parameters** 1426 1427| Name | Type | Mandatory | Description | 1428| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1429| deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX.| 1430| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes | New characteristic value. | 1431| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1432 1433**Error codes** 1434 1435For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1436 1437| ID| Error Message| 1438| -------- | ---------------------------- | 1439|2900001 | Service stopped. | 1440|2900003 | Bluetooth switch is off. | 1441|2900099 | Operation failed. | 1442 1443**Example** 1444 1445```js 1446import { BusinessError } from '@ohos.base'; 1447let arrayBufferC = new ArrayBuffer(8); 1448let notifyCharacter: ble.NotifyCharacteristic = { 1449 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1450 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1451 characteristicValue: arrayBufferC, 1452 confirm: true, 1453}; 1454try { 1455 let gattServer: ble.GattServer = ble.createGattServer(); 1456 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter, (err: BusinessError) => { 1457 if (err) { 1458 console.info('notifyCharacteristicChanged callback failed'); 1459 } else { 1460 console.info('notifyCharacteristicChanged callback successful'); 1461 } 1462 }); 1463} catch (err) { 1464 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1465} 1466``` 1467 1468 1469### notifyCharacteristicChanged 1470 1471notifyCharacteristicChanged(deviceId: string, notifyCharacteristic: NotifyCharacteristic): Promise<void> 1472 1473Notifies a connected client device when a characteristic value changes. This API uses a promise to return the result. 1474 1475**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1476 1477**System capability**: SystemCapability.Communication.Bluetooth.Core 1478 1479**Parameters** 1480 1481| Name | Type | Mandatory | Description | 1482| -------------------- | ---------------------------------------- | ---- | --------------------------------------- | 1483| deviceId | string | Yes | Address of the client that receives the notifications, for example, XX:XX:XX:XX:XX:XX.| 1484| notifyCharacteristic | [NotifyCharacteristic](#notifycharacteristic) | Yes | New characteristic value. | 1485 1486**Return value** 1487 1488| Type | Description | 1489| ------------------- | ------------- | 1490| Promise<void> | Promise used to return the result.| 1491 1492**Error codes** 1493 1494For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1495 1496| ID| Error Message| 1497| -------- | ---------------------------- | 1498|2900001 | Service stopped. | 1499|2900003 | Bluetooth switch is off. | 1500|2900099 | Operation failed. | 1501 1502**Example** 1503 1504```js 1505import { BusinessError } from '@ohos.base'; 1506let arrayBufferC = new ArrayBuffer(8); 1507let notifyCharacter: ble.NotifyCharacteristic = { 1508 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 1509 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 1510 characteristicValue: arrayBufferC, 1511 confirm: true, 1512}; 1513try { 1514 let gattServer: ble.GattServer = ble.createGattServer(); 1515 gattServer.notifyCharacteristicChanged('XX:XX:XX:XX:XX:XX', notifyCharacter).then(() => { 1516 console.info('notifyCharacteristicChanged promise successfull'); 1517 }); 1518} catch (err) { 1519 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1520} 1521``` 1522 1523 1524### sendResponse 1525 1526sendResponse(serverResponse: ServerResponse): void 1527 1528Sends a response to a read or write request from the GATT client. 1529 1530**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1531 1532**System capability**: SystemCapability.Communication.Bluetooth.Core 1533 1534**Parameters** 1535 1536| Name | Type | Mandatory | Description | 1537| -------------- | --------------------------------- | ---- | --------------- | 1538| serverResponse | [ServerResponse](#serverresponse) | Yes | Response returned by the GATT server.| 1539 1540**Error codes** 1541 1542For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 1543 1544| ID| Error Message| 1545| -------- | ---------------------------- | 1546|2900001 | Service stopped. | 1547|2900003 | Bluetooth switch is off. | 1548|2900099 | Operation failed. | 1549 1550**Example** 1551 1552```js 1553import { BusinessError } from '@ohos.base'; 1554/* send response */ 1555let arrayBufferCCC = new ArrayBuffer(8); 1556let cccValue = new Uint8Array(arrayBufferCCC); 1557cccValue[0] = 1123; 1558let serverResponse: ble.ServerResponse = { 1559 deviceId: 'XX:XX:XX:XX:XX:XX', 1560 transId: 0, 1561 status: 0, 1562 offset: 0, 1563 value: arrayBufferCCC, 1564}; 1565try { 1566 let gattServer: ble.GattServer = ble.createGattServer(); 1567 gattServer.sendResponse(serverResponse); 1568} catch (err) { 1569 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1570} 1571``` 1572 1573 1574### on('characteristicRead') 1575 1576on(type: 'characteristicRead', callback: Callback<CharacteristicReadRequest>): void 1577 1578Subscribes to characteristic read request events. 1579 1580**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1581 1582**System capability**: SystemCapability.Communication.Bluetooth.Core 1583 1584**Parameters** 1585 1586| Name | Type | Mandatory | Description | 1587| -------- | ---------------------------------------- | ---- | ------------------------------------- | 1588| type | string | Yes | Event type. The value is **characteristicRead**, which indicates a characteristic read request event.| 1589| callback | Callback<[CharacteristicReadRequest](#characteristicreadrequest)> | Yes | Callback invoked to return a characteristic read request event from the GATT client. | 1590 1591**Example** 1592 1593```js 1594import { BusinessError } from '@ohos.base'; 1595let arrayBufferCCC = new ArrayBuffer(8); 1596let cccValue = new Uint8Array(arrayBufferCCC); 1597cccValue[0] = 1123; 1598let gattServer: ble.GattServer = ble.createGattServer(); 1599function ReadCharacteristicReq(characteristicReadRequest: ble.CharacteristicReadRequest) { 1600 let deviceId: string = characteristicReadRequest.deviceId; 1601 let transId: number = characteristicReadRequest.transId; 1602 let offset: number = characteristicReadRequest.offset; 1603 let characteristicUuid: string = characteristicReadRequest.characteristicUuid; 1604 1605 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1606 1607 try { 1608 gattServer.sendResponse(serverResponse); 1609 } catch (err) { 1610 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1611 } 1612} 1613gattServer.on('characteristicRead', ReadCharacteristicReq); 1614``` 1615 1616 1617### off('characteristicRead') 1618 1619off(type: 'characteristicRead', callback?: Callback<CharacteristicReadRequest>): void 1620 1621Unsubscribes from characteristic read request events. 1622 1623**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1624 1625**System capability**: SystemCapability.Communication.Bluetooth.Core 1626 1627**Parameters** 1628 1629| Name | Type | Mandatory | Description | 1630| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1631| type | string | Yes | Event type. The value is **characteristicRead**, which indicates a characteristic read request event. | 1632| 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**.| 1633 1634**Example** 1635 1636```js 1637import { BusinessError } from '@ohos.base'; 1638try { 1639let gattServer: ble.GattServer = ble.createGattServer(); 1640gattServer.off('characteristicRead'); 1641} catch (err) { 1642 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1643} 1644``` 1645 1646 1647### on('characteristicWrite') 1648 1649on(type: 'characteristicWrite', callback: Callback<CharacteristicWriteRequest>): void 1650 1651Subscribes to characteristic write request events. 1652 1653**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1654 1655**System capability**: SystemCapability.Communication.Bluetooth.Core 1656 1657**Parameters** 1658 1659| Name | Type | Mandatory | Description | 1660| -------- | ---------------------------------------- | ---- | -------------------------------------- | 1661| type | string | Yes | Event type. The value is **characteristicWrite**, which indicates a characteristic write request event.| 1662| callback | Callback<[CharacteristicWriteRequest](#characteristicwriterequest)> | Yes | Callback invoked to return a characteristic write request from the GATT client. | 1663 1664**Example** 1665 1666```js 1667import { BusinessError } from '@ohos.base'; 1668let arrayBufferCCC = new ArrayBuffer(8); 1669let cccValue = new Uint8Array(arrayBufferCCC); 1670let gattServer: ble.GattServer = ble.createGattServer(); 1671function WriteCharacteristicReq(characteristicWriteRequest: ble.CharacteristicWriteRequest) { 1672 let deviceId: string = characteristicWriteRequest.deviceId; 1673 let transId: number = characteristicWriteRequest.transId; 1674 let offset: number = characteristicWriteRequest.offset; 1675 let isPrepared: boolean = characteristicWriteRequest.isPrepared; 1676 let needRsp: boolean = characteristicWriteRequest.needRsp; 1677 let value: Uint8Array = new Uint8Array(characteristicWriteRequest.value); 1678 let characteristicUuid: string = characteristicWriteRequest.characteristicUuid; 1679 1680 cccValue[0] = value[0]; 1681 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferCCC}; 1682 1683 try { 1684 gattServer.sendResponse(serverResponse); 1685 } catch (err) { 1686 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1687 } 1688} 1689gattServer.on('characteristicWrite', WriteCharacteristicReq); 1690``` 1691 1692 1693### off('characteristicWrite') 1694 1695off(type: 'characteristicWrite', callback?: Callback<CharacteristicWriteRequest>): void 1696 1697Unsubscribes from characteristic write request events. 1698 1699**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1700 1701**System capability**: SystemCapability.Communication.Bluetooth.Core 1702 1703**Parameters** 1704 1705| Name | Type | Mandatory | Description | 1706| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1707| type | string | Yes | Event type. The value is **characteristicWrite**, which indicates a characteristic write request event. | 1708| 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**.| 1709 1710**Example** 1711 1712```js 1713import { BusinessError } from '@ohos.base'; 1714try { 1715let gattServer: ble.GattServer = ble.createGattServer(); 1716gattServer.off('characteristicWrite'); 1717} catch (err) { 1718 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1719} 1720``` 1721 1722 1723### on('descriptorRead') 1724 1725on(type: 'descriptorRead', callback: Callback<DescriptorReadRequest>): void 1726 1727Subscribes to descriptor read request events. 1728 1729**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1730 1731**System capability**: SystemCapability.Communication.Bluetooth.Core 1732 1733**Parameters** 1734 1735| Name | Type | Mandatory | Description | 1736| -------- | ---------------------------------------- | ---- | --------------------------------- | 1737| type | string | Yes | Event type. The value is **descriptorRead**, which indicates a descriptor read request event.| 1738| callback | Callback<[DescriptorReadRequest](#descriptorreadrequest)> | Yes | Callback invoked to return a descriptor read request event from the GATT client. | 1739 1740**Example** 1741 1742```js 1743import { BusinessError } from '@ohos.base'; 1744let arrayBufferDesc = new ArrayBuffer(8); 1745let descValue = new Uint8Array(arrayBufferDesc); 1746descValue[0] = 1101; 1747let gattServer: ble.GattServer = ble.createGattServer(); 1748function ReadDescriptorReq(descriptorReadRequest: ble.DescriptorReadRequest) { 1749 let deviceId: string = descriptorReadRequest.deviceId; 1750 let transId: number = descriptorReadRequest.transId; 1751 let offset: number = descriptorReadRequest.offset; 1752 let descriptorUuid: string = descriptorReadRequest.descriptorUuid; 1753 1754 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 1755 1756 try { 1757 gattServer.sendResponse(serverResponse); 1758 } catch (err) { 1759 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1760 } 1761} 1762gattServer.on('descriptorRead', ReadDescriptorReq); 1763``` 1764 1765 1766### off('descriptorRead') 1767 1768off(type: 'descriptorRead', callback?: Callback<DescriptorReadRequest>): void 1769 1770Unsubscribes from descriptor read request events. 1771 1772**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1773 1774**System capability**: SystemCapability.Communication.Bluetooth.Core 1775 1776**Parameters** 1777 1778| Name | Type | Mandatory | Description | 1779| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1780| type | string | Yes | Event type. The value is **descriptorRead**, which indicates a descriptor read request event. | 1781| 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**.| 1782 1783**Example** 1784 1785```js 1786import { BusinessError } from '@ohos.base'; 1787try { 1788let gattServer: ble.GattServer = ble.createGattServer(); 1789gattServer.off('descriptorRead'); 1790} catch (err) { 1791 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1792} 1793``` 1794 1795 1796### on('descriptorWrite') 1797 1798on(type: 'descriptorWrite', callback: Callback<DescriptorWriteRequest>): void 1799 1800Subscribes to descriptor write request events. 1801 1802**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1803 1804**System capability**: SystemCapability.Communication.Bluetooth.Core 1805 1806**Parameters** 1807 1808| Name | Type | Mandatory | Description | 1809| -------- | ---------------------------------------- | ---- | ---------------------------------- | 1810| type | string | Yes | Event type. The value is **descriptorWrite**, which indicates a descriptor write request event.| 1811| callback | Callback<[DescriptorWriteRequest](#descriptorwriterequest)> | Yes | Callback invoked to return a descriptor write request from the GATT client. | 1812 1813**Example** 1814 1815```js 1816import { BusinessError } from '@ohos.base'; 1817let arrayBufferDesc = new ArrayBuffer(8); 1818let descValue = new Uint8Array(arrayBufferDesc); 1819let gattServer: ble.GattServer = ble.createGattServer(); 1820function WriteDescriptorReq(descriptorWriteRequest: ble.DescriptorWriteRequest) { 1821 let deviceId: string = descriptorWriteRequest.deviceId; 1822 let transId: number = descriptorWriteRequest.transId; 1823 let offset: number = descriptorWriteRequest.offset; 1824 let isPrepared: boolean = descriptorWriteRequest.isPrepared; 1825 let needRsp: boolean = descriptorWriteRequest.needRsp; 1826 let value: Uint8Array = new Uint8Array(descriptorWriteRequest.value); 1827 let descriptorUuid: string = descriptorWriteRequest.descriptorUuid; 1828 1829 descValue[0] = value[0]; 1830 let serverResponse: ble.ServerResponse = {deviceId: deviceId, transId: transId, status: 0, offset: offset, value:arrayBufferDesc}; 1831 1832 try { 1833 gattServer.sendResponse(serverResponse); 1834 } catch (err) { 1835 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1836 } 1837} 1838gattServer.on('descriptorWrite', WriteDescriptorReq); 1839``` 1840 1841 1842### off('descriptorWrite') 1843 1844off(type: 'descriptorWrite', callback?: Callback<DescriptorWriteRequest>): void 1845 1846Unsubscribes from descriptor write request events. 1847 1848**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1849 1850**System capability**: SystemCapability.Communication.Bluetooth.Core 1851 1852**Parameters** 1853 1854| Name | Type | Mandatory | Description | 1855| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1856| type | string | Yes | Event type. The value is **descriptorWrite**, which indicates a descriptor write request event. | 1857| 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**.| 1858 1859**Example** 1860 1861```js 1862import { BusinessError } from '@ohos.base'; 1863try { 1864let gattServer: ble.GattServer = ble.createGattServer(); 1865gattServer.off('descriptorWrite'); 1866} catch (err) { 1867 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1868} 1869``` 1870 1871 1872### on('connectionStateChange') 1873 1874on(type: 'connectionStateChange', callback: Callback<BLEConnectionChangeState>): void 1875 1876Subscribes to BLE connection state changes. 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| type | string | Yes | Event type. The value is **connectionStateChange**, which indicates BLE connection state changes.| 1887| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | Yes | Callback invoked to return the BLE connection state. | 1888 1889**Example** 1890 1891```js 1892import { BusinessError } from '@ohos.base'; 1893import constant from '@ohos.bluetooth.constant'; 1894function Connected(bleConnectionChangeState: ble.BLEConnectionChangeState) { 1895 let deviceId: string = bleConnectionChangeState.deviceId; 1896 let status: constant.ProfileConnectionState = bleConnectionChangeState.state; 1897} 1898try { 1899let gattServer: ble.GattServer = ble.createGattServer(); 1900gattServer.on('connectionStateChange', Connected); 1901} catch (err) { 1902 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1903} 1904``` 1905 1906 1907### off('connectionStateChange') 1908 1909off(type: 'connectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 1910 1911Unsubscribes from BLE connection state changes. 1912 1913**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1914 1915**System capability**: SystemCapability.Communication.Bluetooth.Core 1916 1917**Parameters** 1918 1919| Name | Type | Mandatory | Description | 1920| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1921| type | string | Yes | Event type. The value is **connectionStateChange**, which indicates BLE connection state changes.| 1922| 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**. | 1923 1924**Example** 1925 1926```js 1927import { BusinessError } from '@ohos.base'; 1928try { 1929let gattServer: ble.GattServer = ble.createGattServer(); 1930gattServer.off('connectionStateChange'); 1931} catch (err) { 1932 console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message); 1933} 1934``` 1935 1936 1937### on('BLEMtuChange') 1938 1939on(type: 'BLEMtuChange', callback: Callback<number>): void 1940 1941Subscribes to MTU status changes for the server. 1942 1943**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1944 1945**System capability**: SystemCapability.Communication.Bluetooth.Core 1946 1947**Parameters** 1948 1949| Name | Type | Mandatory | Description | 1950| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1951| 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.| 1952| callback | Callback<number> | Yes | Callback invoked to return the number of MTU bytes.| 1953 1954**Example** 1955 1956```js 1957import { BusinessError } from '@ohos.base'; 1958try { 1959 let gattServer: ble.GattServer = ble.createGattServer(); 1960 gattServer.on('BLEMtuChange', (mtu: number) => { 1961 console.info('BLEMtuChange, mtu: ' + mtu); 1962 }); 1963} catch (err) { 1964 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1965} 1966``` 1967 1968 1969### off('BLEMtuChange') 1970 1971off(type: 'BLEMtuChange', callback?: Callback<number>): void 1972 1973Unsubscribes from MTU status changes for the server. 1974 1975**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 1976 1977**System capability**: SystemCapability.Communication.Bluetooth.Core 1978 1979**Parameters** 1980 1981| Name | Type | Mandatory | Description | 1982| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1983| 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. | 1984| 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**.| 1985 1986**Example** 1987 1988```js 1989import { BusinessError } from '@ohos.base'; 1990try { 1991 let gattServer: ble.GattServer = ble.createGattServer(); 1992 gattServer.off('BLEMtuChange'); 1993} catch (err) { 1994 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 1995} 1996``` 1997 1998 1999## GattClientDevice 2000 2001Implements the GATT client. Before using an API of this class, you must create a **GattClientDevice** instance using **createGattClientDevice(deviceId: string)**. 2002 2003 2004### connect 2005 2006connect(): void 2007 2008Connects to the remote BLE device. 2009 2010**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2011 2012**System capability**: SystemCapability.Communication.Bluetooth.Core 2013 2014**Error codes** 2015 2016For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2017 2018| ID| Error Message| 2019| -------- | ---------------------------- | 2020|2900001 | Service stopped. | 2021|2900003 | Bluetooth switch is off. | 2022|2900099 | Operation failed. | 2023 2024**Example** 2025 2026```js 2027import { BusinessError } from '@ohos.base'; 2028try { 2029 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2030 device.connect(); 2031} catch (err) { 2032 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2033} 2034``` 2035 2036 2037### disconnect 2038 2039disconnect(): void 2040 2041Disconnects from the remote BLE device. 2042 2043**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2044 2045**System capability**: SystemCapability.Communication.Bluetooth.Core 2046 2047**Error codes** 2048 2049For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2050 2051| ID| Error Message| 2052| -------- | ---------------------------- | 2053|2900001 | Service stopped. | 2054|2900003 | Bluetooth switch is off. | 2055|2900099 | Operation failed. | 2056 2057**Example** 2058 2059```js 2060import { BusinessError } from '@ohos.base'; 2061try { 2062 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2063 device.disconnect(); 2064} catch (err) { 2065 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2066} 2067``` 2068 2069 2070### close 2071 2072close(): void 2073 2074Closes this GATT client to unregister it from the protocol stack. The closed [GattClientDevice](#gattclientdevice) instance will no longer be used. 2075 2076**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2077 2078**System capability**: SystemCapability.Communication.Bluetooth.Core 2079 2080**Error codes** 2081 2082For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2083 2084| ID| Error Message| 2085| -------- | ---------------------------- | 2086|2900001 | Service stopped. | 2087|2900003 | Bluetooth switch is off. | 2088|2900099 | Operation failed. | 2089 2090**Example** 2091 2092```js 2093import { BusinessError } from '@ohos.base'; 2094try { 2095 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2096 device.close(); 2097} catch (err) { 2098 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2099} 2100``` 2101 2102 2103### getDeviceName 2104 2105getDeviceName(callback: AsyncCallback<string>): void 2106 2107Obtains the name of the remote BLE device. This API uses an asynchronous callback to return the result. 2108 2109**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2110 2111**System capability**: SystemCapability.Communication.Bluetooth.Core 2112 2113**Parameters** 2114 2115| Name | Type | Mandatory | Description | 2116| -------- | --------------------------- | ---- | ------------------------------- | 2117| callback | AsyncCallback<string> | Yes | Callback invoked to return the remote BLE device name obtained.| 2118 2119**Error codes** 2120 2121For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2122 2123| ID| Error Message| 2124| -------- | ---------------------------- | 2125|2900001 | Service stopped. | 2126|2900099 | Operation failed. | 2127 2128**Example** 2129 2130```js 2131import { BusinessError } from '@ohos.base'; 2132// callback 2133try { 2134 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2135 gattClient.connect(); 2136 gattClient.getDeviceName((err: BusinessError, data: string)=> { 2137 console.info('device name err ' + JSON.stringify(err)); 2138 console.info('device name' + JSON.stringify(data)); 2139 }) 2140} catch (err) { 2141 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2142} 2143``` 2144 2145 2146### getDeviceName 2147 2148getDeviceName(): Promise<string> 2149 2150Obtains the name of the remote BLE device. This API uses a promise to return the result. 2151 2152**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2153 2154**System capability**: SystemCapability.Communication.Bluetooth.Core 2155 2156**Return value** 2157 2158| Type | Description | 2159| --------------------- | ---------------------------------- | 2160| Promise<string> | Promise used to return the remote BLE device name.| 2161 2162**Error codes** 2163 2164For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2165 2166| ID| Error Message| 2167| -------- | ---------------------------- | 2168|2900001 | Service stopped. | 2169|2900099 | Operation failed. | 2170 2171**Example** 2172 2173```js 2174import { BusinessError } from '@ohos.base'; 2175// promise 2176try { 2177 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2178 gattClient.connect(); 2179 gattClient.getDeviceName().then((data: string) => { 2180 console.info('device name' + JSON.stringify(data)); 2181 }) 2182} catch (err) { 2183 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2184} 2185``` 2186 2187 2188### getServices 2189 2190getServices(callback: AsyncCallback<Array<GattService>>): void 2191 2192Obtains all services of the remote BLE device. This API uses an asynchronous callback to return the result. 2193 2194**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2195 2196**System capability**: SystemCapability.Communication.Bluetooth.Core 2197 2198**Parameters** 2199 2200| Name | Type | Mandatory | Description | 2201| -------- | ---------------------------------------- | ---- | ------------------------ | 2202| callback | AsyncCallback<Array<[GattService](#gattservice)>> | Yes | Callback invoked to return the services obtained.| 2203 2204**Error codes** 2205 2206For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2207 2208| ID| Error Message| 2209| -------- | ---------------------------- | 2210|2900001 | Service stopped. | 2211|2900099 | Operation failed. | 2212 2213**Example** 2214 2215```js 2216import { BusinessError } from '@ohos.base'; 2217// Callback 2218function getServices(code: BusinessError, gattServices: Array<ble.GattService>) { 2219 if (code.code == 0) { 2220 let services: Array<ble.GattService> = gattServices; 2221 console.log('bluetooth code is ' + code.code); 2222 console.log('bluetooth services size is ', services.length); 2223 2224 for (let i = 0; i < services.length; i++) { 2225 console.log('bluetooth serviceUuid is ' + services[i].serviceUuid); 2226 } 2227 } 2228} 2229 2230try { 2231 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2232 device.connect(); 2233 device.getServices(getServices); 2234} catch (err) { 2235 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2236} 2237``` 2238 2239 2240### getServices 2241 2242getServices(): Promise<Array<GattService>> 2243 2244Obtains all services of the remote BLE device. This API uses a promise to return the result. 2245 2246**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2247 2248**System capability**: SystemCapability.Communication.Bluetooth.Core 2249 2250**Return value** 2251 2252| Type | Description | 2253| ---------------------------------------- | --------------------------- | 2254| Promise<Array<[GattService](#gattservice)>> | Promise used to return the services obtained.| 2255 2256**Error codes** 2257 2258For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2259 2260| ID| Error Message| 2261| -------- | ---------------------------- | 2262|2900001 | Service stopped. | 2263|2900099 | Operation failed. | 2264 2265**Example** 2266 2267```js 2268import { BusinessError } from '@ohos.base'; 2269// Promise 2270try { 2271 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2272 device.connect(); 2273 device.getServices().then((result: Array<ble.GattService>) => { 2274 console.info('getServices successfully:' + JSON.stringify(result)); 2275 }); 2276} catch (err) { 2277 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2278} 2279``` 2280 2281 2282### readCharacteristicValue 2283 2284readCharacteristicValue(characteristic: BLECharacteristic, callback: AsyncCallback<BLECharacteristic>): void 2285 2286Reads the characteristic value of the specific service of the remote BLE device. This API uses an asynchronous callback to return the result. 2287 2288**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2289 2290**System capability**: SystemCapability.Communication.Bluetooth.Core 2291 2292**Parameters** 2293 2294| Name | Type | Mandatory | Description | 2295| -------------- | ---------------------------------------- | ---- | ----------------------- | 2296| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read. | 2297| callback | AsyncCallback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback invoked to return the characteristic value read.| 2298 2299**Error codes** 2300 2301For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2302 2303| ID| Error Message| 2304| -------- | ---------------------------- | 2305|2900001 | Service stopped. | 2306|2901000 | Read forbidden. | 2307|2900099 | Operation failed. | 2308 2309**Example** 2310 2311```js 2312import { BusinessError } from '@ohos.base'; 2313function readCcc(code: BusinessError, BLECharacteristic: ble.BLECharacteristic) { 2314 if (code.code != 0) { 2315 return; 2316 } 2317 console.log('bluetooth characteristic uuid: ' + BLECharacteristic.characteristicUuid); 2318 let value = new Uint8Array(BLECharacteristic.characteristicValue); 2319 console.log('bluetooth characteristic value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2320} 2321 2322let descriptors: Array<ble.BLEDescriptor> = []; 2323let bufferDesc = new ArrayBuffer(8); 2324let descV = new Uint8Array(bufferDesc); 2325descV[0] = 11; 2326let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2327characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2328descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2329descriptors[0] = descriptor; 2330 2331let bufferCCC = new ArrayBuffer(8); 2332let cccV = new Uint8Array(bufferCCC); 2333cccV[0] = 1; 2334let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2335characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2336characteristicValue: bufferCCC, descriptors:descriptors}; 2337 2338try { 2339 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2340 device.readCharacteristicValue(characteristic, readCcc); 2341} catch (err) { 2342 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2343} 2344``` 2345 2346 2347### readCharacteristicValue 2348 2349readCharacteristicValue(characteristic: BLECharacteristic): Promise<BLECharacteristic> 2350 2351Reads the characteristic value of the specific service of the remote BLE device. This API uses a promise to return the result. 2352 2353**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2354 2355**System capability**: SystemCapability.Communication.Bluetooth.Core 2356 2357**Parameters** 2358 2359| Name | Type | Mandatory | Description | 2360| -------------- | --------------------------------------- | ---- | -------- | 2361| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Characteristic value to read.| 2362 2363**Return value** 2364 2365| Type | Description | 2366| ---------------------------------------- | -------------------------- | 2367| Promise<[BLECharacteristic](#blecharacteristic)> | Promise used to return the characteristic value read.| 2368 2369**Error codes** 2370 2371For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2372 2373| ID| Error Message| 2374| -------- | ---------------------------- | 2375|2900001 | Service stopped. | 2376|2901000 | Read forbidden. | 2377|2900099 | Operation failed. | 2378 2379**Example** 2380 2381```js 2382import { BusinessError } from '@ohos.base'; 2383let descriptors: Array<ble.BLEDescriptor> = []; 2384let bufferDesc = new ArrayBuffer(8); 2385let descV = new Uint8Array(bufferDesc); 2386descV[0] = 11; 2387let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2388characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2389descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2390descriptors[0] = descriptor; 2391 2392let bufferCCC = new ArrayBuffer(8); 2393let cccV = new Uint8Array(bufferCCC); 2394cccV[0] = 1; 2395let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2396characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2397characteristicValue: bufferCCC, descriptors:descriptors}; 2398 2399try { 2400 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2401 device.readCharacteristicValue(characteristic); 2402} catch (err) { 2403 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2404} 2405``` 2406 2407 2408### readDescriptorValue 2409 2410readDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<BLEDescriptor>): void 2411 2412Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses an asynchronous callback to return the result. 2413 2414**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2415 2416**System capability**: SystemCapability.Communication.Bluetooth.Core 2417 2418**Parameters** 2419 2420| Name | Type | Mandatory | Description | 2421| ---------- | ---------------------------------------- | ---- | ----------------------- | 2422| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read. | 2423| callback | AsyncCallback<[BLEDescriptor](#bledescriptor)> | Yes | Callback invoked to return the descriptor read.| 2424 2425**Error codes** 2426 2427For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2428 2429| ID| Error Message| 2430| -------- | ---------------------------- | 2431|2900001 | Service stopped. | 2432|2901000 | Read forbidden. | 2433|2900099 | Operation failed. | 2434 2435**Example** 2436 2437```js 2438import { BusinessError } from '@ohos.base'; 2439function readDesc(code: BusinessError, BLEDescriptor: ble.BLEDescriptor) { 2440 if (code.code != 0) { 2441 return; 2442 } 2443 console.log('bluetooth descriptor uuid: ' + BLEDescriptor.descriptorUuid); 2444 let value = new Uint8Array(BLEDescriptor.descriptorValue); 2445 console.log('bluetooth descriptor value: ' + value[0] +','+ value[1]+','+ value[2]+','+ value[3]); 2446} 2447 2448let bufferDesc = new ArrayBuffer(8); 2449let descV = new Uint8Array(bufferDesc); 2450descV[0] = 11; 2451let descriptor: ble.BLEDescriptor = { 2452 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2453 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2454 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2455 descriptorValue: bufferDesc 2456}; 2457try { 2458 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2459 device.readDescriptorValue(descriptor, readDesc); 2460} catch (err) { 2461 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2462} 2463``` 2464 2465 2466### readDescriptorValue 2467 2468readDescriptorValue(descriptor: BLEDescriptor): Promise<BLEDescriptor> 2469 2470Reads the descriptor contained in the specific characteristic of the remote BLE device. This API uses a promise to return the result. 2471 2472**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2473 2474**System capability**: SystemCapability.Communication.Bluetooth.Core 2475 2476**Parameters** 2477 2478| Name | Type | Mandatory | Description | 2479| ---------- | ------------------------------- | ---- | -------- | 2480| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Descriptor to read.| 2481 2482**Return value** 2483 2484| Type | Description | 2485| ---------------------------------------- | -------------------------- | 2486| Promise<[BLEDescriptor](#bledescriptor)> | Promise used to return the descriptor read.| 2487 2488**Error codes** 2489 2490For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2491 2492| ID| Error Message| 2493| -------- | ---------------------------- | 2494|2900001 | Service stopped. | 2495|2901000 | Read forbidden. | 2496|2900099 | Operation failed. | 2497 2498**Example** 2499 2500```js 2501import { BusinessError } from '@ohos.base'; 2502let bufferDesc = new ArrayBuffer(8); 2503let descV = new Uint8Array(bufferDesc); 2504descV[0] = 11; 2505let descriptor: ble.BLEDescriptor = { 2506 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2507 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2508 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2509 descriptorValue: bufferDesc 2510}; 2511try { 2512 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2513 device.readDescriptorValue(descriptor); 2514} catch (err) { 2515 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2516} 2517``` 2518 2519 2520### writeCharacteristicValue 2521 2522writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType, callback: AsyncCallback<void>): void 2523 2524Writes a characteristic value to the remote BLE device. 2525 2526**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2527 2528**System capability**: SystemCapability.Communication.Bluetooth.Core 2529 2530**Parameters** 2531 2532| Name | Type | Mandatory | Description | 2533| -------------- | --------------------------------------- | ---- | ------------------- | 2534| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Binary value and other parameters of the BLE device characteristic.| 2535| writeType | GattWriteType | Yes | Write type of the Bluetooth device characteristic value.| 2536| 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.| 2537 2538**Error codes** 2539 2540For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2541 2542| ID| Error Message| 2543| -------- | ---------------------------- | 2544|2900001 | Service stopped. | 2545|2901001 | Write forbidden. | 2546|2900099 | Operation failed. | 2547 2548**Example** 2549 2550```js 2551import { BusinessError } from '@ohos.base'; 2552let descriptors: Array<ble.BLEDescriptor> = []; 2553let bufferDesc = new ArrayBuffer(8); 2554let descV = new Uint8Array(bufferDesc); 2555descV[0] = 11; 2556let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2557 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2558 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2559descriptors[0] = descriptor; 2560 2561let bufferCCC = new ArrayBuffer(8); 2562let cccV = new Uint8Array(bufferCCC); 2563cccV[0] = 1; 2564let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2565 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2566 characteristicValue: bufferCCC, descriptors:descriptors}; 2567function writeCharacteristicValueCallBack(code: BusinessError) { 2568 if (code.code != 0) { 2569 return; 2570 } 2571 console.log('bluetooth writeCharacteristicValue success'); 2572} 2573try { 2574 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2575 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE, writeCharacteristicValueCallBack); 2576} catch (err) { 2577 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2578} 2579``` 2580 2581 2582### writeCharacteristicValue 2583 2584writeCharacteristicValue(characteristic: BLECharacteristic, writeType: GattWriteType): Promise<void> 2585 2586Writes a characteristic value to the remote BLE device. 2587 2588**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2589 2590**System capability**: SystemCapability.Communication.Bluetooth.Core 2591 2592**Parameters** 2593 2594| Name | Type | Mandatory | Description | 2595| -------------- | --------------------------------------- | ---- | ------------------- | 2596| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | Binary value and other parameters of the BLE device characteristic.| 2597| writeType | GattWriteType | Yes | Write type of the Bluetooth device characteristic value.| 2598 2599**Return value** 2600 2601| Type | Description | 2602| ---------------------------------------- | -------------------------- | 2603| Promise<void> | Promise used to return the descriptor read.| 2604 2605**Error codes** 2606 2607For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2608 2609| ID| Error Message| 2610| -------- | ---------------------------- | 2611|2900001 | Service stopped. | 2612|2901001 | Write forbidden. | 2613|2900099 | Operation failed. | 2614 2615**Example** 2616 2617```js 2618import { BusinessError } from '@ohos.base'; 2619let descriptors: Array<ble.BLEDescriptor> = []; 2620let bufferDesc = new ArrayBuffer(8); 2621let descV = new Uint8Array(bufferDesc); 2622descV[0] = 11; 2623let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2624 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2625 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', descriptorValue: bufferDesc}; 2626descriptors[0] = descriptor; 2627 2628let bufferCCC = new ArrayBuffer(8); 2629let cccV = new Uint8Array(bufferCCC); 2630cccV[0] = 1; 2631let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2632 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2633 characteristicValue: bufferCCC, descriptors:descriptors}; 2634try { 2635 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2636 device.writeCharacteristicValue(characteristic, ble.GattWriteType.WRITE); 2637} catch (err) { 2638 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2639} 2640``` 2641 2642 2643### writeDescriptorValue 2644 2645writeDescriptorValue(descriptor: BLEDescriptor, callback: AsyncCallback<void>): void 2646 2647Writes binary data to the specific descriptor of the remote BLE device. 2648 2649**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2650 2651**System capability**: SystemCapability.Communication.Bluetooth.Core 2652 2653**Parameters** 2654 2655| Name | Type | Mandatory | Description | 2656| ---------- | ------------------------------- | ---- | ------------------ | 2657| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Binary value and other parameters of the BLE device descriptor.| 2658| 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.| 2659 2660**Error codes** 2661 2662For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2663 2664| ID| Error Message| 2665| -------- | ---------------------------- | 2666|2900001 | Service stopped. | 2667|2901001 | Write forbidden. | 2668|2900099 | Operation failed. | 2669 2670**Example** 2671 2672```js 2673import { BusinessError } from '@ohos.base'; 2674let bufferDesc = new ArrayBuffer(8); 2675let descV = new Uint8Array(bufferDesc); 2676descV[0] = 22; 2677let descriptor: ble.BLEDescriptor = { 2678 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2679 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2680 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2681 descriptorValue: bufferDesc 2682}; 2683try { 2684 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2685 device.writeDescriptorValue(descriptor); 2686} catch (err) { 2687 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2688} 2689``` 2690 2691 2692### writeDescriptorValue 2693 2694writeDescriptorValue(descriptor: BLEDescriptor): Promise<void> 2695 2696Writes binary data to the specific descriptor of the remote BLE device. 2697 2698**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2699 2700**System capability**: SystemCapability.Communication.Bluetooth.Core 2701 2702**Parameters** 2703 2704| Name | Type | Mandatory | Description | 2705| ---------- | ------------------------------- | ---- | ------------------ | 2706| descriptor | [BLEDescriptor](#bledescriptor) | Yes | Binary value and other parameters of the BLE device descriptor.| 2707 2708**Return value** 2709 2710| Type | Description | 2711| ---------------------------------------- | -------------------------- | 2712| Promise<void> | Promise used to return the descriptor read.| 2713 2714**Error codes** 2715 2716For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2717 2718| ID| Error Message| 2719| -------- | ---------------------------- | 2720|2900001 | Service stopped. | 2721|2901001 | Write forbidden. | 2722|2900099 | Operation failed. | 2723 2724**Example** 2725 2726```js 2727import { BusinessError } from '@ohos.base'; 2728let bufferDesc = new ArrayBuffer(8); 2729let descV = new Uint8Array(bufferDesc); 2730descV[0] = 22; 2731let descriptor: ble.BLEDescriptor = { 2732 serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2733 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2734 descriptorUuid: '00002903-0000-1000-8000-00805F9B34FB', 2735 descriptorValue: bufferDesc 2736}; 2737try { 2738 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2739 device.writeDescriptorValue(descriptor).then(() => { 2740 console.info('writeDescriptorValue promise success'); 2741 }); 2742} catch (err) { 2743 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2744} 2745``` 2746 2747 2748### getRssiValue 2749 2750getRssiValue(callback: AsyncCallback<number>): void 2751 2752Obtains 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). 2753 2754**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2755 2756**System capability**: SystemCapability.Communication.Bluetooth.Core 2757 2758**Parameters** 2759 2760| Name | Type | Mandatory | Description | 2761| -------- | --------------------------- | ---- | ------------------------------ | 2762| callback | AsyncCallback<number> | Yes | Callback invoked to return the RSSI, in dBm.| 2763 2764**Error codes** 2765 2766For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2767 2768| ID| Error Message| 2769| -------- | ---------------------------- | 2770|2900099 | Operation failed. | 2771 2772**Example** 2773 2774```js 2775import { BusinessError } from '@ohos.base'; 2776// callback 2777try { 2778 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2779 gattClient.connect(); 2780 let rssi = gattClient.getRssiValue((err: BusinessError, data: number)=> { 2781 console.info('rssi err ' + JSON.stringify(err)); 2782 console.info('rssi value' + JSON.stringify(data)); 2783 }) 2784} catch (err) { 2785 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2786} 2787``` 2788 2789 2790### getRssiValue 2791 2792getRssiValue(): Promise<number> 2793 2794Obtains 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). 2795 2796**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2797 2798**System capability**: SystemCapability.Communication.Bluetooth.Core 2799 2800**Return value** 2801 2802| Type | Description | 2803| --------------------- | --------------------------------- | 2804| Promise<number> | Promise used to return the RSSI, in dBm.| 2805 2806**Error codes** 2807 2808For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2809 2810| ID| Error Message| 2811| -------- | ---------------------------- | 2812|2900099 | Operation failed. | 2813 2814**Example** 2815 2816```js 2817import { BusinessError } from '@ohos.base'; 2818// promise 2819try { 2820 let gattClient: ble.GattClientDevice = ble.createGattClientDevice("XX:XX:XX:XX:XX:XX"); 2821 gattClient.getRssiValue().then((data: number) => { 2822 console.info('rssi' + JSON.stringify(data)); 2823 }) 2824} catch (err) { 2825 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2826} 2827``` 2828 2829 2830### setBLEMtuSize 2831 2832setBLEMtuSize(mtu: number): void 2833 2834Sets 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). 2835 2836**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2837 2838**System capability**: SystemCapability.Communication.Bluetooth.Core 2839 2840**Parameters** 2841 2842| Name | Type | Mandatory | Description | 2843| ---- | ------ | ---- | -------------- | 2844| mtu | number | Yes | MTU to set, which ranges from 22 to 512 bytes.| 2845 2846**Error codes** 2847 2848For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2849 2850| ID| Error Message| 2851| -------- | ---------------------------- | 2852|2900001 | Service stopped. | 2853|2900099 | Operation failed. | 2854 2855**Example** 2856 2857```js 2858import { BusinessError } from '@ohos.base'; 2859try { 2860 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2861 device.setBLEMtuSize(128); 2862} catch (err) { 2863 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2864} 2865``` 2866 2867 2868### setCharacteristicChangeNotification 2869 2870setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 2871 2872Sets notification for the change of a characteristic. The GATT client that subscribes to the change will be notified when the characteristic changes. 2873 2874**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2875 2876**System capability**: SystemCapability.Communication.Bluetooth.Core 2877 2878**Parameters** 2879 2880| Name | Type | Mandatory | Description | 2881| -------------- | --------------------------------------- | ---- | ----------------------------- | 2882| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | 2883| enable | boolean | Yes | Whether to notify the client of the characteristic change. The value **true** means to notify the client, and the value **false** means the opposite. | 2884| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 2885 2886**Error codes** 2887 2888For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2889 2890| ID| Error Message| 2891| -------- | ---------------------------- | 2892|2900001 | Service stopped. | 2893|2900099 | Operation failed. | 2894 2895**Example** 2896 2897```js 2898import { BusinessError } from '@ohos.base'; 2899// Create descriptors. 2900let descriptors: Array<ble.BLEDescriptor> = []; 2901let arrayBuffer = new ArrayBuffer(8); 2902let descV = new Uint8Array(arrayBuffer); 2903descV[0] = 11; 2904let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2905 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2906 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2907descriptors[0] = descriptor; 2908let arrayBufferC = new ArrayBuffer(8); 2909let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2910 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2911try { 2912 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2913 device.setCharacteristicChangeNotification(characteristic, false); 2914} catch (err) { 2915 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2916} 2917 2918``` 2919 2920 2921### setCharacteristicChangeNotification 2922 2923setCharacteristicChangeNotification(characteristic: BLECharacteristic, enable: boolean): Promise<void> 2924 2925Sets notification for the change of a characteristic. The GATT client that subscribes to the change will be notified when the characteristic changes. 2926 2927**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2928 2929**System capability**: SystemCapability.Communication.Bluetooth.Core 2930 2931**Parameters** 2932 2933| Name | Type | Mandatory | Description | 2934| -------------- | --------------------------------------- | ---- | ----------------------------- | 2935| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | 2936| 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.| 2937 2938**Return value** 2939 2940| Type | Description | 2941| ---------------------------------------- | -------------------------- | 2942| Promise<void> | Promise used to return the result.| 2943 2944**Error codes** 2945 2946For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 2947 2948| ID| Error Message| 2949| -------- | ---------------------------- | 2950|2900001 | Service stopped. | 2951|2900099 | Operation failed. | 2952 2953**Example** 2954 2955```js 2956import { BusinessError } from '@ohos.base'; 2957// Create descriptors. 2958let descriptors: Array<ble.BLEDescriptor> = []; 2959let arrayBuffer = new ArrayBuffer(8); 2960let descV = new Uint8Array(arrayBuffer); 2961descV[0] = 11; 2962let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2963 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 2964 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 2965descriptors[0] = descriptor; 2966let arrayBufferC = new ArrayBuffer(8); 2967let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 2968 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 2969try { 2970 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 2971 device.setCharacteristicChangeNotification(characteristic, false); 2972} catch (err) { 2973 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 2974} 2975 2976``` 2977 2978 2979### setCharacteristicChangeIndication 2980 2981setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean, callback: AsyncCallback<void>): void 2982 2983Sets indication for the change of a characteristic. The GATT client will be indicated when the specified characteristic value changes. 2984 2985**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 2986 2987**System capability**: SystemCapability.Communication.Bluetooth.Core 2988 2989**Parameters** 2990 2991| Name | Type | Mandatory | Description | 2992| -------------- | --------------------------------------- | ---- | ----------------------------- | 2993| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | 2994| enable | boolean | Yes | Whether to indicate the client of the characteristic change. The value **true** means to indicate the client, and the value **false** means the opposite. | 2995| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 2996 2997**Error codes** 2998 2999For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 3000 3001| ID| Error Message| 3002| -------- | ---------------------------- | 3003|2900001 | Service stopped. | 3004|2900099 | Operation failed. | 3005 3006**Example** 3007 3008```js 3009import { BusinessError } from '@ohos.base'; 3010// Create descriptors. 3011let descriptors: Array<ble.BLEDescriptor> = []; 3012let arrayBuffer = new ArrayBuffer(8); 3013let descV = new Uint8Array(arrayBuffer); 3014descV[0] = 11; 3015let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3016 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3017 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3018descriptors[0] = descriptor; 3019let arrayBufferC = new ArrayBuffer(8); 3020let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3021 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3022try { 3023 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3024 device.setCharacteristicChangeIndication(characteristic, false); 3025} catch (err) { 3026 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3027} 3028 3029``` 3030 3031 3032### setCharacteristicChangeIndication 3033 3034setCharacteristicChangeIndication(characteristic: BLECharacteristic, enable: boolean): Promise<void> 3035 3036Sets indication for the change of a characteristic. The GATT client will be indicated when the specified characteristic value changes. 3037 3038**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3039 3040**System capability**: SystemCapability.Communication.Bluetooth.Core 3041 3042**Parameters** 3043 3044| Name | Type | Mandatory | Description | 3045| -------------- | --------------------------------------- | ---- | ----------------------------- | 3046| characteristic | [BLECharacteristic](#blecharacteristic) | Yes | BLE characteristic to listen for. | 3047| enable | boolean | Yes | Whether to indicate the client of the characteristic change. The value **true** means to indicate the client, and the value **false** means the opposite. | 3048 3049**Return value** 3050 3051| Type | Description | 3052| ---------------------------------------- | -------------------------- | 3053| Promise<void> | Promise used to return the result.| 3054 3055**Error codes** 3056 3057For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 3058 3059| ID| Error Message| 3060| -------- | ---------------------------- | 3061|2900001 | Service stopped. | 3062|2900099 | Operation failed. | 3063 3064**Example** 3065 3066```js 3067import { BusinessError } from '@ohos.base'; 3068// Create descriptors. 3069let descriptors: Array<ble.BLEDescriptor> = []; 3070let arrayBuffer = new ArrayBuffer(8); 3071let descV = new Uint8Array(arrayBuffer); 3072descV[0] = 11; 3073let descriptor: ble.BLEDescriptor = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3074 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', 3075 descriptorUuid: '00002902-0000-1000-8000-00805F9B34FB', descriptorValue: arrayBuffer}; 3076descriptors[0] = descriptor; 3077let arrayBufferC = new ArrayBuffer(8); 3078let characteristic: ble.BLECharacteristic = {serviceUuid: '00001810-0000-1000-8000-00805F9B34FB', 3079 characteristicUuid: '00001820-0000-1000-8000-00805F9B34FB', characteristicValue: arrayBufferC, descriptors:descriptors}; 3080try { 3081 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3082 device.setCharacteristicChangeIndication(characteristic, false); 3083} catch (err) { 3084 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3085} 3086 3087``` 3088 3089 3090### on('BLECharacteristicChange') 3091 3092on(type: 'BLECharacteristicChange', callback: Callback<BLECharacteristic>): void 3093 3094Subscribes to BLE characteristic changes. The client can receive a notification from the server only after the **setNotifyCharacteristicChanged** method is called. 3095 3096**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3097 3098**System capability**: SystemCapability.Communication.Bluetooth.Core 3099 3100**Parameters** 3101 3102| Name | Type | Mandatory | Description | 3103| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3104| type | string | Yes | Event type. The value is **BLECharacteristicChange**, which indicates characteristic value changes. | 3105| callback | Callback<[BLECharacteristic](#blecharacteristic)> | Yes | Callback invoked to return the characteristic value changes. | 3106 3107**Example** 3108 3109```js 3110import { BusinessError } from '@ohos.base'; 3111function CharacteristicChange(characteristicChangeReq: ble.BLECharacteristic) { 3112 let serviceUuid: string = characteristicChangeReq.serviceUuid; 3113 let characteristicUuid: string = characteristicChangeReq.characteristicUuid; 3114 let value: Uint8Array = new Uint8Array(characteristicChangeReq.characteristicValue); 3115} 3116try { 3117 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3118 device.on('BLECharacteristicChange', CharacteristicChange); 3119} catch (err) { 3120 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3121} 3122``` 3123 3124 3125### off('BLECharacteristicChange') 3126 3127off(type: 'BLECharacteristicChange', callback?: Callback<BLECharacteristic>): void 3128 3129Unsubscribes from BLE characteristic changes. 3130 3131**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3132 3133**System capability**: SystemCapability.Communication.Bluetooth.Core 3134 3135**Parameters** 3136 3137| Name | Type | Mandatory | Description | 3138| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3139| type | string | Yes | Event type. The value is **BLECharacteristicChange**, which indicates characteristic value changes. | 3140| 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**. | 3141 3142**Example** 3143 3144```js 3145import { BusinessError } from '@ohos.base'; 3146try { 3147 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3148 device.off('BLECharacteristicChange'); 3149} catch (err) { 3150 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3151} 3152``` 3153 3154 3155### on('BLEConnectionStateChange') 3156 3157on(type: 'BLEConnectionStateChange', callback: Callback<BLEConnectionChangeState>): void 3158 3159Subscribes to BLE connection state changes. 3160 3161**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3162 3163**System capability**: SystemCapability.Communication.Bluetooth.Core 3164 3165**Parameters** 3166 3167| Name | Type | Mandatory | Description | 3168| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3169| type | string | Yes | Event type. The value is **BLEConnectionStateChange**, which indicates BLE connection state changes. | 3170| callback | Callback<[BLEConnectionChangeState](#bleconnectionchangestate)> | Yes | Callback invoked to return the BLE connection state. | 3171 3172**Example** 3173 3174```js 3175import { BusinessError } from '@ohos.base'; 3176function ConnectStateChanged(state: ble.BLEConnectionChangeState) { 3177 console.log('bluetooth connect state changed'); 3178 let connectState: ble.ProfileConnectionState = state.state; 3179} 3180try { 3181 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3182 device.on('BLEConnectionStateChange', ConnectStateChanged); 3183} catch (err) { 3184 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3185} 3186``` 3187 3188 3189### off('BLEConnectionStateChange') 3190 3191off(type: 'BLEConnectionStateChange', callback?: Callback<BLEConnectionChangeState>): void 3192 3193Unsubscribes from BLE connection state changes. 3194 3195**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3196 3197**System capability**: SystemCapability.Communication.Bluetooth.Core 3198 3199**Parameters** 3200 3201| Name | Type | Mandatory | Description | 3202| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3203| type | string | Yes | Event type. The value is **BLEConnectionStateChange**, which indicates BLE connection state changes. | 3204| 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**. | 3205 3206**Example** 3207 3208```js 3209import { BusinessError } from '@ohos.base'; 3210try { 3211 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3212 device.off('BLEConnectionStateChange'); 3213} catch (err) { 3214 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3215} 3216``` 3217 3218 3219### on('BLEMtuChange') 3220 3221on(type: 'BLEMtuChange', callback: Callback<number>): void 3222 3223Subscribes to MTU status changes for the client. 3224 3225**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3226 3227**System capability**: SystemCapability.Communication.Bluetooth.Core 3228 3229**Parameters** 3230 3231| Name | Type | Mandatory | Description | 3232| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3233| 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. | 3234| callback | Callback<number> | Yes | Callback invoked to return the number of MTU bytes.| 3235 3236**Example** 3237 3238```js 3239import { BusinessError } from '@ohos.base'; 3240try { 3241 let gattClient: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3242 gattClient.on('BLEMtuChange', (mtu: number) => { 3243 console.info('BLEMtuChange, mtu: ' + mtu); 3244 }); 3245} catch (err) { 3246 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3247} 3248``` 3249 3250 3251### off('BLEMtuChange') 3252 3253off(type: 'BLEMtuChange', callback?: Callback<number>): void 3254 3255Unsubscribes from MTU status changes for the client. 3256 3257**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 3258 3259**System capability**: SystemCapability.Communication.Bluetooth.Core 3260 3261**Parameters** 3262 3263| Name | Type | Mandatory | Description | 3264| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 3265| 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. | 3266| 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**.| 3267 3268**Example** 3269 3270```js 3271import { BusinessError } from '@ohos.base'; 3272try { 3273 let device: ble.GattClientDevice = ble.createGattClientDevice('XX:XX:XX:XX:XX:XX'); 3274 device.off('BLEMtuChange'); 3275} catch (err) { 3276 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 3277} 3278``` 3279 3280 3281## GattService 3282 3283Defines the GATT service API parameters. 3284 3285**System capability**: SystemCapability.Communication.Bluetooth.Core 3286 3287| Name | Type | Readable | Writable | Description | 3288| --------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3289| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3290| isPrimary | boolean | Yes | Yes | Whether the service is a primary service. The value **true** means a primary service. | 3291| characteristics | Array<[BLECharacteristic](#blecharacteristic)> | Yes | Yes | List of characteristics of the service. | 3292| includeServices | Array<[GattService](#gattservice)> | Yes | Yes | Services on which the service depends. | 3293 3294 3295## BLECharacteristic 3296 3297Defines the characteristic API parameters. 3298 3299**System capability**: SystemCapability.Communication.Bluetooth.Core 3300 3301| Name | Type | Readable | Writable | Description | 3302| ------------------- | ---------------------------------------- | ---- | ---- | ---------------------------------------- | 3303| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3304| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3305| characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | 3306| descriptors | Array<[BLEDescriptor](#bledescriptor)> | Yes | Yes | List of descriptors of the characteristic. | 3307| properties | [GattProperties](#gattproperties) | Yes | Yes | Properties of the characteristic. | 3308 3309 3310## BLEDescriptor 3311 3312Defines the BLE descriptor. 3313 3314**System capability**: SystemCapability.Communication.Bluetooth.Core 3315 3316| Name | Type | Readable | Writable | Description | 3317| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 3318| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3319| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3320| descriptorUuid | string | Yes | Yes | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| 3321| descriptorValue | ArrayBuffer | Yes | Yes | Binary value of the descriptor. | 3322 3323 3324## NotifyCharacteristic 3325 3326Defines the parameters in the notifications sent when the server characteristic value changes. 3327 3328**System capability**: SystemCapability.Communication.Bluetooth.Core 3329 3330| Name | Type | Readable | Writable | Description | 3331| ------------------- | ----------- | ---- | ---- | ---------------------------------------- | 3332| serviceUuid | string | Yes | Yes | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3333| characteristicUuid | string | Yes | Yes | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3334| characteristicValue | ArrayBuffer | Yes | Yes | Binary value of the characteristic. | 3335| 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.| 3336 3337 3338## CharacteristicReadRequest 3339 3340Defines the parameters of the **CharacteristicReadReq** event received by the server. 3341 3342**System capability**: SystemCapability.Communication.Bluetooth.Core 3343 3344| Name | Type | Readable | Writable | Description | 3345| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 3346| deviceId | string | Yes | No | Address of the remote device that sends the **CharacteristicReadReq** event, for example, XX:XX:XX:XX:XX:XX.| 3347| transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | 3348| 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.| 3349| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3350| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3351 3352 3353## CharacteristicWriteRequest 3354 3355Defines the parameters of the **CharacteristicWriteReq** event received by the server. 3356 3357**System capability**: SystemCapability.Communication.Bluetooth.Core 3358 3359| Name | Type | Readable | Writable | Description | 3360| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 3361| deviceId | string | Yes | No | Address of the remote device that sends the **CharacteristicWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| 3362| transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | 3363| 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.| 3364| isPrepared | boolean | Yes | No | Whether the write request is executed immediately.| 3365| needRsp | boolean | Yes | No | Whether to send a response to the GATT client.| 3366| value | ArrayBuffer | Yes | No | Binary value of the descriptor to write.| 3367| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3368| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3369 3370 3371## DescriptorReadRequest 3372 3373Defines the parameters of the **DescriptorReadReq** event received by the server. 3374 3375**System capability**: SystemCapability.Communication.Bluetooth.Core 3376 3377| Name | Type | Readable | Writable | Description | 3378| ------------------ | ------ | ---- | ---- | ---------------------------------------- | 3379| deviceId | string | Yes | No | Address of the remote device that sends a **DescriptorReadReq** event, for example, XX:XX:XX:XX:XX:XX.| 3380| transId | number | Yes | No | Transmission ID of the read request. The response returned by the server must use the same transmission ID. | 3381| 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.| 3382| descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| 3383| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3384| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3385 3386 3387## DescriptorWriteRequest 3388 3389Defines the parameters of the **DescriptorWriteReq** event received by the server. 3390 3391**System capability**: SystemCapability.Communication.Bluetooth.Core 3392 3393| Name | Type | Readable | Writable | Description | 3394| ------------------ | ----------- | ---- | ---- | ---------------------------------------- | 3395| deviceId | string | Yes | No | Address of the remote device that sends a **DescriptorWriteReq** event, for example, XX:XX:XX:XX:XX:XX.| 3396| transId | number | Yes | No | Transmission ID of the write request. The response returned by the server must use the same transmission ID. | 3397| 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.| 3398| isPrepared | boolean | Yes | No | Whether the write request is executed immediately. | 3399| needRsp | boolean | Yes | No | Whether to send a response to the GATT client. | 3400| value | ArrayBuffer | Yes | No | Binary value of the descriptor to write. | 3401| descriptorUuid | string | Yes | No | UUID of the descriptor, for example, **00002902-0000-1000-8000-00805f9b34fb**.| 3402| characteristicUuid | string | Yes | No | UUID of the characteristic, for example, **00002a11-0000-1000-8000-00805f9b34fb**.| 3403| serviceUuid | string | Yes | No | UUID of the service, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3404 3405 3406## ServerResponse 3407 3408Defines the parameters of the server's response to the GATT client's read/write request. 3409 3410**System capability**: SystemCapability.Communication.Bluetooth.Core 3411 3412| Name | Type | Readable | Writable | Description | 3413| -------- | ----------- | ---- | ---- | -------------------------------------- | 3414| deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX. | 3415| 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. | 3416| status | number | Yes | No | Response state. Set this parameter to **0**, which indicates a normal response. | 3417| offset | number | Yes | No | Start read/write position. The value must be the same as the offset carried in the read/write request.| 3418| value | ArrayBuffer | Yes | No | Binary data in the response. | 3419 3420 3421## BLEConnectionChangeState 3422 3423Defines the parameters of **BLEConnectChangedState**. 3424 3425**System capability**: SystemCapability.Communication.Bluetooth.Core 3426 3427| Name | Type | Readable| Writable| Description | 3428| -------- | ------------------------------------------------- | ---- | ---- | --------------------------------------------- | 3429| deviceId | string | Yes | No | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.| 3430| state | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | Yes | Yes | BLE connection state. | 3431 3432 3433## ScanResult 3434 3435Defines the scan result. 3436 3437**System capability**: SystemCapability.Communication.Bluetooth.Core 3438 3439| Name | Type | Readable | Writable | Description | 3440| -------- | ----------- | ---- | ---- | ---------------------------------- | 3441| deviceId | string | Yes | No | Address of the scanned device, for example, XX:XX:XX:XX:XX:XX.| 3442| rssi | number | Yes | No | RSSI of the device. | 3443| data | ArrayBuffer | Yes | No | Advertisement packets sent by the device. | 3444| deviceName | string | Yes | No | Name of the device detected. | 3445| connectable | boolean | Yes | No | Whether the discovered device is connectable. | 3446 3447 3448## AdvertiseSetting 3449 3450Defines the BLE advertising parameters. 3451 3452**System capability**: SystemCapability.Communication.Bluetooth.Core 3453 3454| Name | Type | Readable | Writable | Description | 3455| ----------- | ------- | ---- | ---- | ---------------------------------------- | 3456| 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).| 3457| txPower | number | Yes | Yes | Transmit power, in dBm. The value range is -127 to 1. The default value is **-7**. | 3458| connectable | boolean | Yes | Yes | Whether the advertisement is connectable. The default value is **true**. | 3459 3460 3461## AdvertiseData 3462 3463Defines the content of a BLE advertisement packet. 3464 3465**System capability**: SystemCapability.Communication.Bluetooth.Core 3466 3467| Name | Type | Readable | Writable | Description | 3468| --------------- | ---------------------------------------- | ---- | ---- | --------------------------- | 3469| serviceUuids | Array<string> | Yes | Yes | List of service UUIDs to broadcast.| 3470| manufactureData | Array<[ManufactureData](#manufacturedata)> | Yes | Yes | List of manufacturers to broadcast. | 3471| serviceData | Array<[ServiceData](#servicedata)> | Yes | Yes | List of service data to broadcast. | 3472| includeDeviceName | boolean | Yes | Yes | Whether the device name is contained. This parameter is optional. | 3473 3474## AdvertisingParams<sup>11+</sup> 3475 3476Defines the parameters for starting BLE advertising for the first time. 3477 3478**System capability**: SystemCapability.Communication.Bluetooth.Core 3479 3480| Name | Type | Readable | Writable | Description | 3481| ------------------- | ------------------------------- | ----- | ----- | ------------------------ | 3482| advertisingSettings<sup>11+</sup> | AdvertiseSetting | Yes | Yes | Parameters related advertising settings. | 3483| advertisingData<sup>11+</sup> | [AdvertiseData](#advertisedata) | Yes | Yes | Content of the advertising packet. | 3484| advertisingResponse<sup>11+</sup> | [AdvertiseData](#advertisedata) | Yes | Yes | Content of the response to the scan request.| 3485| duration<sup>11+</sup> | number | Yes | Yes | Duration for the advertising. | 3486 3487## AdvertisingEnableParams<sup>11+</sup> 3488 3489Defines the parameters for temporarily enabling BLE advertising. 3490 3491**System capability**: SystemCapability.Communication.Bluetooth.Core 3492 3493| Name | Type | Readable | Writable | Description | 3494| ------------------- | --------------------- | ----- | ----- | ------------------------ | 3495| advertisingId<sup>11+</sup> | number | Yes | Yes | ID of the advertisement. | 3496| duration<sup>11+</sup> | number | Yes | Yes | Duration for the advertising. | 3497 3498## AdvertisingDisableParams<sup>11+</sup> 3499 3500Defines the parameters for temporarily disabling BLE advertising. 3501 3502**System capability**: SystemCapability.Communication.Bluetooth.Core 3503 3504| Name | Type | Readable | Writable | Description | 3505| ------------------- | --------------------- | ----- | ----- | ------------------------ | 3506| advertisingId<sup>11+</sup> | number | Yes | Yes | ID of the advertisement. | 3507 3508## AdvertisingStateChangeInfo<sup>11+</sup> 3509 3510Represents the advertising status information. 3511 3512**System capability**: SystemCapability.Communication.Bluetooth.Core 3513 3514| Name | Type | Readable | Writable | Description | 3515| ------------------- | --------------------------------------- | ----- | ----- | ------------------------ | 3516| advertisingId<sup>11+</sup> | number | Yes | Yes | ID of the advertisement. | 3517| state<sup>11+</sup> | [AdvertisingState](#advertisingstate11) | Yes | Yes | Advertising status. | 3518 3519## ManufactureData 3520 3521Defines the content of a BLE advertisement packet. 3522 3523**System capability**: SystemCapability.Communication.Bluetooth.Core 3524 3525| Name | Type | Readable | Writable | Description | 3526| ---------------- | ------------------- | ---- | ---- | ------------------ | 3527| manufactureId | number | Yes | Yes | Manufacturer ID allocated by the Bluetooth SIG.| 3528| manufactureValue | ArrayBuffer | Yes | Yes | Manufacturer data. | 3529 3530 3531## ServiceData 3532 3533Defines the service data contained in an advertisement packet. 3534 3535**System capability**: SystemCapability.Communication.Bluetooth.Core 3536 3537| Name | Type | Readable | Writable | Description | 3538| ------------ | ----------- | ---- | ---- | ---------- | 3539| serviceUuid | string | Yes | Yes | Service UUID.| 3540| serviceValue | ArrayBuffer | Yes | Yes | Service data. | 3541 3542 3543## ScanFilter 3544 3545Defines the scan filter parameters. 3546 3547**System capability**: SystemCapability.Communication.Bluetooth.Core 3548 3549| Name | Type | Readable| Writable| Description | 3550| ---------------------------------------- | ----------- | ---- | ---- | ------------------------------------------------------------ | 3551| deviceId | string | Yes | Yes | Address of the BLE device to filter, for example, XX:XX:XX:XX:XX:XX. | 3552| name | string | Yes | Yes | Name of the BLE device to filter. | 3553| serviceUuid | string | Yes | Yes | Service UUID of the device to filter, for example, **00001888-0000-1000-8000-00805f9b34fb**.| 3554| serviceUuidMask | string | Yes | Yes | Service UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| 3555| serviceSolicitationUuid | string | Yes | Yes | Service solicitation UUID of the device to filter, for example, **00001888-0000-1000-8000-00805F9B34FB**.| 3556| serviceSolicitationUuidMask | string | Yes | Yes | Service solicitation UUID mask of the device to filter, for example, **FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF**.| 3557| serviceData | ArrayBuffer | Yes | Yes | Service data of the device to filter, for example, **[0x90, 0x00, 0xF1, 0xF2]**.| 3558| serviceDataMask | ArrayBuffer | Yes | Yes | Service data mask of the device to filter, for example, **[0xFF,0xFF,0xFF,0xFF]**.| 3559| manufactureId | number | Yes | Yes | Manufacturer ID of the device to filter, for example, **0x0006**. | 3560| manufactureData | ArrayBuffer | Yes | Yes | Manufacturer data of the device to filter, for example, **[0x1F,0x2F,0x3F]**.| 3561| manufactureDataMask | ArrayBuffer | Yes | Yes | Manufacturer data mask of the device to filter, for example, **[0xFF, 0xFF, 0xFF]**.| 3562 3563 3564## ScanOptions 3565 3566Defines the scan configuration parameters. 3567 3568**System capability**: SystemCapability.Communication.Bluetooth.Core 3569 3570| Name | Type | Readable | Writable | Description | 3571| --------- | ----------------------- | ---- | ---- | -------------------------------------- | 3572| interval | number | Yes | Yes | Delay in reporting the scan result. The default value is **0**. | 3573| dutyMode | [ScanDuty](#scanduty) | Yes | Yes | Scan duty. The default value is SCAN_MODE_LOW_POWER. | 3574| matchMode | [MatchMode](#matchmode) | Yes | Yes | Hardware filtering match mode. The default value is **MATCH_MODE_AGGRESSIVE**.| 3575 3576 3577## GattProperties<a name="GattProperties"></a> 3578 3579Defines the properties of a GATT characteristic. 3580 3581**System capability**: SystemCapability.Communication.Bluetooth.Core 3582 3583| Name | Type | Mandatory | Description | 3584| -------- | ------ |---- | ----------- | 3585| write | boolean | Yes | Permits writes of the characteristic value (with a response).| 3586| writeNoResponse | boolean | Yes | Permits writes of the characteristic value (without a response).| 3587| read | boolean | Yes | Permits reads of the characteristic value.| 3588| notify | boolean | Yes | Permits notifications of the characteristic value.| 3589| indicate | boolean | Yes | Permits notifications of the characteristic value without acknowledgement.| 3590 3591 3592## GattWriteType<a name="GattWriteType"></a> 3593 3594Enumerates the GATT write types. 3595 3596**System capability**: SystemCapability.Communication.Bluetooth.Core 3597 3598| Name | Value | Description | 3599| ------------------------------------| ------ | --------------- | 3600| WRITE | 1 | Write a characteristic value with a response from the peer device. | 3601| WRITE_NO_RESPONSE | 2 | Write characteristic value without a response from the peer device. | 3602 3603 3604## ScanDuty 3605 3606Enumerates the scan duties. 3607 3608**System capability**: SystemCapability.Communication.Bluetooth.Core 3609 3610| Name | Value | Description | 3611| --------------------- | ---- | ------------ | 3612| SCAN_MODE_LOW_POWER | 0 | Low-power mode, which is the default value.| 3613| SCAN_MODE_BALANCED | 1 | Balanced mode. | 3614| SCAN_MODE_LOW_LATENCY | 2 | Low-latency mode. | 3615 3616 3617## MatchMode 3618 3619Enumerates the hardware match modes of BLE scan filters. 3620 3621**System capability**: SystemCapability.Communication.Bluetooth.Core 3622 3623| Name | Value | Description | 3624| --------------------- | ---- | ---------------------------------------- | 3625| 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.| 3626| MATCH_MODE_STICKY | 2 | Hardware reports the scan result with a higher threshold of signal strength and sightings. | 3627 3628## AdvertisingState<sup>11+</sup> 3629 3630Enumerates the advertising statuses. 3631 3632**System capability**: SystemCapability.Communication.Bluetooth.Core 3633 3634| Name | Value | Description | 3635| -------- | ---- | ------------------------------ | 3636| STARTED<sup>11+</sup> | 1 | The BLE advertising is started for the first time. | 3637| ENABLED<sup>11+</sup> | 2 | The BLE advertising is enabled temporarily. | 3638| DISABLED<sup>11+</sup> | 3 | The BLE advertising is disabled temporarily. | 3639| STOPPED<sup>11+</sup> | 4 | The BLE advertising is stopped. | 3640