1# @ohos.bluetooth.connection (Bluetooth Connection Module)
2
3The **connection** 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 { connection } from '@kit.ConnectivityKit';
15```
16
17
18## connection.pairDevice
19
20pairDevice(deviceId: string, callback: AsyncCallback<void>): void
21
22Pairs a Bluetooth device. This API uses an asynchronous callback to return the result.
23
24**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
25
26**Atomic service API**: This API can be used in atomic services since API version 12.
27
28**System capability**: SystemCapability.Communication.Bluetooth.Core
29
30**Parameters**
31
32| Name     | Type    | Mandatory  | Description                                 |
33| -------- | ------ | ---- | ----------------------------------- |
34| deviceId | string | Yes   | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.|
35| callback | AsyncCallback<void>  | Yes   | Callback used to return the result. If the pairing is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
36
37**Error codes**
38
39For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
40
41| ID| Error Message|
42| -------- | ---------------------------- |
43|201 | Permission denied.                 |
44|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
45|801 | Capability not supported.          |
46|2900001 | Service stopped.                         |
47|2900003 | Bluetooth disabled.                 |
48|2900099 | Operation failed.                        |
49
50**Example**
51
52```js
53import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
54//callback
55try {
56    connection.pairDevice('11:22:33:44:55:66', (err: BusinessError) => {
57        console.info('pairDevice, device name err:' + JSON.stringify(err));
58    });
59} catch (err) {
60    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
61}
62
63```
64
65
66## connection.pairDevice
67
68pairDevice(deviceId: string): Promise<void>
69
70Pairs a Bluetooth device. This API uses a promise to return the result.
71
72**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
73
74**Atomic service API**: This API can be used in atomic services since API version 12.
75
76**System capability**: SystemCapability.Communication.Bluetooth.Core
77
78**Parameters**
79
80| Name     | Type    | Mandatory  | Description                                 |
81| -------- | ------ | ---- | ----------------------------------- |
82| deviceId | string | Yes   | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.|
83
84**Return value**
85
86| Type                 | Description           |
87| ------------------- | ------------- |
88| Promise<void> | Promise used to return the result.|
89
90**Error codes**
91
92For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
93
94| ID| Error Message|
95| -------- | ---------------------------- |
96|201 | Permission denied.                 |
97|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
98|801 | Capability not supported.          |
99|2900001 | Service stopped.                         |
100|2900003 | Bluetooth disabled.                 |
101|2900099 | Operation failed.                        |
102
103**Example**
104
105```js
106import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
107//promise
108try {
109    connection.pairDevice('11:22:33:44:55:66').then(() => {
110        console.info('pairDevice');
111    }, (error: BusinessError) => {
112        console.info('pairDevice: errCode:' + error.code + ',errMessage' + error.message);
113    })
114
115} catch (err) {
116    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
117}
118```
119
120
121## connection.getRemoteDeviceName
122
123getRemoteDeviceName(deviceId: string): string
124
125Obtains the name of a remote Bluetooth device.
126
127**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
128
129**Atomic service API**: This API can be used in atomic services since API version 12.
130
131**System capability**: SystemCapability.Communication.Bluetooth.Core
132
133**Parameters**
134
135| Name     | Type    | Mandatory  | Description                               |
136| -------- | ------ | ---- | --------------------------------- |
137| deviceId | string | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
138
139**Return value**
140
141| Type    | Description           |
142| ------ | ------------- |
143| string | Device name (a string) obtained.|
144
145**Error codes**
146
147For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
148
149| ID| Error Message|
150| -------- | ---------------------------- |
151|201 | Permission denied.                 |
152|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
153|801 | Capability not supported.          |
154|2900001 | Service stopped.                         |
155|2900003 | Bluetooth disabled.                 |
156|2900099 | Operation failed.                        |
157
158**Example**
159
160```js
161import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
162try {
163    let remoteDeviceName: string = connection.getRemoteDeviceName('XX:XX:XX:XX:XX:XX');
164} catch (err) {
165    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
166}
167```
168
169
170## connection.getRemoteDeviceClass
171
172getRemoteDeviceClass(deviceId: string): DeviceClass
173
174Obtains the class of a remote Bluetooth device.
175
176**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
177
178**System capability**: SystemCapability.Communication.Bluetooth.Core
179
180**Parameters**
181
182| Name     | Type    | Mandatory  | Description                               |
183| -------- | ------ | ---- | --------------------------------- |
184| deviceId | string | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
185
186**Return value**
187
188| Type                         | Description      |
189| --------------------------- | -------- |
190| [DeviceClass](#deviceclass) | Class of the remote device obtained.|
191
192**Error codes**
193
194For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
195
196| ID| Error Message|
197| -------- | ---------------------------- |
198|201 | Permission denied.                 |
199|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
200|801 | Capability not supported.          |
201|2900001 | Service stopped.                         |
202|2900003 | Bluetooth disabled.                 |
203|2900099 | Operation failed.                        |
204
205**Example**
206
207```js
208import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
209try {
210    let remoteDeviceClass: connection.DeviceClass = connection.getRemoteDeviceClass('XX:XX:XX:XX:XX:XX');
211} catch (err) {
212    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
213}
214```
215
216
217## connection.getRemoteProfileUuids<sup>12+</sup>
218
219getRemoteProfileUuids(deviceId: string, callback: AsyncCallback&lt;Array&lt;ProfileUuids&gt;&gt;): void
220
221Obtains the profile UUIDs of a remote Bluetooth device. This API uses an asynchronous callback to return the result.
222
223**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
224
225**System capability**: SystemCapability.Communication.Bluetooth.Core
226
227**Parameters**
228
229| Name     | Type    | Mandatory  | Description                                 |
230| -------- | ------ | ---- | ----------------------------------- |
231| deviceId | string | Yes   | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.|
232| callback | AsyncCallback&lt;Array&lt;[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)&gt;&gt; | Yes   | Callback used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
233
234**Error codes**
235
236For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
237
238| ID| Error Message|
239| -------- | ---------------------------- |
240|201 | Permission denied.                 |
241|401 | Invalid parameter.    |
242|801 | Capability not supported.          |
243|2900001 | Service stopped.                         |
244|2900003 | Bluetooth disabled.                 |
245|2900099 | Operation failed.                        |
246
247**Example**
248
249```js
250import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
251try {
252    connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX', (err: BusinessError, data: Array<connection.ProfileUuids>) => {
253        console.info('getRemoteProfileUuids, err: ' + JSON.stringify(err) + ', data: ' + JSON.stringify(data));
254    });
255} catch (err) {
256    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
257}
258
259```
260
261
262## connection.getRemoteProfileUuids<sup>12+</sup>
263
264getRemoteProfileUuids(deviceId: string): Promise&lt;Array&lt;ProfileUuids&gt;&gt;
265
266Obtains the profile UUIDs of a remote Bluetooth device. This API uses a promise to return the result.
267
268**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
269
270**System capability**: SystemCapability.Communication.Bluetooth.Core
271
272**Parameters**
273
274| Name     | Type    | Mandatory  | Description                                 |
275| -------- | ------ | ---- | ----------------------------------- |
276| deviceId | string | Yes   | Address of the device to pair, for example, XX:XX:XX:XX:XX:XX.|
277
278**Return value**
279
280| Type                 | Description           |
281| ------------------- | ------------- |
282|   Promise&lt;Array&lt;[ProfileUuids](js-apis-bluetooth-constant.md#profileuuids12)&gt;&gt; | Promise used to return the result.|
283
284**Error codes**
285
286For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
287
288| ID| Error Message|
289| -------- | ---------------------------- |
290|201 | Permission denied.                 |
291|401 | Invalid parameter.    |
292|801 | Capability not supported.          |
293|2900001 | Service stopped.                         |
294|2900003 | Bluetooth disabled.                 |
295|2900099 | Operation failed.                        |
296
297**Example**
298
299```js
300import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
301try {
302    connection.getRemoteProfileUuids('XX:XX:XX:XX:XX:XX').then(() => {
303        console.info('getRemoteProfileUuids');
304    }, (err: BusinessError) => {
305        console.error('getRemoteProfileUuids: errCode' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
306    });
307} catch (err) {
308    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
309}
310```
311
312
313## connection.getLocalName
314
315getLocalName(): string
316
317Obtains the name of the local Bluetooth device.
318
319**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
320
321**System capability**: SystemCapability.Communication.Bluetooth.Core
322
323**Return value**
324
325| Type    | Description       |
326| ------ | --------- |
327| string | Name of the local Bluetooth device obtained.|
328
329**Error codes**
330
331For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
332
333| ID| Error Message|
334| -------- | ---------------------------- |
335|201 | Permission denied.                 |
336|801 | Capability not supported.          |
337|2900001 | Service stopped.                         |
338|2900099 | Operation failed.                        |
339
340**Example**
341
342```js
343import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
344try {
345    let localName: string = connection.getLocalName();
346} catch (err) {
347    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
348}
349```
350
351
352## connection.getPairedDevices
353
354getPairedDevices(): Array&lt;string&gt;
355
356Obtains the paired devices.
357
358**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
359
360**Atomic service API**: This API can be used in atomic services since API version 12.
361
362**System capability**: SystemCapability.Communication.Bluetooth.Core
363
364**Return value**
365
366| Type                 | Description           |
367| ------------------- | ------------- |
368| Array&lt;string&gt; | Addresses of the paired Bluetooth devices. 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.|
369
370**Error codes**
371
372For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
373
374| ID| Error Message|
375| -------- | ---------------------------- |
376|201 | Permission denied.                 |
377|801 | Capability not supported.          |
378|2900001 | Service stopped.                         |
379|2900003 | Bluetooth disabled.                 |
380|2900099 | Operation failed.                        |
381
382**Example**
383
384```js
385import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
386try {
387    let devices: Array<string> = connection.getPairedDevices();
388} catch (err) {
389    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
390}
391```
392
393
394## connection.getPairState<sup>11+</sup>
395
396getPairState(deviceId: string): BondState
397
398Obtains the Bluetooth pairing state.
399
400**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
401
402**Atomic service API**: This API can be used in atomic services since API version 12.
403
404**System capability**: SystemCapability.Communication.Bluetooth.Core
405
406**Parameters**
407
408| Name     | Type    | Mandatory  | Description                               |
409| -------- | ------ | ---- | --------------------------------- |
410| deviceId | string | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
411
412**Return value**
413
414| Type                         | Description      |
415| --------------------------- | -------- |
416| [BondState](#bondstate) | Bluetooth pairing state obtained.|
417
418**Error codes**
419
420For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
421
422| ID| Error Message|
423| -------- | ---------------------------- |
424|201 | Permission denied.                 |
425|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
426|801 | Capability not supported.          |
427|2900001 | Service stopped.                         |
428|2900003 | Bluetooth disabled.                 |
429|2900099 | Operation failed.                        |
430
431**Example**
432
433```js
434import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
435try {
436    let res: connection.BondState = connection.getPairState("XX:XX:XX:XX:XX:XX");
437    console.info('getPairState: ' + res);
438} catch (err) {
439    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
440}
441```
442
443
444## connection.getProfileConnectionState
445
446getProfileConnectionState(profileId?: ProfileId): ProfileConnectionState
447
448Obtains the connection state of a Bluetooth profile. The **ProfileId** parameter is optional. If **ProfileId** is specified, the connection state of the specified profile is returned. If no **ProfileId** is specified, [STATE_CONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate) is returned by any connected profile. If no profile is connected, [STATE_DISCONNECTED](js-apis-bluetooth-constant.md#profileconnectionstate) is returned.
449
450**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
451
452**System capability**: SystemCapability.Communication.Bluetooth.Core
453
454**Parameters**
455
456| Name      | Type       | Mandatory  | Description                                   |
457| --------- | --------- | ---- | ------------------------------------- |
458| profileId | [ProfileId](js-apis-bluetooth-constant.md#profileid) | No   | ID of the target profile, for example, **PROFILE_A2DP_SOURCE**.|
459
460**Return value**
461
462| Type                                             | Description               |
463| ------------------------------------------------- | ------------------- |
464| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | Profile connection state obtained.|
465
466**Error codes**
467
468For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
469
470| ID| Error Message|
471| -------- | ---------------------------- |
472|201 | Permission denied.                 |
473|401 | Invalid parameter. Possible causes: 1. Incorrect parameter types.        |
474|801 | Capability not supported.          |
475|2900001 | Service stopped.                         |
476|2900003 | Bluetooth disabled.                 |
477|2900004 | Profile not supported.                |
478|2900099 | Operation failed.                        |
479
480**Example**
481
482```js
483import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
484import { constant } from '@kit.ConnectivityKit';
485try {
486    let result: connection.ProfileConnectionState = connection.getProfileConnectionState(constant.ProfileId.PROFILE_A2DP_SOURCE);
487} catch (err) {
488    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
489}
490```
491
492
493## connection.setDevicePairingConfirmation
494
495setDevicePairingConfirmation(deviceId: string, accept: boolean): void
496
497Sets the device pairing confirmation.
498
499**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH (available only for system applications)
500
501**System capability**: SystemCapability.Communication.Bluetooth.Core
502
503**Parameters**
504
505| Name   | Type     | Mandatory  | Description                              |
506| ------   | ------- | ---- | -------------------------------- |
507| deviceId | string  | Yes   | Address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
508| accept   | boolean | Yes   | Whether to accept the pairing request. The value **true** means to accept the pairing request, and the value **false** means the opposite.       |
509
510**Error codes**
511
512For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
513
514| ID| Error Message|
515| -------- | ---------------------------- |
516|201 | Permission denied.                 |
517|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
518|801 | Capability not supported.          |
519|2900001 | Service stopped.                         |
520|2900003 | Bluetooth disabled.                 |
521|2900099 | Operation failed.                        |
522
523**Example**
524
525```js
526import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
527// Subscribe to the pinRequired event and configure the pairing confirmation after receiving a pairing request from the remote device.
528function onReceivePinRequiredEvent(data: connection.PinRequiredParam) { // data is the input parameter for the pairing request.
529    console.info('pin required  = '+ JSON.stringify(data));
530    connection.setDevicePairingConfirmation(data.deviceId, true);
531}
532try {
533    connection.on('pinRequired', onReceivePinRequiredEvent);
534} catch (err) {
535    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
536}
537```
538
539
540## connection.setDevicePinCode
541
542setDevicePinCode(deviceId: string, code: string, callback: AsyncCallback&lt;void&gt;): void
543
544Sets the PIN for the device when **PinType** is **PIN_TYPE_ENTER_PIN_CODE** or **PIN_TYPE_PIN_16_DIGITS**. This API uses an asynchronous callback to return the result.
545
546**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
547
548**System capability**: SystemCapability.Communication.Bluetooth.Core
549
550**Parameters**
551
552| Name   | Type     | Mandatory  | Description                              |
553| ------ | ------- | ---- | -------------------------------- |
554| deviceId | string  | Yes   | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
555| code   | string  | Yes   | PIN to set.       |
556| 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.       |
557
558**Error codes**
559
560For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
561
562| ID| Error Message|
563| -------- | ---------------------------- |
564|201 | Permission denied.                 |
565|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
566|801 | Capability not supported.          |
567|2900001 | Service stopped.                         |
568|2900003 | Bluetooth disabled.                 |
569|2900099 | Operation failed.                        |
570
571**Example**
572
573```js
574import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
575//callback
576try {
577    connection.setDevicePinCode('11:22:33:44:55:66', '12345', (err: BusinessError) => {
578        console.info('setDevicePinCode,device name err:' + JSON.stringify(err));
579    });
580} catch (err) {
581    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
582}
583```
584
585
586## connection.setDevicePinCode
587
588setDevicePinCode(deviceId: string, code: string): Promise&lt;void&gt;
589
590Sets the PIN for the device when **PinType** is **PIN_TYPE_ENTER_PIN_CODE** or **PIN_TYPE_PIN_16_DIGITS**. This API uses a promise to return the result.
591
592**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
593
594**System capability**: SystemCapability.Communication.Bluetooth.Core
595
596**Parameters**
597
598| Name   | Type     | Mandatory  | Description                              |
599| ------ | ------- | ---- | -------------------------------- |
600| deviceId | string  | Yes   | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
601| code   | string  | Yes   | PIN to set.       |
602
603**Return value**
604
605| Type                 | Description           |
606| ------------------- | ------------- |
607| Promise&lt;void&gt; | Promise used to return the result.|
608
609**Error codes**
610
611For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
612
613| ID| Error Message|
614| -------- | ---------------------------- |
615|201 | Permission denied.                 |
616|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
617|801 | Capability not supported.          |
618|2900001 | Service stopped.                         |
619|2900003 | Bluetooth disabled.                 |
620|2900099 | Operation failed.                        |
621
622**Example**
623
624```js
625import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
626//promise
627try {
628    connection.setDevicePinCode('11:22:33:44:55:66', '12345').then(() => {
629        console.info('setDevicePinCode');
630    }, (error: BusinessError) => {
631        console.info('setDevicePinCode: errCode:' + error.code + ',errMessage' + error.message);
632    })
633
634} catch (err) {
635    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
636}
637```
638
639
640## connection.setLocalName<sup>(deprecated)</sup>
641
642setLocalName(name: string): void
643
644Sets the name of the local Bluetooth device.
645
646> **NOTE**<br>
647> This API is supported since API version 10 and deprecated since API version 12. No substitute is provided.
648
649**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
650
651**System capability**: SystemCapability.Communication.Bluetooth.Core
652
653**Parameters**
654
655| Name | Type    | Mandatory  | Description                   |
656| ---- | ------ | ---- | --------------------- |
657| name | string | Yes   | Bluetooth device name to set. It cannot exceed 248 bytes.|
658
659**Error codes**
660
661For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
662
663| ID| Error Message|
664| -------- | ---------------------------- |
665|201 | Permission denied.                 |
666|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
667|801 | Capability not supported.          |
668|2900001 | Service stopped.                         |
669|2900003 | Bluetooth disabled.                 |
670|2900099 | Operation failed.                        |
671
672**Example**
673
674```js
675import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
676try {
677    connection.setLocalName('device_name');
678} catch (err) {
679    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
680}
681```
682
683
684## connection.setBluetoothScanMode
685
686setBluetoothScanMode(mode: ScanMode, duration: number): void
687
688Sets the Bluetooth scan mode so that the device can be discovered by a remote device.
689
690**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
691
692**System capability**: SystemCapability.Communication.Bluetooth.Core
693
694**Parameters**
695
696| Name     | Type                   | Mandatory  | Description                          |
697| -------- | --------------------- | ---- | ---------------------------- |
698| mode     | [ScanMode](#scanmode) | Yes   | Bluetooth scan mode to set. If the scan times out (**duration** is not **0**) when the scan mode is **SCAN_MODE_GENERAL_DISCOVERABLE**, the scan mode will be reset to **SCAN_MODE_CONNECTABLE**.              |
699| duration | number                | Yes   | Duration (in ms) in which the device can be discovered. The value **0** indicates unlimited time.|
700
701**Error codes**
702
703For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
704
705| ID| Error Message|
706| -------- | ---------------------------- |
707|201 | Permission denied.                 |
708|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
709|801 | Capability not supported.          |
710|2900001 | Service stopped.                         |
711|2900003 | Bluetooth disabled.                 |
712|2900099 | Operation failed.                        |
713
714**Example**
715
716```js
717import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
718try {
719    // The device can be discovered and connected only when the discoverable and connectable mode is used.
720    connection.setBluetoothScanMode(connection.ScanMode.SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE, 100);
721} catch (err) {
722    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
723}
724```
725
726
727## connection.getBluetoothScanMode
728
729getBluetoothScanMode(): ScanMode
730
731Obtains the Bluetooth scan mode.
732
733**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
734
735**System capability**: SystemCapability.Communication.Bluetooth.Core
736
737**Return value**
738
739| Type                   | Description     |
740| --------------------- | ------- |
741| [ScanMode](#scanmode) | Bluetooth scan mode obtained.|
742
743**Error codes**
744
745For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
746
747| ID| Error Message|
748| -------- | ---------------------------- |
749|201 | Permission denied.                 |
750|801 | Capability not supported.          |
751|2900001 | Service stopped.                         |
752|2900003 | Bluetooth disabled.                 |
753|2900099 | Operation failed.                        |
754
755**Example**
756
757```js
758import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
759try {
760    let scanMode: connection.ScanMode = connection.getBluetoothScanMode();
761} catch (err) {
762    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
763}
764```
765
766
767## connection.startBluetoothDiscovery
768
769startBluetoothDiscovery(): void
770
771Starts to discover Bluetooth devices.
772
773**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
774
775**Atomic service API**: This API can be used in atomic services since API version 12.
776
777**System capability**: SystemCapability.Communication.Bluetooth.Core
778
779**Error codes**
780
781For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
782
783| ID| Error Message|
784| -------- | ---------------------------- |
785|201 | Permission denied.                 |
786|801 | Capability not supported.          |
787|2900001 | Service stopped.                         |
788|2900003 | Bluetooth disabled.                 |
789|2900099 | Operation failed.                        |
790
791**Example**
792
793```js
794import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
795function onReceiveEvent(data: Array<string>) {
796    console.info('data length' + data.length);
797}
798try {
799    connection.on('bluetoothDeviceFind', onReceiveEvent);
800    connection.startBluetoothDiscovery();
801} catch (err) {
802    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
803}
804```
805
806
807## connection.stopBluetoothDiscovery
808
809stopBluetoothDiscovery(): void
810
811Stops discovering Bluetooth devices.
812
813**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
814
815**Atomic service API**: This API can be used in atomic services since API version 12.
816
817**System capability**: SystemCapability.Communication.Bluetooth.Core
818
819**Error codes**
820
821For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
822
823| ID| Error Message|
824| -------- | ---------------------------- |
825|201 | Permission denied.                 |
826|801 | Capability not supported.          |
827|2900001 | Service stopped.                         |
828|2900003 | Bluetooth disabled.                 |
829|2900099 | Operation failed.                        |
830
831**Example**
832
833```js
834import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
835try {
836    connection.stopBluetoothDiscovery();
837} catch (err) {
838    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
839}
840```
841
842
843## connection.isBluetoothDiscovering<sup>11+</sup>
844
845isBluetoothDiscovering(): boolean
846
847Checks whether Bluetooth discovery is enabled.
848
849**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
850
851**System capability**: SystemCapability.Communication.Bluetooth.Core
852
853**Return value**
854
855| Type                 | Description           |
856| ------------------- | ------------- |
857|   boolean           | Returns **true** if Bluetooth discovery is enabled; returns **false** otherwise.|
858
859**Error codes**
860
861For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
862
863| ID| Error Message|
864| -------- | ---------------------------- |
865|201 | Permission denied.                 |
866|801 | Capability not supported.          |
867|2900001 | Service stopped.                         |
868|2900003 | Bluetooth disabled.                 |
869|2900099 | Operation failed.                        |
870
871**Example**
872
873```js
874import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
875try {
876    let res: boolean = connection.isBluetoothDiscovering();
877    console.info('isBluetoothDiscovering: ' + res);
878} catch (err) {
879    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
880}
881```
882
883## connection.setRemoteDeviceName<sup>12+</sup>
884
885setRemoteDeviceName(deviceId: string, name: string): Promise&lt;void&gt;
886
887Sets the name of a remote Bluetooth device. This API uses a promise to return the result.
888
889**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
890
891**Atomic service API**: This API can be used in atomic services since API version 12.
892
893**System capability**: SystemCapability.Communication.Bluetooth.Core
894
895**Parameters**
896
897| Name     | Type                                 | Mandatory  | Description                                    |
898| -------- | ----------------------------------- | ---- | -------------------------------------- |
899| deviceId     | string                              | Yes   | MAC address of the remote device, for example, XX:XX:XX:XX:XX:XX.|
900| name | string | Yes   | Name of the remote device to set. The name cannot exceed 64 bytes.   |
901
902**Return value**
903
904| Type                 | Description           |
905| ------------------- | ------------- |
906| Promise&lt;void&gt; | Promise used to return the device name set. If the operation fails, an error code is returned.|
907
908**Error codes**
909
910For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
911
912| ID| Error Message|
913| -------- | ---------------------------- |
914|201 | Permission denied.                 |
915|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.            |
916|2900001 | Service stopped.                         |
917|2900003 | Bluetooth disabled.                 |
918
919**Example**
920
921```js
922import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
923//promise
924try {
925    connection.setRemoteDeviceName('11:22:33:44:55:66', 'RemoteDeviceName').then(() => {
926        console.info('setRemoteDeviceName success');
927    }, (error: BusinessError) => {
928        console.error('setRemoteDeviceName: errCode:' + error.code + ',errMessage' + error.message);
929    })
930
931} catch (err) {
932    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
933}
934```
935
936
937## connection.getRemoteDeviceBatteryInfo<sup>12+</sup>
938
939getRemoteDeviceBatteryInfo(deviceId: string): Promise&lt;BatteryInfo&gt;
940
941obtains the battery information of a remote Bluetooth device. This API uses a promise to return the result.
942
943**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
944
945**System capability**: SystemCapability.Communication.Bluetooth.Core
946
947**Parameters**
948
949| Name   | Type     | Mandatory  | Description                              |
950| ------ | ------- | ---- | -------------------------------- |
951| deviceId | string  | Yes   | MAC address of the remote device, for example, **11:22:33:AA:BB:FF**.|
952
953**Return value**
954
955| Type                 | Description        |
956| ------------------- | ------------- |
957| Promise&lt;[BatteryInfo](#batteryinfo12)&gt; | Promise used to return the battery information obtained.|
958
959**Error codes**
960
961For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
962
963| ID| Error Message|
964| -------- | ---------------------------- |
965|201 | Permission denied.                 |
966|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.            |
967|2900001 | Service stopped.                         |
968|2900003 | Bluetooth disabled.                 |
969
970**Example**
971
972```js
973import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
974// promise
975try {
976    connection.getRemoteDeviceBatteryInfo('11:22:33:AA:BB:FF').then((data: connection.BatteryInfo) => {
977        console.info('getRemoteDeviceBatteryInfo success, DeviceType:' + JSON.stringify(data));
978    });
979} catch (err) {
980    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
981}
982```
983
984
985## connection.on('batteryChange')<sup>12+</sup>
986
987on(type: 'batteryChange', callback: Callback&lt;BatteryInfo&gt;): void
988
989Subscribes to the changes in the battery information of a remote Bluetooth device. This API uses an asynchronous callback to return the result.
990
991**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
992
993**System capability**: SystemCapability.Communication.Bluetooth.Core
994
995**Parameters**
996
997| Name     | Type                                 | Mandatory  | Description                                    |
998| -------- | ----------------------------------- | ---- | -------------------------------------- |
999| type     | string                              | Yes   | Event type. The value is **'batteryChange'**, which indicates the change in battery information of a remote Bluetooth device.|
1000| callback | Callback&lt;[BatteryInfo](#batteryinfo12)&gt; | Yes   | Callback used to return the battery information.   |
1001
1002**Error codes**
1003
1004For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1005
1006| ID| Error Message|
1007| -------- | ---------------------------- |
1008|201 | Permission denied.                 |
1009|2900099 | Operation failed.                        |
1010
1011**Example**
1012
1013```js
1014import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1015let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
1016    console.info('BatteryInfo = '+ JSON.stringify(data));
1017}
1018try {
1019    connection.on('batteryChange', onReceiveEvent);
1020} catch (err) {
1021    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1022}
1023```
1024
1025
1026## connection.off('batteryChange')<sup>12+</sup>
1027
1028off(type: 'batteryChange', callback?: Callback&lt;BatteryInfo&gt;): void
1029
1030Unsubscribes from the changes in the battery information of a remote Bluetooth device.
1031
1032**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1033
1034**System capability**: SystemCapability.Communication.Bluetooth.Core
1035
1036**Parameters**
1037
1038| Name     | Type                                 | Mandatory  | Description                                      |
1039| -------- | ----------------------------------- | ---- | ---------------------------------------- |
1040| type     | string                              | Yes   | Event type. The value is **'batteryChange'**, which indicates the change in battery information of a remote Bluetooth device.  |
1041| callback | Callback&lt;[BatteryInfo](#batteryinfo12)&gt; | No   | Callback to unregister.|
1042
1043**Error codes**
1044
1045For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1046
1047| ID| Error Message|
1048| -------- | ---------------------------- |
1049|201 | Permission denied.                 |
1050|2900099 | Operation failed.                        |
1051
1052**Example**
1053
1054```js
1055import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1056let onReceiveEvent: (data: connection.BatteryInfo) => void = (data: connection.BatteryInfo) => {
1057    console.info('BatteryInfo = '+ JSON.stringify(data));
1058}
1059try {
1060    connection.on('batteryChange', onReceiveEvent);
1061    connection.off('batteryChange', onReceiveEvent);
1062} catch (err) {
1063    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1064}
1065```
1066
1067
1068## connection.on('bluetoothDeviceFind')
1069
1070on(type: 'bluetoothDeviceFind', callback: Callback&lt;Array&lt;string&gt;&gt;): void
1071
1072Subscribes to the discovery of a Bluetooth device. This API uses an asynchronous callback to return the result.
1073
1074**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1075
1076**Atomic service API**: This API can be used in atomic services since API version 12.
1077
1078**System capability**: SystemCapability.Communication.Bluetooth.Core
1079
1080**Parameters**
1081
1082| Name     | Type                                 | Mandatory  | Description                                    |
1083| -------- | ----------------------------------- | ---- | -------------------------------------- |
1084| type     | string                              | Yes   | Event type. The value is **bluetoothDeviceFind**, which indicates an event of discovering a Bluetooth device.|
1085| callback | Callback&lt;Array&lt;string&gt;&gt; | Yes   | Callback used to return the discovered devices. You need to implement this callback. For security purposes, the device addresses 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.   |
1086
1087**Error codes**
1088
1089For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1090
1091| ID| Error Message|
1092| -------- | ---------------------------- |
1093|201 | Permission denied.                 |
1094|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
1095|801 | Capability not supported.          |
1096|2900099 | Operation failed.                        |
1097
1098**Example**
1099
1100```js
1101import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1102function onReceiveEvent(data: Array<string>) { // data is an array of Bluetooth device addresses.
1103    console.info('bluetooth device find = '+ JSON.stringify(data));
1104}
1105try {
1106    connection.on('bluetoothDeviceFind', onReceiveEvent);
1107} catch (err) {
1108    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1109}
1110```
1111
1112
1113## connection.off('bluetoothDeviceFind')
1114
1115off(type: 'bluetoothDeviceFind', callback?: Callback&lt;Array&lt;string&gt;&gt;): void
1116
1117Unsubscribes from the discovery of a Bluetooth device.
1118
1119**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1120
1121**Atomic service API**: This API can be used in atomic services since API version 12.
1122
1123**System capability**: SystemCapability.Communication.Bluetooth.Core
1124
1125**Parameters**
1126
1127| Name     | Type                                 | Mandatory  | Description                                      |
1128| -------- | ----------------------------------- | ---- | ---------------------------------------- |
1129| type     | string                              | Yes   | Event type. The value is **bluetoothDeviceFind**, which indicates an event of discovering a Bluetooth device.  |
1130| callback | Callback&lt;Array&lt;string&gt;&gt; | No   | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.|
1131
1132**Error codes**
1133
1134For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1135
1136| ID| Error Message|
1137| -------- | ---------------------------- |
1138|201 | Permission denied.                 |
1139|801 | Capability not supported.          |
1140|2900099 | Operation failed.                        |
1141
1142**Example**
1143
1144```js
1145import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1146function onReceiveEvent(data: Array<string>) {
1147    console.info('bluetooth device find = '+ JSON.stringify(data));
1148}
1149try {
1150    connection.on('bluetoothDeviceFind', onReceiveEvent);
1151    connection.off('bluetoothDeviceFind', onReceiveEvent);
1152} catch (err) {
1153    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1154}
1155```
1156
1157
1158## connection.on('bondStateChange')
1159
1160on(type: 'bondStateChange', callback: Callback&lt;BondStateParam&gt;): void
1161
1162Subscribes to Bluetooth pairing state changes. This API uses an asynchronous callback to return the result.
1163
1164**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1165
1166**System capability**: SystemCapability.Communication.Bluetooth.Core
1167
1168**Parameters**
1169
1170| Name     | Type                                      | Mandatory  | Description                                  |
1171| -------- | ---------------------------------------- | ---- | ------------------------------------ |
1172| type     | string                                   | Yes   | Event type. The value is **bondStateChange**, which indicates a Bluetooth pairing state change event.|
1173| callback | Callback&lt;[BondStateParam](#bondstateparam)&gt; | Yes   | Callback used to return the pairing state. You need to implement this callback.   |
1174
1175**Error codes**
1176
1177For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1178
1179| ID| Error Message|
1180| -------- | ---------------------------- |
1181|201 | Permission denied.                 |
1182|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
1183|801 | Capability not supported.          |
1184|2900099 | Operation failed.                        |
1185
1186**Example**
1187
1188```js
1189import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1190function onReceiveEvent(data: connection.BondStateParam) { // data, as the input parameter of the callback, indicates the pairing state.
1191    console.info('pair state = '+ JSON.stringify(data));
1192}
1193try {
1194    connection.on('bondStateChange', onReceiveEvent);
1195} catch (err) {
1196    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1197}
1198```
1199
1200
1201## connection.off('bondStateChange')
1202
1203off(type: 'bondStateChange', callback?: Callback&lt;BondStateParam&gt;): void
1204
1205Unsubscribes from Bluetooth pairing state changes.
1206
1207**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1208
1209**System capability**: SystemCapability.Communication.Bluetooth.Core
1210
1211**Parameters**
1212
1213| Name     | Type                                      | Mandatory  | Description                                      |
1214| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
1215| type     | string                                   | Yes   | Event type. The value is **bondStateChange**, which indicates a Bluetooth pairing state change event.    |
1216| callback | Callback&lt;[BondStateParam](#bondstateparam)&gt; | No   | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for the specified **type**.|
1217
1218**Error codes**
1219
1220For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1221
1222| ID| Error Message|
1223| -------- | ---------------------------- |
1224|201 | Permission denied.                 |
1225|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
1226|801 | Capability not supported.          |
1227|2900099 | Operation failed.                        |
1228
1229**Example**
1230
1231```js
1232import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1233function onReceiveEvent(data: connection.BondStateParam) {
1234    console.info('bond state = '+ JSON.stringify(data));
1235}
1236try {
1237    connection.on('bondStateChange', onReceiveEvent);
1238    connection.off('bondStateChange', onReceiveEvent);
1239} catch (err) {
1240    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1241}
1242```
1243
1244
1245## connection.on('pinRequired')
1246
1247on(type: 'pinRequired', callback: Callback&lt;PinRequiredParam&gt;): void
1248
1249Subscribes to the pairing request events of the remote Bluetooth device. This API uses an asynchronous callback to return the result.
1250
1251**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1252
1253**System capability**: SystemCapability.Communication.Bluetooth.Core
1254
1255**Parameters**
1256
1257| Name     | Type                                      | Mandatory  | Description                              |
1258| -------- | ---------------------------------------- | ---- | -------------------------------- |
1259| type     | string                                   | Yes   | Event type. The value **pinRequired** indicates a pairing request event.    |
1260| callback | Callback&lt;[PinRequiredParam](#pinrequiredparam)&gt; | Yes   | Callback used to return the pairing request. You need to implement this callback.|
1261
1262**Error codes**
1263
1264For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1265
1266| ID| Error Message|
1267| -------- | ---------------------------- |
1268|201 | Permission denied.                 |
1269|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
1270|801 | Capability not supported.          |
1271|2900099 | Operation failed.                        |
1272
1273**Example**
1274
1275```js
1276import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1277function onReceiveEvent(data: connection.PinRequiredParam) { // data is the pairing request parameter.
1278    console.info('pin required = '+ JSON.stringify(data));
1279}
1280try {
1281    connection.on('pinRequired', onReceiveEvent);
1282} catch (err) {
1283    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1284}
1285```
1286
1287
1288## connection.off('pinRequired')
1289
1290off(type: 'pinRequired', callback?: Callback&lt;PinRequiredParam&gt;): void
1291
1292Unsubscribes from the pairing request events of the remote Bluetooth device.
1293
1294**Required permissions**: ohos.permission.ACCESS_BLUETOOTH
1295
1296**System capability**: SystemCapability.Communication.Bluetooth.Core
1297
1298**Parameters**
1299
1300| Name     | Type                                      | Mandatory  | Description                                      |
1301| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
1302| type     | string                                   | Yes   | Event type. The value **pinRequired** indicates a pairing request event.            |
1303| callback | Callback&lt;[PinRequiredParam](#pinrequiredparam)&gt; | No   | Callback to unregister. The input parameter is the pairing request parameter. If this parameter is not set, this API unregisters all callbacks for the specified **type**.|
1304
1305**Error codes**
1306
1307For details about the error codes, see [Bluetooth Error Codes](errorcode-bluetoothManager.md).
1308
1309| ID| Error Message|
1310| -------- | ---------------------------- |
1311|201 | Permission denied.                 |
1312|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
1313|801 | Capability not supported.          |
1314|2900099 | Operation failed.                        |
1315
1316**Example**
1317
1318```js
1319import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
1320function onReceiveEvent(data: connection.PinRequiredParam) {
1321    console.info('pin required = '+ JSON.stringify(data));
1322}
1323try {
1324    connection.on('pinRequired', onReceiveEvent);
1325    connection.off('pinRequired', onReceiveEvent);
1326} catch (err) {
1327    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
1328}
1329```
1330
1331
1332## BondStateParam
1333
1334Represents the pairing state parameters.
1335
1336**System capability**: SystemCapability.Communication.Bluetooth.Core
1337
1338| Name      | Type  | Readable  | Writable  | Description         |
1339| -------- | ------ | ---- | ---- | ----------- |
1340| deviceId | string      | Yes   | No   | ID of the device to pair.|
1341| state    | BondState   | Yes   | No   | State of the device.|
1342| cause<sup>12+</sup>| [UnbondCause](#unbondcause12) | Yes| No| Cause of the pairing failure.|
1343
1344
1345## PinRequiredParam
1346
1347Represents the pairing request parameters.
1348
1349**System capability**: SystemCapability.Communication.Bluetooth.Core
1350
1351| Name      | Type  | Readable  | Writable  | Description         |
1352| -------- | ------ | ---- | ---- | ----------- |
1353| deviceId | string | Yes   | No   | ID of the device to pair.|
1354| pinCode  | string | Yes   | No   | Key for the device pairing.  |
1355
1356
1357
1358## DeviceClass
1359
1360Represents the class of a Bluetooth device.
1361
1362**System capability**: SystemCapability.Communication.Bluetooth.Core
1363
1364| Name             | Type                               | Readable  | Writable  | Description              |
1365| --------------- | ----------------------------------- | ---- | ---- | ---------------- |
1366| majorClass      | [MajorClass](js-apis-bluetooth-constant.md#majorclass)           | Yes   | No   | Major class of the Bluetooth device.  |
1367| majorMinorClass | [MajorMinorClass](js-apis-bluetooth-constant.md#majorminorclass) | Yes   | No   | Major and minor classes of the Bluetooth device.|
1368| classOfDevice   | number                              | Yes   | No   | Class of the device.         |
1369
1370
1371## BatteryInfo<sup>12+</sup>
1372
1373Represents the battery information.
1374
1375**System capability**: SystemCapability.Communication.Bluetooth.Core
1376
1377| Name      | Type  | Readable  | Writable  | Description         |
1378| -------- | ------ | ---- | ---- | ----------- |
1379| batteryLevel  | number | Yes   | No   | Battery level of the remote device. If the value is **-1**, there is no battery information.  |
1380| leftEarBatteryLevel  | number | Yes   | No   | Battery level of the left earphone. If the value is **-1**, there is no battery information.  |
1381| leftEarChargeState  | [DeviceChargeState](#devicechargestate12) | Yes   | No   | Charging state of the left earphone.  |
1382| rightEarBatteryLevel  | number | Yes   | No   | Battery level of the right earphone. If the value is **-1**, there is no battery information.  |
1383| rightEarChargeState  | [DeviceChargeState](#devicechargestate12) | Yes   | No   | Charging state of the right earphone.  |
1384| boxBatteryLevel  | number | Yes   | No   | Battery level of the earbud compartment. If the value is **-1**, there is no battery information.  |
1385| boxChargeState  | [DeviceChargeState](#devicechargestate12) | Yes   | No   | Charging state of the earbud compartment.  |
1386
1387
1388## BluetoothTransport
1389
1390Enumerates the device types. The default device type is **TRANSPORT_BR_EDR**.
1391
1392**System capability**: SystemCapability.Communication.Bluetooth.Core
1393
1394| Name                              | Value   | Description             |
1395| -------------------------------- | ------ | --------------- |
1396| TRANSPORT_BR_EDR   | 0 | Classic Bluetooth (BR/EDR) device.|
1397| TRANSPORT_LE  | 1 | BLE device. |
1398
1399
1400## ScanMode
1401
1402Enumerates the scan modes.
1403
1404**System capability**: SystemCapability.Communication.Bluetooth.Core
1405
1406| Name                                      | Value | Description             |
1407| ---------------------------------------- | ---- | --------------- |
1408| SCAN_MODE_NONE                           | 0    | No scan mode.        |
1409| SCAN_MODE_CONNECTABLE                    | 1    | Connectable mode.       |
1410| SCAN_MODE_GENERAL_DISCOVERABLE           | 2    | General discoverable mode.   |
1411| SCAN_MODE_LIMITED_DISCOVERABLE           | 3    | Limited discoverable mode.   |
1412| SCAN_MODE_CONNECTABLE_GENERAL_DISCOVERABLE | 4    | General connectable and discoverable mode.|
1413| SCAN_MODE_CONNECTABLE_LIMITED_DISCOVERABLE | 5    | Limited connectable and discoverable mode.|
1414
1415
1416## BondState
1417
1418Enumerates the pairing states.
1419
1420**Atomic service API**: This API can be used in atomic services since API version 12.
1421
1422**System capability**: SystemCapability.Communication.Bluetooth.Core
1423
1424| Name                | Value | Description    |
1425| ------------------ | ---- | ------ |
1426| BOND_STATE_INVALID | 0    | Invalid pairing.|
1427| BOND_STATE_BONDING | 1    | Pairing. |
1428| BOND_STATE_BONDED  | 2    | Paired.  |
1429
1430
1431## UnbondCause<sup>12+</sup>
1432
1433Enumerates the possible causes of a pairing failure.
1434
1435**System capability**: SystemCapability.Communication.Bluetooth.Core
1436
1437| Name                | Value | Description    |
1438| ------------------ | ---- | ------ |
1439| USER_REMOVED        | 0    | The user proactively removes the device.|
1440| REMOTE_DEVICE_DOWN  | 1    | The remote device is shut down.|
1441| AUTH_FAILURE        | 2    | The PIN is incorrect.|
1442| AUTH_REJECTED       | 3    | The remote device authentication is rejected.|
1443| INTERNAL_ERROR      | 4    | Internal error.|
1444
1445
1446## DeviceChargeState<sup>12+</sup>
1447
1448Enumerates the charging states.
1449
1450**System capability**: SystemCapability.Communication.Bluetooth.Core
1451
1452| Name                | Value | Description    |
1453| ------------------ | ---- | ------ |
1454| DEVICE_NORMAL_CHARGE_NOT_CHARGED        | 0    | The device is not charged and does not support supercharging.|
1455| DEVICE_NORMAL_CHARGE_IN_CHARGING       | 1    | The device is being charged and does not support supercharging.|
1456| DEVICE_SUPER_CHARGE_NOT_CHARGED        | 2    | The device is not charged and supports supercharging.|
1457| DEVICE_SUPER_CHARGE_IN_CHARGING       | 3    | The device is being charged and supports supercharging.|
1458