1# @ohos.runningLock (Running Lock) 2 3The **runningLock** module provides APIs for creating, querying, holding, and releasing running locks. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```js 12import runningLock from '@ohos.runningLock'; 13``` 14 15## runningLock.isSupported<sup>9+</sup> 16 17isSupported(type: RunningLockType): boolean; 18 19Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. 20 21**System capability:** SystemCapability.PowerManager.PowerManager.Core 22 23**Parameters** 24 25| Name| Type | Mandatory| Description | 26| ------ | ----------------------------------- | ---- | -------------------- | 27| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object.| 28 29**Return Value** 30 31| Type | Description | 32| ------- | --------------------------------------- | 33| boolean | The value **true** indicates that the specified type of **RunningLock** is supported, and the value **false** indicates the opposite.| 34 35**Error codes** 36 37For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 38 39| ID | Error Message | 40|---------|---------| 41| 4900101 | If connecting to the service failed. | 42 43**Example** 44 45```js 46try { 47 var isSupported = runningLock.isSupported(runningLock.RunningLockType.BACKGROUND); 48 console.info('BACKGROUND type supported: ' + isSupported); 49} catch(err) { 50 console.error('check supported failed, err: ' + err); 51} 52``` 53 54## runningLock.create<sup>9+</sup> 55 56create(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void 57 58Creates a **RunningLock** object. 59 60**System capability:** SystemCapability.PowerManager.PowerManager.Core 61 62**Required permission:** ohos.permission.RUNNING_LOCK 63 64**Parameters** 65 66| Name | Type | Mandatory| Description | 67| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 68| name | string | Yes | Name of the **RunningLock** object. | 69| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created. | 70| callback | AsyncCallback<[RunningLock](#runninglock)> | Yes | Callback used to return the result. If a lock is successfully created, **err** is **undefined** and **data** is the created **RunningLock**. Otherwise, **err** is an error object.| 71 72**Error codes** 73 74For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 75 76| ID | Error Message | 77|---------|----------| 78| 4900101 | If connecting to the service failed. | 79 80**Example** 81 82```js 83runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err, lock) => { 84 if (typeof err === 'undefined') { 85 console.info('created running lock: ' + lock); 86 } else { 87 console.error('create running lock failed, err: ' + err); 88 } 89}); 90``` 91 92## runningLock.create<sup>9+</sup> 93 94create(name: string, type: RunningLockType): Promise<RunningLock> 95 96Creates a **RunningLock** object. 97 98**System capability:** SystemCapability.PowerManager.PowerManager.Core 99 100**Required permission:** ohos.permission.RUNNING_LOCK 101 102**Parameters** 103 104| Name| Type | Mandatory| Description | 105| ------ | ----------------------------------- | ---- | ------------------ | 106| name | string | Yes | Name of the **RunningLock** object. | 107| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created.| 108 109**Return Value** 110 111| Type | Description | 112| ------------------------------------------ | ------------------------------------ | 113| Promise<[RunningLock](#runninglock)> | Promise used to return the result.| 114 115**Error codes** 116 117For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 118 119| ID | Error Message | 120|---------|----------| 121| 4900101 | If connecting to the service failed. | 122 123**Example** 124 125```js 126runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND) 127.then(lock => { 128 console.info('created running lock: ' + lock); 129}) 130.catch(err => { 131 console.error('create running lock failed, error: ' + err); 132}); 133``` 134 135## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup> 136 137isRunningLockTypeSupported(type: RunningLockType, callback: AsyncCallback<boolean>): void 138 139> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [runningLock.isSupported](#runninglockissupported9). 140 141Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. This API uses an asynchronous callback to return the result. 142 143**System capability:** SystemCapability.PowerManager.PowerManager.Core 144 145**Parameters** 146 147| Name | Type | Mandatory| Description | 148| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 149| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object. | 150| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the query result obtained, where the value **true** indicates that the specified type of **RunningLock** is supported and **false** indicates the opposite. Otherwise, **err** is an error object.| 151 152**Example** 153 154```js 155runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND, (err, data) => { 156 if (typeof err === 'undefined') { 157 console.info('BACKGROUND lock support status: ' + data); 158 } else { 159 console.log('check BACKGROUND lock support status failed, err: ' + err); 160 } 161}); 162``` 163 164## runningLock.isRunningLockTypeSupported<sup>(deprecated)</sup> 165 166isRunningLockTypeSupported(type: RunningLockType): Promise<boolean> 167 168> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [runningLock.isSupported](#runninglockissupported9). 169 170Checks whether the specified type of **RunningLock** is supported. This API uses an asynchronous callback to return the result. This API uses a promise to return the result. 171 172**System capability:** SystemCapability.PowerManager.PowerManager.Core 173 174**Parameters** 175 176| Name| Type | Mandatory| Description | 177| ------ | ----------------------------------- | ---- | -------------------- | 178| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object.| 179 180**Return Value** 181 182| Type | Description | 183| ---------------------- | ---------------------------------------------------- | 184| Promise<boolean> | Promise used to return the result. The value **true** indicates that the specified type of **RunningLock** is supported, and the value **false** indicates the opposite.| 185 186**Example** 187 188```js 189runningLock.isRunningLockTypeSupported(runningLock.RunningLockType.BACKGROUND) 190.then(data => { 191 console.info('BACKGROUND lock support status: ' + data); 192}) 193.catch(err => { 194 console.log('check BACKGROUND lock support status failed, err: ' + err); 195}); 196``` 197 198## runningLock.createRunningLock<sup>(deprecated)</sup> 199 200createRunningLock(name: string, type: RunningLockType, callback: AsyncCallback<RunningLock>): void 201 202> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [runningLock.create](#runninglockcreate9). 203 204Creates a **RunningLock** object. 205 206**System capability:** SystemCapability.PowerManager.PowerManager.Core 207 208**Required permission:** ohos.permission.RUNNING_LOCK 209 210**Parameters** 211 212| Name | Type | Mandatory| Description | 213| -------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 214| name | string | Yes | Name of the **RunningLock** object. | 215| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created. | 216| callback | AsyncCallback<[RunningLock](#runninglock)> | Yes | Callback used to return the result. If a lock is successfully created, **err** is **undefined** and **data** is the created **RunningLock**. Otherwise, **err** is an error object.| 217 218**Example** 219 220```js 221runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND, (err, lock) => { 222 if (typeof err === 'undefined') { 223 console.info('created running lock: ' + lock); 224 } else { 225 console.error('create running lock failed, err: ' + err); 226 } 227}); 228``` 229 230## runningLock.createRunningLock<sup>(deprecated)</sup> 231 232createRunningLock(name: string, type: RunningLockType): Promise<RunningLock> 233 234> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [runningLock.create](#runninglockcreate9). 235 236Creates a **RunningLock** object. 237 238**System capability:** SystemCapability.PowerManager.PowerManager.Core 239 240**Required permission:** ohos.permission.RUNNING_LOCK 241 242**Parameters** 243 244| Name| Type | Mandatory| Description | 245| ------ | ----------------------------------- | ---- | ------------------ | 246| name | string | Yes | Name of the **RunningLock** object. | 247| type | [RunningLockType](#runninglocktype) | Yes | Type of the **RunningLock** object to be created.| 248 249**Return Value** 250 251| Type | Description | 252| ------------------------------------------ | ------------------------------------ | 253| Promise<[RunningLock](#runninglock)> | Promise used to return the result.| 254 255**Example** 256 257```js 258runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 259.then(lock => { 260 console.info('created running lock: ' + lock); 261}) 262.catch(err => { 263 console.log('create running lock failed, err: ' + err); 264}); 265``` 266 267## RunningLock 268 269Defines a **RunningLock** object. 270 271### hold<sup>9+</sup> 272 273hold(timeout: number): void 274 275Locks and holds a **RunningLock** object. 276 277**System capability:** SystemCapability.PowerManager.PowerManager.Core 278 279**Required permission:** ohos.permission.RUNNING_LOCK 280 281**Parameters** 282 283| Name | Type | Mandatory| Description | 284| ------- | ------ | ---- | ----------------------------------------- | 285| timeout | number | Yes | Duration for locking and holding the **RunningLock** object, in ms.| 286 287**Error codes** 288 289For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 290 291| ID | Error Message | 292|---------|----------| 293| 4900101 | If connecting to the service failed. | 294 295**Example** 296 297```js 298runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND) 299.then(lock => { 300 console.info('create running lock success'); 301 try { 302 lock.hold(500); 303 console.info('hold running lock success'); 304 } catch(err) { 305 console.error('hold running lock failed, err: ' + err); 306 } 307}) 308.catch(err => { 309 console.error('create running lock failed, err: ' + err); 310}); 311``` 312 313### unhold<sup>9+</sup> 314 315unhold(): void 316 317Releases a **RunningLock** object. 318 319**System capability:** SystemCapability.PowerManager.PowerManager.Core 320 321**Required permission:** ohos.permission.RUNNING_LOCK 322 323**Error codes** 324 325For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 326 327| ID | Error Message | 328|---------|----------| 329| 4900101 | If connecting to the service failed. | 330 331**Example** 332 333```js 334runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND) 335.then(lock => { 336 console.info('create running lock success'); 337 try { 338 lock.unhold(); 339 console.info('unhold running lock success'); 340 } catch(err) { 341 console.error('unhold running lock failed, err: ' + err); 342 } 343}) 344.catch(err => { 345 console.error('create running lock failed, err: ' + err); 346}); 347``` 348 349### isHolding<sup>9+</sup> 350 351isHolding(): boolean 352 353Checks the hold status of the **Runninglock** object. 354 355**System capability:** SystemCapability.PowerManager.PowerManager.Core 356 357**Return Value** 358 359| Type | Description | 360| ------- | ------------------------------------------------------------ | 361| boolean | The value **true** indicates that the **Runninglock** object is held; and the value **false** indicates that the **Runninglock** object is released.| 362 363**Error codes** 364 365For details about the error codes, see [RunningLock Error Codes](../errorcodes/errorcode-runninglock.md). 366 367| ID | Error Message | 368|---------|---------| 369| 4900101 | If connecting to the service failed. | 370 371**Example** 372 373```js 374runningLock.create('running_lock_test', runningLock.RunningLockType.BACKGROUND) 375.then(lock => { 376 console.info('create running lock success'); 377 try { 378 var isHolding = lock.isHolding(); 379 console.info('check running lock holding status: ' + isHolding); 380 } catch(err) { 381 console.error('check running lock holding status failed, err: ' + err); 382 } 383}) 384.catch(err => { 385 console.error('create running lock failed, err: ' + err); 386}); 387``` 388 389### lock<sup>(deprecated)</sup> 390 391lock(timeout: number): void 392 393> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [RunningLock.hold](#hold9). 394 395Locks and holds a **RunningLock** object. 396 397**System capability:** SystemCapability.PowerManager.PowerManager.Core 398 399**Required permission:** ohos.permission.RUNNING_LOCK 400 401**Parameters** 402 403| Name | Type | Mandatory| Description | 404| ------- | ------ | ---- | ----------------------------------------- | 405| timeout | number | Yes | Duration for locking and holding the **RunningLock** object, in ms.| 406 407**Example** 408 409```js 410runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 411.then(lock => { 412 lock.lock(500); 413 console.info('create running lock and lock success'); 414}) 415.catch(err => { 416 console.error('create running lock failed, err: ' + err); 417}); 418``` 419 420### unlock<sup>(deprecated)</sup> 421 422unlock(): void 423 424> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [RunningLock.unhold](#unhold9). 425 426Releases a **RunningLock** object. 427 428**System capability:** SystemCapability.PowerManager.PowerManager.Core 429 430**Required permission:** ohos.permission.RUNNING_LOCK 431 432**Example** 433 434```js 435runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 436.then(lock => { 437 lock.unlock(); 438 console.info('create running lock and unlock success'); 439}) 440.catch(err => { 441 console.error('create running lock failed, err: ' + err); 442}); 443``` 444 445### isUsed<sup>(deprecated)</sup> 446 447isUsed(): boolean 448 449> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [RunningLock.isHolding](#isholding9). 450 451Checks the hold status of the **Runninglock** object. 452 453**System capability:** SystemCapability.PowerManager.PowerManager.Core 454 455**Return Value** 456| Type | Description | 457| ------- | ------------------------------------------------------------ | 458| boolean | The value **true** indicates that the **Runninglock** object is held; and the value **false** indicates that the **Runninglock** object is released.| 459 460**Example** 461 462```js 463runningLock.createRunningLock('running_lock_test', runningLock.RunningLockType.BACKGROUND) 464.then(lock => { 465 var isUsed = lock.isUsed(); 466 console.info('check running lock used status: ' + isUsed); 467}) 468.catch(err => { 469 console.error('check running lock used status failed, err: ' + err); 470}); 471``` 472 473## RunningLockType 474 475Enumerates the types of **RunningLock** objects. 476 477**System capability:** SystemCapability.PowerManager.PowerManager.Core 478 479| Name | Value | Description | 480| --------------------------------- | ---- | ------------------------------------------------------------ | 481| BACKGROUND<sup>(deprecated)</sup> | 1 | A lock that prevents the system from hibernating when the screen is off.<br>**NOTE**<br>This parameter is supported since API version 7 and deprecated since API version 10.| 482| PROXIMITY_SCREEN_CONTROL | 2 | A lock that determines whether to turn on or off the screen based on the distance away from the screen. | 483