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-universal.md)和[蓝牙服务子系统错误码](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-universal.md)和[蓝牙服务子系统错误码](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**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 94 95**系统能力**：SystemCapability.Communication.Bluetooth.Core 96 97**返回值：** 98 99| 类型 | 说明 | 100| --------------------------------- | ---------------- | 101| [BluetoothState](#bluetoothstate) | 表示蓝牙开关状态。 | 102 103**错误码**： 104 105以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 106 107|错误码ID | 错误信息 | 108| -------- | ------------------ | 109|801 | Capability not supported. | 110|2900001 | Service stopped. | 111|2900099 | Operation failed. | 112 113**示例：** 114 115```js 116import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 117try { 118 let state = access.getState(); 119} catch (err) { 120 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 121} 122``` 123 124## access.on('stateChange')<a name="stateChange"></a> 125 126on(type: 'stateChange', callback: Callback<BluetoothState>): void 127 128订阅蓝牙设备开关状态事件。使用Callback异步回调。 129 130**需要权限**：ohos.permission.ACCESS_BLUETOOTH 131 132**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 133 134**系统能力**：SystemCapability.Communication.Bluetooth.Core 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- | 140| type | string | 是 | 填写"stateChange"字符串，表示蓝牙状态改变事件。 | 141| callback | Callback<[BluetoothState](#bluetoothstate)> | 是 | 表示回调函数的入参，蓝牙状态。回调函数由用户创建并通过该接口注册。 | 142 143**错误码**： 144 145以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 146 147|错误码ID | 错误信息 | 148| -------- | ------------------ | 149|201 | Permission denied. | 150|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 151|801 | Capability not supported. | 152|2900099 | Operation failed. | 153 154**示例：** 155 156```js 157import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 158function onReceiveEvent(data: access.BluetoothState) { 159 console.info('bluetooth state = '+ JSON.stringify(data)); 160} 161try { 162 access.on('stateChange', onReceiveEvent); 163} catch (err) { 164 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 165} 166``` 167 168 169## access.off('stateChange') 170 171off(type: 'stateChange', callback?: Callback<BluetoothState>): void 172 173取消订阅蓝牙设备开关状态事件。 174 175**需要权限**：ohos.permission.ACCESS_BLUETOOTH 176 177**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 178 179**系统能力**：SystemCapability.Communication.Bluetooth.Core 180 181**参数：** 182 183| 参数名 | 类型 | 必填 | 说明 | 184| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 185| type | string | 是 | 填写"stateChange"字符串，表示蓝牙状态改变事件。 | 186| callback | Callback<[BluetoothState](#bluetoothstate)> | 否 | 表示取消订阅蓝牙状态改变事件上报。不填该参数则取消订阅该type对应的所有回调。 | 187 188**错误码**： 189 190以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 191 192| 错误码ID | 错误信息 | 193| -------- | ---------------------------- | 194|201 | Permission denied. | 195|401 | Invalid parameter. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 196|801 | Capability not supported. | 197|2900099 | Operation failed. | 198 199**示例：** 200 201```js 202import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 203function onReceiveEvent(data: access.BluetoothState) { 204 console.info('bluetooth state = '+ JSON.stringify(data)); 205} 206try { 207 access.on('stateChange', onReceiveEvent); 208 access.off('stateChange', onReceiveEvent); 209} catch (err) { 210 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 211} 212``` 213 214## access.addPersistentDeviceId<sup>16+</sup> 215 216addPersistentDeviceId(deviceId: string): Promise<void> 217 218应用通过蓝牙扫描获取得到的设备地址是虚拟随机的，若应用想长期使用该虚拟随机地址，需要调用该接口持久化存储虚拟随机地址。 219 220需注意，使用该接口时，开发者应明确该虚拟随机地址对应的对端蓝牙设备真实地址是不变的，若对端设备地址发生变化，持久化保存的地址信息也会失效，无法继续使用。 221 222**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 223 224**原子化服务API**：从API version 16开始，该接口支持在原子化服务中使用。 225 226**系统能力**：SystemCapability.Communication.Bluetooth.Core 227 228**参数：** 229 230| 参数名 | 类型 | 必填 | 说明 | 231| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 232| deviceId | string | 是 | 表示远程设备的虚拟地址，例如："XX:XX:XX:XX:XX:XX"，该地址一般来源于蓝牙扫描结果。 | 233 234**错误码**： 235 236以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 237 238| 错误码ID | 错误信息 | 239| -------- | ---------------------------- | 240|201 | Permission denied. | 241|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 242|801 | Capability not supported. | 243|2900003 | Bluetooth disabled. | 244|2900010 | The number of supported device addresses has reached the upper limit. | 245|2900099 | Add persistent device address failed. | 246 247**示例：** 248 249```js 250import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 251import { access } from '@kit.ConnectivityKit'; 252 253let deviceId = '11:22:33:44:55:66' // 该地址可通过BLE扫描获取 254try { 255 access.addPersistentDeviceId(deviceId); 256} catch (err) { 257 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 258} 259``` 260 261## access.deletePersistentDeviceId<sup>16+</sup> 262 263deletePersistentDeviceId(deviceId: string): Promise<void> 264 265删除一个持久化的蓝牙虚拟设备地址。 266 267 268**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 269 270**原子化服务API**：从API version 16开始，该接口支持在原子化服务中使用。 271 272**系统能力**：SystemCapability.Communication.Bluetooth.Core 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 278| deviceId | string | 是 | 表示远程设备的虚拟地址，例如："XX:XX:XX:XX:XX:XX"，该地址一般来源于蓝牙扫描结果。 | 279 280**错误码**： 281 282以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 283 284| 错误码ID | 错误信息 | 285| -------- | ---------------------------- | 286|201 | Permission denied. | 287|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 288|801 | Capability not supported. | 289|2900003 | Bluetooth disabled. | 290|2900099 | delete persistent device address failed. | 291 292**示例：** 293 294```js 295import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 296import { access } from '@kit.ConnectivityKit'; 297 298let deviceId = '11:22:33:44:55:66' // 该地址可通过BLE扫描获取 299try { 300 access.deletePersistentDeviceId(deviceId); 301} catch (err) { 302 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 303} 304``` 305 306## access.getPersistentDeviceIds<sup>16+</sup> 307 308getPersistentDeviceIds(): string[]; 309 310获取该应用持久化过的蓝牙虚拟设备地址。 311 312 313**需要权限**：ohos.permission.ACCESS_BLUETOOTH 和 ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 314 315**原子化服务API**：从API version 16开始，该接口支持在原子化服务中使用。 316 317**系统能力**：SystemCapability.Communication.Bluetooth.Core 318 319**返回值：** 320 321| 类型 | 说明 | 322| --------------------------------- | ---------------- | 323| string[] | 表示该应用持久化过的蓝牙虚拟设备地址列表。 | 324 325**错误码**： 326 327以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 328 329| 错误码ID | 错误信息 | 330| -------- | ---------------------------- | 331|201 | Permission denied. | 332|801 | Capability not supported. | 333|2900003 | Bluetooth disabled. | 334|2900099 | Get persistent device address failed. | 335 336**示例：** 337 338```js 339import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 340import { access } from '@kit.ConnectivityKit'; 341 342try { 343 let deviceIds = access.getPersistentDeviceIds(); 344 console.info("deviceIds: " + deviceIds); 345} catch (err) { 346 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 347} 348``` 349 350## access.isValidRandomDeviceId<sup>16+</sup> 351 352isValidRandomDeviceId(deviceId: string): boolean; 353 354判断对端蓝牙设备的虚拟地址是否是有效。 355 356 357**需要权限**：ohos.permission.ACCESS_BLUETOOTH 358 359**原子化服务API**：从API version 16开始，该接口支持在原子化服务中使用。 360 361**系统能力**：SystemCapability.Communication.Bluetooth.Core 362 363**参数：** 364 365| 参数名 | 类型 | 必填 | 说明 | 366| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 367| deviceId | string | 是 | 表示远程设备的虚拟地址，例如："XX:XX:XX:XX:XX:XX"，该地址一般来源于蓝牙扫描结果。 | 368 369**返回值：** 370 371| 类型 | 说明 | 372| --------------------------------- | ---------------- | 373| boolean | 表明蓝牙虚拟设备地址是否有效。 | 374 375**错误码**： 376 377以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[蓝牙服务子系统错误码](errorcode-bluetoothManager.md)。 378 379| 错误码ID | 错误信息 | 380| -------- | ---------------------------- | 381|201 | Permission denied. | 382|401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed. | 383|801 | Capability not supported. | 384|2900003 | Bluetooth disabled. | 385|2900099 | Check persistent device address failed. | 386 387**示例：** 388 389```js 390import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 391import { access } from '@kit.ConnectivityKit'; 392 393try { 394 let deviceId = '11:22:33:44:55:66' // 该地址可通过BLE扫描获取 395 let isValid = access.isValidRandomDeviceId(deviceId); 396 console.info("isValid: " + isValid); 397} catch (err) { 398 console.error('errCode: ' + err.code + ', errMessage: ' + err.message); 399} 400``` 401 402## BluetoothState 403 404枚举，蓝牙开关状态。 405 406**原子化服务API**: 从API version 11开始，该接口支持在原子化服务中使用。 407 408**系统能力**：SystemCapability.Communication.Bluetooth.Core 409 410| 名称 | 值 | 说明 | 411| --------------------- | ---- | ------------------ | 412| STATE_OFF | 0 | 表示蓝牙已关闭。 | 413| STATE_TURNING_ON | 1 | 表示蓝牙正在打开。 | 414| STATE_ON | 2 | 表示蓝牙已打开。 | 415| STATE_TURNING_OFF | 3 | 表示蓝牙正在关闭。 | 416| STATE_BLE_TURNING_ON | 4 | 表示蓝牙正在打开LE-only模式。 | 417| STATE_BLE_ON | 5 | 表示蓝牙正处于LE-only模式。 | 418| STATE_BLE_TURNING_OFF | 6 | 表示蓝牙正在关闭LE-only模式。 | 419 420