• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.bluetooth.baseProfile (蓝牙baseProfile模块)
2
3<!--Kit: Connectivity Kit-->
4<!--Subsystem: Communication-->
5<!--Owner: @enjoy_sunshine-->
6<!--Designer: @chengguohong; @tangjia15-->
7<!--Tester: @wangfeng517-->
8<!--Adviser: @zhang_yixin13-->
9
10本模块提供不同的蓝牙技术协议的基础公共方法。
11
12> **说明：**
13>
14> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
15
16## 导入模块
17
18```js
19import { baseProfile } from '@kit.ConnectivityKit';
20```
21## BaseProfile
22
23基础Profile接口定义，提供订阅和获取连接状态等公共能力。如：[A2dpSourceProfile](js-apis-bluetooth-a2dp.md#a2dpsourceprofile)、[HandsFreeAudioGatewayProfile](js-apis-bluetooth-hfp.md#handsfreeaudiogatewayprofile)等[Profile](../../connectivity/terminology.md#profile)类型都继承于该类。
24
25## ProfileConnectionState
26
27type ProfileConnectionState = constant.ProfileConnectionState
28
29本端和对端蓝牙设备间的Profile连接状态。
30
31**系统能力**：SystemCapability.Communication.Bluetooth.Core
32
33| 类型                  | 说明                  |
34| ------------------- | ------------------- |
35| [constant.ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 本端和对端蓝牙设备间的Profile连接状态。 |
36
37## StateChangeParam
38
39本端和对端蓝牙设备间Profile连接状态变化参数。
40
41**系统能力**：SystemCapability.Communication.Bluetooth.Core
42
43| 名称     | 类型                           | 只读 | 可选 | 说明                            |
44| -------- | ----------------------------- | ---- | ---- | ------------------------------- |
45| deviceId | string                        | 否   | 否   | 对端设备地址，例如："XX:XX:XX:XX:XX:XX"。   |
46| state    | [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate)        | 否   | 否   | Profile连接状态。 |
47| cause<sup>12+</sup>| [DisconnectCause](#disconnectcause12) | 否 | 否 | Profile断开连接的原因。|
48
49## DisconnectCause<sup>12+</sup>
50
51枚举，Profile断开连接的原因。
52
53**系统能力**：SystemCapability.Communication.Bluetooth.Core
54
55| 名称                 | 值  | 说明     |
56| ------------------ | ---- | ------ |
57| USER_DISCONNECT            | 0    | 用户主动断开连接。|
58| CONNECT_FROM_KEYBOARD      | 1    | 连接请求需从键盘侧发起。|
59| CONNECT_FROM_MOUSE         | 2    | 连接请求需从鼠标侧发起。|
60| CONNECT_FROM_CAR           | 3    | 连接请求需从车机侧发起。|
61| TOO_MANY_CONNECTED_DEVICES | 4    | 当前连接数量超过上限。|
62| CONNECT_FAIL_INTERNAL      | 5    | 内部错误。|
63
64## BaseProfile.getConnectedDevices
65
66getConnectedDevices(): Array&lt;string&gt;
67
68获取和本端设备间已连接Profile的对端设备列表。
69
70**需要权限**：ohos.permission.ACCESS_BLUETOOTH
71
72**系统能力**：SystemCapability.Communication.Bluetooth.Core
73
74**返回值：**
75
76| 类型                  | 说明                  |
77| ------------------- | ------------------- |
78| Array&lt;string&gt; | 返回已连接Profile的对端设备列表。<br>基于信息安全考虑，此处获取的设备地址为虚拟MAC地址。<br>- 已配对的地址不会变更。<br>- 若取消配对该设备或蓝牙关闭后，再次重新获取，该虚拟地址会变更。<br>- 若要持久化保存该地址，可使用[access.addPersistentDeviceId](js-apis-bluetooth-access.md#accessaddpersistentdeviceid16)方法。 |
79
80**错误码**：
81
82以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
83
84| 错误码ID | 错误信息 |
85| -------- | ---------------------------- |
86|201 | Permission denied.                 |
87|801 | Capability not supported.          |
88|2900001 | Service stopped.                         |
89|2900003 | Bluetooth disabled.                 |
90|2900004 | Profile not supported.                |
91|2900099 | Operation failed.                        |
92
93**示例：**
94
95```js
96import { BusinessError } from '@kit.BasicServicesKit';
97import { a2dp } from '@kit.ConnectivityKit';
98
99try {
100    let a2dpSrc = a2dp.createA2dpSrcProfile(); // 以a2dp举例
101    let retArray = a2dpSrc.getConnectedDevices();
102} catch (err) {
103    console.error("errCode:" + (err as BusinessError).code + ",errMessage:" + (err as BusinessError).message);
104}
105```
106
107## BaseProfile.getConnectionState
108
109getConnectionState(deviceId: string): ProfileConnectionState
110
111获取和对端设备间Profile的连接状态。
112
113**需要权限**：ohos.permission.ACCESS_BLUETOOTH
114
115**系统能力**：SystemCapability.Communication.Bluetooth.Core
116
117**参数：**
118
119| 参数名    | 类型     | 必填   | 说明      |
120| ------ | ------ | ---- | ------- |
121| deviceId | string | 是    | 对端设备地址，例如："XX:XX:XX:XX:XX:XX"。 |
122
123**返回值：**
124
125| 类型                                              | 说明                    |
126| ------------------------------------------------- | ----------------------- |
127| [ProfileConnectionState](js-apis-bluetooth-constant.md#profileconnectionstate) | 返回Profile的连接状态。 |
128
129**错误码**：
130
131以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
132
133| 错误码ID | 错误信息 |
134| -------- | ---------------------------- |
135|201 | Permission denied.                 |
136|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
137|801 | Capability not supported.          |
138|2900001 | Service stopped.                         |
139|2900003 | Bluetooth disabled.                 |
140|2900004 | Profile not supported.                |
141|2900099 | Operation failed.                        |
142
143**示例：**
144
145```js
146import { BusinessError } from '@kit.BasicServicesKit';
147import { a2dp } from '@kit.ConnectivityKit';
148
149try {
150    let a2dpSrc = a2dp.createA2dpSrcProfile(); // 以a2dp举例
151    let ret = a2dpSrc.getConnectionState('XX:XX:XX:XX:XX:XX');
152} catch (err) {
153    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
154}
155```
156
157## BaseProfile.on('connectionStateChange')
158
159on(type: 'connectionStateChange', callback: Callback&lt;StateChangeParam&gt;): void
160
161订阅Profile的连接状态变化事件。使用Callback异步回调。
162
163**需要权限**：ohos.permission.ACCESS_BLUETOOTH
164
165**系统能力**：SystemCapability.Communication.Bluetooth.Core
166
167**参数：**
168
169| 参数名      | 类型                                       | 必填   | 说明                                       |
170| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
171| type     | string                                   | 是    | 事件回调类型，支持的事件为'connectionStateChange'，表示Profile连接状态变化事件。<br>当Profile连接状态变化时，触发该事件。 |
172| callback | Callback&lt;[StateChangeParam](#statechangeparam)&gt; | 是    | 指定订阅的回调函数，会携带Profile连接状态。                        |
173
174**错误码**：
175
176以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
177
178| 错误码ID | 错误信息 |
179| -------- | ---------------------------- |
180|201 | Permission denied.                 |
181|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
182|801 | Capability not supported.          |
183
184**示例：**
185
186```js
187import { BusinessError } from '@kit.BasicServicesKit';
188import { a2dp } from '@kit.ConnectivityKit';
189
190function onReceiveEvent(data: baseProfile.StateChangeParam) {
191    console.info('a2dp state = '+ JSON.stringify(data));
192}
193try {
194    let a2dpSrc = a2dp.createA2dpSrcProfile(); // 以a2dp举例
195    a2dpSrc.on('connectionStateChange', onReceiveEvent);
196} catch (err) {
197    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
198}
199```
200
201## BaseProfile.off('connectionStateChange')
202
203off(type: 'connectionStateChange', callback?: Callback&lt;[StateChangeParam](#statechangeparam)&gt;): void
204
205取消订阅Profile的连接状态变化事件。
206
207**需要权限**：ohos.permission.ACCESS_BLUETOOTH
208
209**系统能力**：SystemCapability.Communication.Bluetooth.Core
210
211**参数：**
212
213| 参数名      | 类型                                       | 必填   | 说明                                       |
214| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
215| type     | string                                   | 是    | 事件回调类型，支持的事件为'connectionStateChange'，表示Profile连接状态变化事件。 |
216| callback | Callback&lt;[StateChangeParam](#statechangeparam)&gt; | 否    | 指定取消订阅的回调函数通知。<br>若传参，则需与[BaseProfile.on('connectionStateChange')](#baseprofileonconnectionstatechange)中的回调函数一致；若无传参，则取消订阅该type对应的所有回调函数通知。                               |
217
218**错误码**：
219
220以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
221
222| 错误码ID | 错误信息 |
223| -------- | ---------------------------- |
224|201 | Permission denied.                 |
225|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
226|801 | Capability not supported.          |
227
228**示例：**
229
230```js
231import { BusinessError } from '@kit.BasicServicesKit';
232import { a2dp } from '@kit.ConnectivityKit';
233
234function onReceiveEvent(data: baseProfile.StateChangeParam) {
235    console.info('a2dp state = '+ JSON.stringify(data));
236}
237try {
238    let a2dpSrc = a2dp.createA2dpSrcProfile(); // 以a2dp举例
239    a2dpSrc.on('connectionStateChange', onReceiveEvent);
240    a2dpSrc.off('connectionStateChange', onReceiveEvent);
241} catch (err) {
242    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
243}
244```