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