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