本模块提供了打开和关闭蓝牙、获取蓝牙开关状态以及其他相关方法。
本模块首批接口从API version 10开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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);
} 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}`);
} 枚举,蓝牙开关状态。
元服务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模式。 |