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