1# @ohos.bluetooth.access (蓝牙access模块)
2
3access模块提供了打开和关闭蓝牙、获取蓝牙状态的方法。
4
5> **说明：**
6>
7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8
9
10## 导入模块
11
12```js
13import { access } from '@kit.ConnectivityKit';
14```
15
16
17## access.enableBluetooth
18
19enableBluetooth(): void
20
21开启蓝牙。
22
23**需要权限**：ohos.permission.ACCESS_BLUETOOTH
24
25**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。
26
27**系统能力**：SystemCapability.Communication.Bluetooth.Core。
28
29**错误码**：
30
31以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
32
33| 错误码ID | 错误信息            |
34| -------- | ------------------ |
35|201 | Permission denied.                 |
36|801 | Capability not supported.          |
37|2900001   | Service stopped.   |
38|2900099   | Operation failed.  |
39
40**示例：**
41
42```js
43import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
44try {
45    access.enableBluetooth();
46} catch (err) {
47    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
48}
49```
50
51
52## access.disableBluetooth
53
54disableBluetooth(): void
55
56关闭蓝牙。
57
58**需要权限**：ohos.permission.ACCESS_BLUETOOTH
59
60**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。
61
62**系统能力**：SystemCapability.Communication.Bluetooth.Core。
63
64**错误码**：
65
66以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
67
68|错误码ID   | 错误信息           |
69| -------- | ------------------ |
70|201 | Permission denied.                 |
71|801 | Capability not supported.          |
72|2900001   | Service stopped.   |
73|2900099   | Operation failed.  |
74
75**示例：**
76
77```js
78import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
79try {
80    access.disableBluetooth();
81} catch (err) {
82    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
83}
84```
85
86
87## access.getState
88
89getState(): BluetoothState
90
91获取蓝牙开关状态。
92
93**需要权限**：ohos.permission.ACCESS_BLUETOOTH
94
95**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。
96
97**系统能力**：SystemCapability.Communication.Bluetooth.Core。
98
99**返回值：**
100
101| 类型                              | 说明              |
102| --------------------------------- | ---------------- |
103| [BluetoothState](#bluetoothstate) | 表示蓝牙开关状态。 |
104
105**错误码**：
106
107以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
108
109|错误码ID   | 错误信息           |
110| -------- | ------------------ |
111|201 | Permission denied.                 |
112|801 | Capability not supported.          |
113|2900001   | Service stopped.   |
114|2900099   | Operation failed.  |
115
116**示例：**
117
118```js
119import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
120try {
121    let state = access.getState();
122} catch (err) {
123    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
124}
125```
126
127## access.on('stateChange')<a name="stateChange"></a>
128
129on(type: 'stateChange', callback: Callback&lt;BluetoothState&gt;): void
130
131订阅蓝牙设备开关状态事件。使用Callback异步回调。
132
133**需要权限**：ohos.permission.ACCESS_BLUETOOTH
134
135**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。
136
137**系统能力**：SystemCapability.Communication.Bluetooth.Core。
138
139**参数：**
140
141| 参数名   | 类型                                               | 必填  | 说明                                                       |
142| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- |
143| type     | string                                            | 是    | 填写"stateChange"字符串，表示蓝牙状态改变事件。               |
144| callback | Callback&lt;[BluetoothState](#bluetoothstate)&gt; | 是    | 表示回调函数的入参，蓝牙状态。回调函数由用户创建通过该接口注册。 |
145
146**错误码**：
147
148以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
149
150|错误码ID   | 错误信息           |
151| -------- | ------------------ |
152|201 | Permission denied.                 |
153|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
154|801 | Capability not supported.          |
155|2900099   | Operation failed.  |
156
157**示例：**
158
159```js
160import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
161function onReceiveEvent(data: access.BluetoothState) {
162    console.info('bluetooth state = '+ JSON.stringify(data));
163}
164try {
165    access.on('stateChange', onReceiveEvent);
166} catch (err) {
167    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
168}
169```
170
171
172## access.off('stateChange')
173
174off(type: 'stateChange', callback?: Callback&lt;BluetoothState&gt;): void
175
176取消订阅蓝牙设备开关状态事件。
177
178**需要权限**：ohos.permission.ACCESS_BLUETOOTH
179
180**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。
181
182**系统能力**：SystemCapability.Communication.Bluetooth.Core。
183
184**参数：**
185
186| 参数名      | 类型                                       | 必填   | 说明                                       |
187| -------- | ---------------------------------------- | ---- | ---------------------------------------- |
188| type     | string                                   | 是    | 填写"stateChange"字符串，表示蓝牙状态改变事件。           |
189| callback | Callback&lt;[BluetoothState](#bluetoothstate)&gt; | 否    | 表示取消订阅蓝牙状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 |
190
191**错误码**：
192
193以下错误码的详细介绍请参见[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。
194
195| 错误码ID | 错误信息 |
196| -------- | ---------------------------- |
197|201 | Permission denied.                 |
198|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.                 |
199|801 | Capability not supported.          |
200|2900099 | Operation failed.                        |
201
202**示例：**
203
204```js
205import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit';
206function onReceiveEvent(data: access.BluetoothState) {
207    console.info('bluetooth state = '+ JSON.stringify(data));
208}
209try {
210    access.on('stateChange', onReceiveEvent);
211    access.off('stateChange', onReceiveEvent);
212} catch (err) {
213    console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message);
214}
215```
216
217
218## BluetoothState
219
220枚举，蓝牙开关状态。
221
222**原子化服务API**: 从API version 11开始，该接口支持在原子化服务中使用。
223
224**系统能力**：SystemCapability.Communication.Bluetooth.Core。
225
226| 名称                    | 值  | 说明                 |
227| --------------------- | ---- | ------------------ |
228| STATE_OFF             | 0    | 表示蓝牙已关闭。          |
229| STATE_TURNING_ON      | 1    | 表示蓝牙正在打开。          |
230| STATE_ON              | 2    | 表示蓝牙已打开。           |
231| STATE_TURNING_OFF     | 3    | 表示蓝牙正在关闭。          |
232| STATE_BLE_TURNING_ON  | 4    | 表示蓝牙正在打开LE-only模式。 |
233| STATE_BLE_ON          | 5    | 表示蓝牙正处于LE-only模式。  |
234| STATE_BLE_TURNING_OFF | 6    | 表示蓝牙正在关闭LE-only模式。 |
235
236