harmony 鸿蒙@ohos.bluetooth.baseProfile (蓝牙baseProfile模块)

2025-06-12
浏览 (3)

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

baseProfile模块提供了基础的profile方法。

说明：

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

导入模块

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

ProfileConnectionState

type ProfileConnectionState = constant.ProfileConnectionState

蓝牙设备的profile连接状态。

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

类型	说明
constant.ProfileConnectionState	蓝牙设备的profile连接状态。

StateChangeParam

描述profile状态改变参数。

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

名称	类型	只读	可选	说明
deviceId	string	否	否	表示蓝牙设备地址。
state	ProfileConnectionState	否	否	表示蓝牙设备的profile连接状态。
cause¹²⁺	DisconnectCause	否	否	表示连接失败的原因。

DisconnectCause¹²⁺

枚举，连接失败原因。

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

名称	值	说明
USER_DISCONNECT	0	用户主动断开连接。
CONNECT_FROM_KEYBOARD	1	应该从键盘侧发起连接。
CONNECT_FROM_MOUSE	2	应该从鼠标侧发起连接。
CONNECT_FROM_CAR	3	应该从车机侧发起连接。
TOO_MANY_CONNECTED_DEVICES	4	当前连接数超过上限。
CONNECT_FAIL_INTERNAL	5	内部错误。

BaseProfile.getConnectedDevices

getConnectedDevices(): Array<string>

获取已连接设备列表。

需要权限：ohos.permission.ACCESS_BLUETOOTH

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

返回值：

类型	说明
Array<string>	返回当前已连接设备的地址。基于信息安全考虑，此处获取的设备地址为随机MAC地址。配对成功后，该地址不会变更。已配对设备取消配对后重新扫描或蓝牙服务下电时，该随机地址会变更。

错误码：

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

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

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
import { a2dp } from '@kit.ConnectivityKit';
try {
    let a2dpSrc = a2dp.createA2dpSrcProfile();
    let retArray = a2dpSrc.getConnectedDevices();
} catch (err) {
    console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
}

BaseProfile.getConnectionState

getConnectionState(deviceId: string): ProfileConnectionState

获取设备profile的连接状态。

需要权限：ohos.permission.ACCESS_BLUETOOTH

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

参数：

参数名	类型	必填	说明
deviceId	string	是	远端设备地址。

返回值：

类型	说明
ProfileConnectionState	返回profile的连接状态。

错误码：

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

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.
2900001	Service stopped.
2900003	Bluetooth disabled.
2900004	Profile not supported.
2900099	Operation failed.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
import { a2dp } from '@kit.ConnectivityKit';
try {
    let a2dpSrc = a2dp.createA2dpSrcProfile();
    let ret = a2dpSrc.getConnectionState('XX:XX:XX:XX:XX:XX');
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

BaseProfile.on(‘connectionStateChange’)

on(type: ‘connectionStateChange’, callback: Callback<StateChangeParam>): void

订阅连接状态变化事件。使用Callback异步回调。

需要权限：ohos.permission.ACCESS_BLUETOOTH

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

参数：

参数名	类型	必填	说明
type	string	是	填写”connectionStateChange”字符串，表示连接状态变化事件。
callback	Callback<StateChangeParam>	是	表示回调函数的入参。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
import { a2dp } from '@kit.ConnectivityKit';
function onReceiveEvent(data: baseProfile.StateChangeParam) {
    console.info('a2dp state = '+ JSON.stringify(data));
}
try {
    let a2dpSrc = a2dp.createA2dpSrcProfile();
    a2dpSrc.on('connectionStateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}

BaseProfile.off(‘connectionStateChange’)

off(type: ‘connectionStateChange’, callback?: Callback<StateChangeParam>): void

取消订阅连接状态变化事件。

需要权限：ohos.permission.ACCESS_BLUETOOTH

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

参数：

参数名	类型	必填	说明
type	string	是	填写”connectionStateChange”字符串，表示连接状态变化事件。
callback	Callback<StateChangeParam>	否	表示回调函数的入参。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

错误码ID	错误信息
201	Permission denied.
401	Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801	Capability not supported.

示例：

import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
import { a2dp } from '@kit.ConnectivityKit';
function onReceiveEvent(data: baseProfile.StateChangeParam) {
    console.info('a2dp state = '+ JSON.stringify(data));
}
try {
    let a2dpSrc = a2dp.createA2dpSrcProfile();
    a2dpSrc.on('connectionStateChange', onReceiveEvent);
    a2dpSrc.off('connectionStateChange', onReceiveEvent);
} catch (err) {
    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
}