目录

@ohos.bluetooth.access (Bluetooth Access Module)

The access module provides APIs for enabling and disabling Bluetooth and obtaining the Bluetooth status.

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.

Modules to Import

import { access } from '@kit.ConnectivityKit';

access.enableBluetooth

enableBluetooth(): void

Enables Bluetooth.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    access.enableBluetooth();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.enableBluetoothAsync20+

enableBluetoothAsync(): Promise<void>

Enables Bluetooth. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900013 The user does not respond.
2900014 User refuse the action.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    access.enableBluetoothAsync().then(() => {
        console.info('enableBluetoothAsync');
    }, (error: BusinessError) => {
        console.error('enableBluetoothAsync: errCode:' + error.code + ',errMessage' + error.message);
    })
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.disableBluetooth

disableBluetooth(): void

Disables Bluetooth.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    access.disableBluetooth();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.disableBluetoothAsync20+

disableBluetoothAsync(): Promise<void>

Disables Bluetooth. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900013 The user does not respond.
2900014 User refuse the action.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    access.disableBluetoothAsync().then(() => {
        console.info('disableBluetoothAsync');
    }, (error: BusinessError) => {
        console.error('disableBluetoothAsync: errCode:' + error.code + ',errMessage' + error.message);
    })
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.getState

getState(): BluetoothState

Obtains the Bluetooth state.

Required permissions:

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Type Description
BluetoothState Bluetooth state obtained.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 10–12
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    let state = access.getState();
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.on('stateChange')

on(type: 'stateChange', callback: Callback<BluetoothState>): void

Enables listening for Bluetooth status change events of the local device. This API uses an asynchronous callback to return the result. Since API version 18, the ohos.permission.ACCESS_BLUETOOTH permission is no longer verified.

Required permissions:

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
type string Yes

Event type. The value stateChange indicates a Bluetooth status change event.

