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&lt;string&gt;
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&lt;string&gt; | 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&lt;ScanFilter&gt;, 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&lt;[ScanFilter](#scanfilter)&gt; | 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&lt;number&gt;): 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&lt;number&gt;             | 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&lt;number&gt;
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&lt;number&gt;      | 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&lt;void&gt;): 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&lt;void&gt;                           | 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&lt;void&gt;
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&lt;void&gt;      | 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&lt;void&gt;): 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&lt;void&gt;                             | 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&lt;void&gt;
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&lt;void&gt;        | 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&lt;void&gt;): 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&lt;void&gt;    | 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&lt;void&gt;
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&lt;void&gt;        | 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&lt;AdvertisingStateChangeInfo&gt;): 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&lt;[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)&gt; | 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&lt;AdvertisingStateChangeInfo&gt;): 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&lt;[AdvertisingStateChangeInfo](#advertisingstatechangeinfo11)&gt; | 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&lt;Array&lt;ScanResult&gt;&gt;): 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&lt;Array&lt;[ScanResult](#scanresult)&gt;&gt; | 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&lt;Array&lt;ScanResult&gt;&gt;): 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&lt;Array&lt;[ScanResult](#scanresult)&gt;&gt; | 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&lt;void&gt;): 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&lt;void&gt;  | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;CharacteristicReadRequest&gt;): 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&lt;[CharacteristicReadRequest](#characteristicreadrequest)&gt; | 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&lt;CharacteristicReadRequest&gt;): 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&lt;[CharacteristicReadRequest](#characteristicreadrequest)&gt; | 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&lt;CharacteristicWriteRequest&gt;): 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&lt;[CharacteristicWriteRequest](#characteristicwriterequest)&gt; | 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&lt;CharacteristicWriteRequest&gt;): 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&lt;[CharacteristicWriteRequest](#characteristicwriterequest)&gt; | 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&lt;DescriptorReadRequest&gt;): 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&lt;[DescriptorReadRequest](#descriptorreadrequest)&gt; | 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&lt;DescriptorReadRequest&gt;): 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&lt;[DescriptorReadRequest](#descriptorreadrequest)&gt; | 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&lt;DescriptorWriteRequest&gt;): 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&lt;[DescriptorWriteRequest](#descriptorwriterequest)&gt; | 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&lt;DescriptorWriteRequest&gt;): 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&lt;[DescriptorWriteRequest](#descriptorwriterequest)&gt; | 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&lt;BLEConnectionChangeState&gt;): 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&lt;[BLEConnectionChangeState](#bleconnectionchangestate)&gt; | 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&lt;BLEConnectionChangeState&gt;): 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&lt;[BLEConnectionChangeState](#bleconnectionchangestate)&gt; | 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&lt;number&gt;): 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&lt;number&gt; | 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&lt;number&gt;): 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&lt;number&gt; | 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&lt;string&gt;): 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&lt;string&gt; | 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&lt;string&gt;
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&lt;string&gt; | 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&lt;Array&lt;GattService&gt;&gt;): 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&lt;Array&lt;[GattService](#gattservice)&gt;&gt; | 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&lt;Array&lt;GattService&gt;&gt;
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&lt;Array&lt;[GattService](#gattservice)&gt;&gt; | 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&lt;BLECharacteristic&gt;): 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&lt;[BLECharacteristic](#blecharacteristic)&gt; | 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&lt;BLECharacteristic&gt;
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&lt;[BLECharacteristic](#blecharacteristic)&gt; | 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&lt;BLEDescriptor&gt;): 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&lt;[BLEDescriptor](#bledescriptor)&gt; | 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&lt;BLEDescriptor&gt;
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&lt;[BLEDescriptor](#bledescriptor)&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;number&gt;): 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&lt;number&gt; | 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&lt;number&gt;
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&lt;number&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;void&gt;): 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&lt;void&gt; | 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&lt;void&gt;
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&lt;void&gt; | 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&lt;BLECharacteristic&gt;): 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&lt;[BLECharacteristic](#blecharacteristic)&gt; | 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&lt;BLECharacteristic&gt;): 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&lt;[BLECharacteristic](#blecharacteristic)&gt; | 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&lt;BLEConnectionChangeState&gt;): 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&lt;[BLEConnectionChangeState](#bleconnectionchangestate)&gt; | 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&lt;BLEConnectionChangeState&gt;): 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&lt;[BLEConnectionChangeState](#bleconnectionchangestate)&gt; | 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&lt;number&gt;): 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&lt;number&gt; | 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&lt;number&gt;): 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&lt;number&gt; | 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&lt;[BLECharacteristic](#blecharacteristic)&gt; | Yes   | Yes   | List of characteristics of the service.                            |
3702| includeServices | Array&lt;[GattService](#gattservice)&gt; | 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&lt;[BLEDescriptor](#bledescriptor)&gt; | 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&lt;string&gt;                      | Yes   | Yes   | List of service UUIDs to broadcast.|
3904| manufactureData | Array&lt;[ManufactureData](#manufacturedata)&gt; | Yes   | Yes   | List of manufacturers to broadcast.          |
3905| serviceData     | Array&lt;[ServiceData](#servicedata)&gt; | 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