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 '@ohos.bluetooth.access'; 14``` 15 16 17## access.enableBluetooth 18 19enableBluetooth(): void 20 21Enables Bluetooth. 22 23**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 24 25**System capability**: SystemCapability.Communication.Bluetooth.Core 26 27**Error codes** 28 29For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 30 31| ID| Error Message | 32| -------- | ------------------ | 33|2900001 | Service stopped. | 34|2900099 | Operation failed. | 35 36**Example** 37 38```js 39import { BusinessError } from '@ohos.base'; 40try { 41 access.enableBluetooth(); 42} catch (err) { 43 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 44} 45``` 46 47 48## access.disableBluetooth 49 50disableBluetooth(): void 51 52Disables Bluetooth. 53 54**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 55 56**System capability**: SystemCapability.Communication.Bluetooth.Core 57 58**Error codes** 59 60For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 61 62|ID | Error Message | 63| -------- | ------------------ | 64|2900001 | Service stopped. | 65|2900099 | Operation failed. | 66 67**Example** 68 69```js 70import { BusinessError } from '@ohos.base'; 71try { 72 access.disableBluetooth(); 73} catch (err) { 74 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 75} 76``` 77 78 79## access.getState 80 81getState(): BluetoothState 82 83Obtains the Bluetooth state. 84 85**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 86 87**System capability**: SystemCapability.Communication.Bluetooth.Core 88 89**Return value** 90 91| Type | Description | 92| --------------------------------- | ---------------- | 93| [BluetoothState](#bluetoothstate) | Bluetooth state obtained.| 94 95**Error codes** 96 97For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 98 99|ID | Error Message | 100| -------- | ------------------ | 101|2900001 | Service stopped. | 102|2900099 | Operation failed. | 103 104**Example** 105 106```js 107import { BusinessError } from '@ohos.base'; 108try { 109 let state = access.getState(); 110} catch (err) { 111 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 112} 113``` 114 115 116## access.factoryReset<sup>11+</sup> 117 118factoryReset(callback: AsyncCallback<void>): void 119 120Restores the Bluetooth factory settings. 121 122**System API**: This is a system API. 123 124**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 125 126**System capability**: SystemCapability.Communication.Bluetooth.Core 127 128**Parameters** 129 130| Name | Type | Mandatory | Description | 131| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- | 132| callback | AsyncCallback<void> | Yes | Callback invoked to return the result.<br> If the Bluetooth factory settings are restored successfully, **err** is **undefined**. Otherwise, **err** is an error object. | 133 134**Error codes** 135 136For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 137 138|ID | Error Message | 139| -------- | ------------------ | 140|2900001 | Service stopped. | 141|2900099 | Operation failed. | 142 143**Example** 144 145```js 146import { AsyncCallback, BusinessError } from '@ohos.base'; 147try { 148 access.factoryReset((err: BusinessError) => { 149 if (err) { 150 console.error("factoryReset error"); 151 } 152 }); 153} catch (err) { 154 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 155} 156``` 157 158 159## access.factoryReset<sup>11+</sup> 160 161factoryReset(): Promise<void> 162 163Restores the Bluetooth factory settings. 164 165**System API**: This is a system API. 166 167**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.MANAGE_BLUETOOTH 168 169**System capability**: SystemCapability.Communication.Bluetooth.Core 170 171**Return value** 172 173| Type | Description | 174| --------------------------------- | ---------------- | 175| Promise<void> | Promise that returns no value.| 176 177**Error codes** 178 179For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 180 181|ID | Error Message | 182| -------- | ------------------ | 183|2900001 | Service stopped. | 184|2900099 | Operation failed. | 185 186**Example** 187 188```js 189import { AsyncCallback, BusinessError } from '@ohos.base'; 190try { 191 access.factoryReset().then(() => { 192 console.info("factoryReset"); 193 }); 194} catch (err) { 195 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 196} 197``` 198 199 200## access.getLocalAddress<sup>11+</sup><a name="getLocalAddress"></a> 201 202getLocalAddress(): string; 203 204Obtains the Bluetooth address of the local device. 205 206**System API**: This is a system API. 207 208**Required permissions**: ohos.permission.ACCESS_BLUETOOTH and ohos.permission.GET_BLUETOOTH_LOCAL_MAC 209 210**System capability**: SystemCapability.Communication.Bluetooth.Core 211 212**Return value** 213 214| Type | Description | 215| --------- | ------------------ | 216| string | Bluetooth address obtained.| 217 218**Error codes** 219 220For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 221 222|ID | Error Message | 223| -------- | ------------------ | 224|2900001 | Service stopped. | 225|2900099 | Operation failed. | 226 227**Example** 228 229```js 230try { 231 let localAddr = access.getLocalAddress(); 232} catch (err) { 233 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 234} 235``` 236 237 238## access.on('stateChange')<a name="stateChange"></a> 239 240on(type: "stateChange", callback: Callback<BluetoothState>): void 241 242Subscribes to Bluetooth state changes. 243 244**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 245 246**System capability**: SystemCapability.Communication.Bluetooth.Core 247 248**Parameters** 249 250| Name | Type | Mandatory | Description | 251| -------- | ------------------------------------------------- | ----- | ---------------------------------------------------------- | 252| type | string | Yes | Event type. The value is **stateChange**, which indicates a Bluetooth state change event. | 253| callback | Callback<[BluetoothState](#bluetoothstate)> | Yes | Callback invoked to return the Bluetooth state. You need to implement this callback.| 254 255**Error codes** 256 257For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 258 259|ID | Error Message | 260| -------- | ------------------ | 261|2900099 | Operation failed. | 262 263**Example** 264 265```js 266import { BusinessError } from '@ohos.base'; 267function onReceiveEvent(data: access.BluetoothState) { 268 console.info('bluetooth state = '+ JSON.stringify(data)); 269} 270try { 271 access.on('stateChange', onReceiveEvent); 272} catch (err) { 273 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 274} 275``` 276 277 278## access.off('stateChange') 279 280off(type: "stateChange", callback?: Callback<BluetoothState>): void 281 282Unsubscribes from Bluetooth state changes. 283 284**Required permissions**: ohos.permission.ACCESS_BLUETOOTH 285 286**System capability**: SystemCapability.Communication.Bluetooth.Core 287 288**Parameters** 289 290| Name | Type | Mandatory | Description | 291| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 292| type | string | Yes | Event type. The value is **stateChange**, which indicates a Bluetooth state change event. | 293| callback | Callback<[BluetoothState](#bluetoothstate)> | No | Callback for the Bluetooth state change event. If this parameter is not set, this API unsubscribes from all callbacks corresponding to **type**.| 294 295**Error codes** 296 297For details about the error codes, see [Bluetooth Error Codes](../errorcodes/errorcode-bluetoothManager.md). 298 299| ID| Error Message| 300| -------- | ---------------------------- | 301|2900099 | Operation failed. | 302 303**Example** 304 305```js 306import { BusinessError } from '@ohos.base'; 307function onReceiveEvent(data: access.BluetoothState) { 308 console.info('bluetooth state = '+ JSON.stringify(data)); 309} 310try { 311 access.on('stateChange', onReceiveEvent); 312 access.off('stateChange', onReceiveEvent); 313} catch (err) { 314 console.error('errCode: ' + (err as BusinessError).code + ', errMessage: ' + (err as BusinessError).message); 315} 316``` 317 318 319## BluetoothState 320 321Enumerates the Bluetooth states. 322 323**System capability**: SystemCapability.Communication.Bluetooth.Core 324 325| Name | Value | Description | 326| --------------------- | ---- | ------------------ | 327| STATE_OFF | 0 | Bluetooth is turned off. | 328| STATE_TURNING_ON | 1 | Bluetooth is being turned on. | 329| STATE_ON | 2 | Bluetooth is turned on. | 330| STATE_TURNING_OFF | 3 | Bluetooth is being turned off. | 331| STATE_BLE_TURNING_ON | 4 | The LE-only mode is being turned on for Bluetooth.| 332| STATE_BLE_ON | 5 | Bluetooth is in LE-only mode. | 333| STATE_BLE_TURNING_OFF | 6 | The LE-only mode is being turned off for Bluetooth.| 334