For example, this event is triggered when access.enableBluetooth or access.disableBluetooth is called.
callback Callback<BluetoothState> Yes Callback used to return the Bluetooth switch status.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 10–17
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function onReceiveEvent(data: access.BluetoothState) {
    console.info('bluetooth state = '+ JSON.stringify(data));
}
try {
    access.on('stateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.off('stateChange')

off(type: 'stateChange', callback?: Callback<BluetoothState>): void

Disables listening for Bluetooth status change events of the local device. Since API version 18, the ohos.permission.ACCESS_BLUETOOTH permission is no longer verified.

Required permissions:

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
type string Yes Event type. The value stateChange indicates a Bluetooth status change event.
callback Callback<BluetoothState> No

Callback to unregister.

If this parameter is specified, it must be the same as the callback in access.on('stateChange'). If this parameter is not specified, all callbacks corresponding to the event type are unregistered.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201

Permission denied.

Applicable versions: 10–17
401 Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900099 Operation failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

function onReceiveEvent(data: access.BluetoothState) {
    console.info('bluetooth state = '+ JSON.stringify(data));
}
try {
    access.on('stateChange', onReceiveEvent);
    access.off('stateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.addPersistentDeviceId16+

addPersistentDeviceId(deviceId: string): Promise<void>

Stores the virtual MAC address of a Bluetooth device persistently. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
deviceId string Yes

Virtual MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.

This address is typically obtained from Bluetooth scan results, which can be retrieved, for example, by calling startScan or connection.startBluetoothDiscovery.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900003 Bluetooth disabled.
2900010 The number of supported device addresses has reached the upper limit.
2900099 Add persistent device address failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let deviceId = '11:22:33:44:55:66' // The address can be obtained through BLE scanning.
try {
    access.addPersistentDeviceId(deviceId);
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.deletePersistentDeviceId16+

deletePersistentDeviceId(deviceId: string): Promise<void>

Deletes the persistently stored virtual MAC address of a Bluetooth device. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
deviceId string Yes

Virtual MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.

This address is typically obtained from Bluetooth scan results, which can be retrieved, for example, by calling startScan or connection.startBluetoothDiscovery.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900003 Bluetooth disabled.
2900099 delete persistent device address failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let deviceId = '11:22:33:44:55:66' // The address can be obtained through BLE scanning.
try {
    access.deletePersistentDeviceId(deviceId);
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.getPersistentDeviceIds16+

getPersistentDeviceIds(): string[];

Obtains the persistently stored virtual MAC address of a Bluetooth device.

Required permissions: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.Communication.Bluetooth.Core

Return value

Type Description
string[] List of persistently stored virtual MAC addresses.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
801 Capability not supported.
2900003 Bluetooth disabled.
2900099 Get persistent device address failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    let deviceIds = access.getPersistentDeviceIds();
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.isValidRandomDeviceId16+

isValidRandomDeviceId(deviceId: string): boolean;

Checks whether the virtual MAC address of the peer device is valid.

Required permissions: ohos.permission.ACCESS_BLUETOOTH

Atomic service API: This API can be used in atomic services since API version 16.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
deviceId string Yes Virtual MAC address of the peer device, for example, XX:XX:XX:XX:XX:XX.

Return value

Type Description
boolean Whether the virtual MAC address of the Bluetooth device is valid. The value true indicates that the MAC address is valid, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes and Bluetooth Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801 Capability not supported.
2900003 Bluetooth disabled.
2900099 Check persistent device address failed.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    let deviceId = '11:22:33:44:55:66' // The address can be obtained through BLE scanning.
    let isValid = access.isValidRandomDeviceId(deviceId);
    console.info("isValid: " + isValid);
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.convertUuid22+

convertUuid(uuid: string): string

Converts the UUID of a specified format to a 128-bit UUID.

The common UUID formats include 16-bit, 32-bit, and 128-bit UUIDs. The 128-bit UUID defined by the Bluetooth protocol is 00000000-0000-1000-8000-00805f9b34fb. If a 16-bit or 32-bit UUID is entered, the UUID is converted based on the Bluetooth UUID. If a 128-bit UUID is entered, the UUID is output without conversion.

System capability: SystemCapability.Communication.Bluetooth.Core

Parameters

Name Type Mandatory Description
uuid string Yes 16-bit, 32-bit, or 128-bit UUID.

Return value

Type Description
string 128-bit UUID after conversion.

Example

import { BusinessError } from '@kit.BasicServicesKit';

try {
    let inputUuid: string = '1801';
    let convertedUuid: string = access.convertUuid(inputUuid);
    console.info("convertedUuid: " + convertedUuid);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

access.isBluetoothSupported

isBluetoothSupported(): boolean

Check whether a device supports Bluetooth.

Since: 26.0.0

System capability: SystemCapability.Communication.Bluetooth.Core

Model restriction: This API can be used only in the stage model.

Return value

Type Description
boolean Whether a device supports Bluetooth. The value true indicates that the device supports Bluetooth, and the value false indicates the opposite.

Error codes

For details about the error codes, see Bluetooth Error Codes.

ID Error Message
2900099 Operation failed.

Example

try {
    let isSupported: boolean = access.isBluetoothSupported();
    console.info("isSupported: " + isSupported);
} catch (err) {
    console.error(`errCode: ${err.code}, errMessage: ${err.message}`);
}

BluetoothState

Enumerates the Bluetooth states.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Communication.Bluetooth.Core

Name Value Description
STATE_OFF 0 Bluetooth is turned off.
STATE_TURNING_ON 1 Bluetooth is being turned on.
STATE_ON 2 Bluetooth is turned on.
STATE_TURNING_OFF 3 Bluetooth is being turned off.
STATE_BLE_TURNING_ON 4 The LE-only mode is being turned on for Bluetooth.
STATE_BLE_ON 5 Bluetooth is in LE-only mode.
STATE_BLE_TURNING_OFF 6 The LE-only mode is being turned off for Bluetooth.