1# @ohos.bluetooth.access (Bluetooth Access Module) 2 3The **access** module provides APIs for enabling and disabling Bluetooth and obtaining the Bluetooth status. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9 10## Modules to Import 11 12```js 13import { access } from '@kit.ConnectivityKit'; 14``` 15 16 17## access.enableBluetooth 18 19enableBluetooth(): void 20 21Enables Bluetooth. 22 23**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 24 25**Atomic service API**: This API can be used in atomic services since API version 12. 26 27**System capability**: SystemCapability.Communication.Bluetooth.Core 28 29**Error codes** 30 31For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 32 33| ID| Error Message | 34| -------- | ------------------ | 35|201 | Permission denied. | 36|801 | Capability not supported. | 37|2900001 | Service stopped. | 38|2900099 | Operation failed. | 39 40**Example** 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 56Disables Bluetooth. 57 58**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 59 60**Atomic service API**: This API can be used in atomic services since API version 12. 61 62**System capability**: SystemCapability.Communication.Bluetooth.Core 63 64**Error codes** 65 66For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 67 68|ID | Error Message | 69| -------- | ------------------ | 70|201 | Permission denied. | 71|801 | Capability not supported. | 72|2900001 | Service stopped. | 73|2900099 | Operation failed. | 74 75**Example** 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 91Obtains the Bluetooth state. 92 93**Atomic service API**: This API can be used in atomic services since API version 11. 94 95**System capability**: SystemCapability.Communication.Bluetooth.Core 96 97**Return value** 98 99| Type | Description | 100| --------------------------------- | ---------------- | 101| [BluetoothState](#bluetoothstate) | Bluetooth state obtained.| 102 103**Error codes** 104 105For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 106 107|ID | Error Message | 108| -------- | ------------------ | 109|801 | Capability not supported. | 110|2900001 | Service stopped. | 111|2900099 | Operation failed. | 112 113**Example** 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 128Subscribes to Bluetooth state changes. This API uses an asynchronous callback to return the result. Since API version 18, the **ohos.permission.ACCESS_BLUETOOTH** permission is no longer verified. 129 130**Atomic service API**: This API can be used in atomic services since API version 12. 131 132**System capability**: SystemCapability.Communication.Bluetooth.Core 133 134**Parameters** 135 136| Name | Type | Mandatory | Description | 137| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- | 138| type | string | Yes | Event type. The value is **stateChange**, which indicates Bluetooth state changes. | 139| callback | Callback<[BluetoothState](#bluetoothstate)> | Yes | Callback used to return the Bluetooth state. You need to implement this callback.| 140 141**Error codes** 142 143For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 144 145|ID | Error Message | 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**Example** 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 170Unsubscribes from Bluetooth state changes. Since API version 18, the **ohos.permission.ACCESS_BLUETOOTH** permission is no longer verified. 171 172**Atomic service API**: This API can be used in atomic services since API version 12. 173 174**System capability**: SystemCapability.Communication.Bluetooth.Core 175 176**Parameters** 177 178| Name | Type | Mandatory | Description | 179| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 180| type | string | Yes | Event type. The value is **stateChange**, which indicates Bluetooth state changes. | 181| callback | Callback<[BluetoothState](#bluetoothstate)> | No | Callback to unregister. If this parameter is not set, this API unregisters all callbacks for Bluetooth state changes.| 182 183**Error codes** 184 185For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 186 187| ID| Error Message| 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**Example** 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 212The device address obtained by the application through Bluetooth scanning is a random virtual address. If the application needs to use this random virtual address for an extended period, it needs to call this API to persistently store the address. 213 214When using this API, ensure that the real address of the peer device corresponding to the virtual random address remains unchanged. If the real address of the peer device changes, the persistently stored virtual address will become invalid and unusable. 215 216**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 217 218**Atomic service API**: This API can be used in atomic services since API version 16. 219 220**System capability**: SystemCapability.Communication.Bluetooth.Core 221 222**Parameters** 223 224| Name | Type | Mandatory | Description | 225| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 226| deviceId | string | Yes | Virtual address of the peer device, for example, XX:XX:XX:XX:XX:XX. The address is generally obtained from Bluetooth scanning. | 227 228**Error codes** 229 230For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 231 232| ID| Error Message| 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**Example** 242 243```js 244import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 245import { access } from '@kit.ConnectivityKit'; 246 247let deviceId = '11:22:33:44:55:66' // The address can be obtained through BLE scanning. 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 259Deletes a persistently stored virtual address. 260 261 262**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 263 264**Atomic service API**: This API can be used in atomic services since API version 16. 265 266**System capability**: SystemCapability.Communication.Bluetooth.Core 267 268**Parameters** 269 270| Name | Type | Mandatory | Description | 271| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 272| deviceId | string | Yes | Virtual address of the peer device, for example, XX:XX:XX:XX:XX:XX. The address is generally obtained from Bluetooth scanning. | 273 274**Error codes** 275 276For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 277 278| ID| Error Message| 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**Example** 287 288```js 289import { AsyncCallback, BusinessError } from '@kit.BasicServicesKit'; 290import { access } from '@kit.ConnectivityKit'; 291 292let deviceId = '11:22:33:44:55:66' // The address can be obtained through BLE scanning. 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 304Obtains persistently stored virtual addresses. 305 306 307**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.PERSISTENT_BLUETOOTH_PEERS_MAC 308 309**Atomic service API**: This API can be used in atomic services since API version 16. 310 311**System capability**: SystemCapability.Communication.Bluetooth.Core 312 313**Return value** 314 315| Type | Description | 316| --------------------------------- | ---------------- | 317| string[] | List of persistently stored virtual addresses.| 318 319**Error codes** 320 321For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 322 323| ID| Error Message| 324| -------- | ---------------------------- | 325|201 | Permission denied. | 326|801 | Capability not supported. | 327|2900003 | Bluetooth disabled. | 328|2900099 | Get persistent device address failed. | 329 330**Example** 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 348Checks whether the virtual address of the peer device is valid. 349 350 351**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 352 353**Atomic service API**: This API can be used in atomic services since API version 16. 354 355**System capability**: SystemCapability.Communication.Bluetooth.Core 356 357**Parameters** 358 359| Name | Type | Mandatory | Description | 360| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 361| deviceId | string | Yes | Virtual address of the peer device, for example, XX:XX:XX:XX:XX:XX. The address is generally obtained from Bluetooth scanning. | 362 363**Return value** 364 365| Type | Description | 366| --------------------------------- | ---------------- | 367| boolean | Whether the virtual address is valid.| 368 369**Error codes** 370 371For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Bluetooth Error Codes](errorcode-bluetoothManager.md). 372 373| ID| Error Message| 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**Example** 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' // The address can be obtained through BLE scanning. 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 398Enumerates the Bluetooth states. 399 400**Atomic service API**: This API can be used in atomic services since API version 11. 401 402**System capability**: SystemCapability.Communication.Bluetooth.Core 403 404| Name | Value | Description | 405| --------------------- | ---- | ------------------ | 406| STATE_OFF | 0 | Bluetooth is turned off. | 407| STATE_TURNING_ON | 1 | Bluetooth is being turned on. | 408| STATE_ON | 2 | Bluetooth is turned on. | 409| STATE_TURNING_OFF | 3 | Bluetooth is being turned off. | 410| STATE_BLE_TURNING_ON | 4 | The LE-only mode is being turned on for Bluetooth.| 411| STATE_BLE_ON | 5 | Bluetooth is in LE-only mode. | 412| STATE_BLE_TURNING_OFF | 6 | The LE-only mode is being turned off for Bluetooth.| 413