目录

@ohos.bluetooth.access (蓝牙access模块)

本模块提供了打开和关闭蓝牙、获取蓝牙开关状态以及其他相关方法。

本模块首批接口从API version 10开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

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

access.enableBluetooth

enableBluetooth(): void

开启蓝牙。

需要权限:ohos.permission.ACCESS_BLUETOOTH

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

示例:

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>

开启蓝牙。使用Promise异步回调。

需要权限:ohos.permission.ACCESS_BLUETOOTH

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

返回值:

类型 说明
Promise<void> Promise对象,无返回结果。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900013 The user does not respond.
2900014 User refuse the action.
2900099 Operation failed.

示例:

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

关闭蓝牙。

需要权限:ohos.permission.ACCESS_BLUETOOTH

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

示例:

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>

关闭蓝牙。使用Promise异步回调。

需要权限:ohos.permission.ACCESS_BLUETOOTH

元服务API:从API version 20开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

返回值:

类型 说明
Promise<void> Promise对象,无返回结果。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900001 Service stopped.
2900013 The user does not respond.
2900014 User refuse the action.
2900099 Operation failed.

示例:

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

获取蓝牙开关状态。

需要权限:

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

返回值:

类型 说明
BluetoothState 表示蓝牙开关状态。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201

Permission denied.

适用版本:10-12

801 Capability not supported.
2900001 Service stopped.
2900099 Operation failed.

示例:

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

订阅本端蓝牙开关状态变化事件。使用Callback异步回调。从API18开始不再校验ohos.permission.ACCESS_BLUETOOTH权限。

需要权限:

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
type string 是

事件回调类型,支持的事件为'stateChange',表示蓝牙开关状态变化事件。

如:当调用access.enableBluetooth或access.disableBluetooth时,可触发该事件。

callback Callback<BluetoothState> 是 指定订阅的回调函数,会携带蓝牙开关状态。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201

Permission denied.

适用版本: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.

示例:

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

取消订阅本端蓝牙开关状态变化事件。从API18开始不再校验ohos.permission.ACCESS_BLUETOOTH权限。

需要权限:

元服务API:从API version 12开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
type string 是 事件回调类型,支持的事件为'stateChange',表示蓝牙开关状态变化事件。
callback Callback<BluetoothState> 否

指定取消订阅的回调函数通知。

若传参,则需与access.on('stateChange')中的回调函数一致;若无传参,则取消订阅该type对应的所有回调函数通知。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201

Permission denied.

适用版本: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.

示例:

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>

持久化存储蓝牙设备的虚拟MAC地址。使用Promise异步回调。

需要权限:ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

元服务API:从API version 16开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
deviceId string 是

对端设备的虚拟MAC地址,例如:"XX:XX:XX:XX:XX:XX"。

该地址一般来源于蓝牙扫描结果,如:可通过调用startScan或connection.startBluetoothDiscovery扫描得到。

返回值:

类型 说明
Promise<void> Promise对象,无返回结果。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
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.

示例:

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

let deviceId = '11:22:33:44:55:66'  // 该地址可通过BLE扫描获取
try {
    access.addPersistentDeviceId(deviceId);
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.deletePersistentDeviceId16+

deletePersistentDeviceId(deviceId: string): Promise<void>

删除已持久化存储的蓝牙虚拟MAC地址。使用Promise异步回调。

需要权限:ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

元服务API:从API version 16开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
deviceId string 是

对端设备的虚拟MAC地址,例如:"XX:XX:XX:XX:XX:XX",

该地址一般来源于蓝牙扫描结果,如:通过调用startScan或connection.startBluetoothDiscovery扫描得到。

返回值:

类型 说明
Promise<void> Promise对象,无返回结果。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
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.

示例:

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

let deviceId = '11:22:33:44:55:66'  // 该地址可通过BLE扫描获取
try {
    access.deletePersistentDeviceId(deviceId);
} catch (err) {
    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}

access.getPersistentDeviceIds16+

getPersistentDeviceIds(): string[];

获取应用持久化存储过的蓝牙虚拟MAC地址。

需要权限:ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC

元服务API:从API version 16开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

返回值:

类型 说明
string[] 持久化存储过的蓝牙虚拟MAC地址列表。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
201 Permission denied.
801 Capability not supported.
2900003 Bluetooth disabled.
2900099 Get persistent device address failed.

示例:

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;

判断对端蓝牙设备的虚拟MAC地址是否有效。

需要权限:ohos.permission.ACCESS_BLUETOOTH

元服务API:从API version 16开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
deviceId string 是 对端设备的虚拟MAC地址,例如:"XX:XX:XX:XX:XX:XX"。

返回值:

类型 说明
boolean 蓝牙设备的虚拟MAC地址是否是有效的。true表示有效地址,false表示无效地址。

错误码:

以下错误码的详细介绍请参见通用错误码说明文档和蓝牙服务子系统错误码。

错误码ID 错误信息
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.

示例:

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

try {
    let deviceId = '11:22:33:44:55:66'  // 该地址可通过BLE扫描获取
    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

将指定格式的UUID转换为128bit的UUID。

常用的UUID格式主要包括16bit、32bit和128bit三种格式。蓝牙协议定义的128bit格式的基准UUID为:00000000-0000-1000-8000-00805f9b34fb。若输入16bit或者32bit的UUID,将基于蓝牙基准UUID进行转换。若输入128bit的UUID,将不做转换直接输出该UUID。

系统能力:SystemCapability.Communication.Bluetooth.Core

参数:

参数名 类型 必填 说明
uuid string 是 16bit、32bit、128bit的UUID。

返回值:

类型 说明
string 转换后的128bit的UUID。

示例:

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

查询本机是否支持蓝牙能力。

起始版本:26.0.0

系统能力:SystemCapability.Communication.Bluetooth.Core

模型约束:此接口仅可在Stage模型下使用。

返回值:

类型 说明
boolean 查询本机是否支持蓝牙能力。true 表示本机支持蓝牙能力,false 表示本机不支持蓝牙能力。

错误码:

以下错误码的详细介绍请参见蓝牙服务子系统错误码。

错误码ID 错误信息
2900099 Operation failed.

示例:

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

BluetoothState

枚举,蓝牙开关状态。

元服务API:从API version 11开始,该接口支持在元服务中使用。

系统能力:SystemCapability.Communication.Bluetooth.Core

名称 值 说明
STATE_OFF 0 表示蓝牙已关闭。
STATE_TURNING_ON 1 表示蓝牙正在打开。
STATE_ON 2 表示蓝牙已打开。
STATE_TURNING_OFF 3 表示蓝牙正在关闭。
STATE_BLE_TURNING_ON 4 表示蓝牙正在打开LE-only模式。
STATE_BLE_ON 5 表示蓝牙正处于LE-only模式。
STATE_BLE_TURNING_OFF 6 表示蓝牙正在关闭LE-only模式。