1# @ohos.screenLock (Screen Lock) 2 3The **screenlock** module is a system module in OpenHarmony. It provides APIs for screen lock applications to subscribe to screen lock status changes as well as callbacks for them to receive the results. It also provides APIs for third-party applications to unlock the screen, obtain the screen locked status, and check whether a lock screen password has been set. 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```ts 12import screenLock from '@ohos.screenLock'; 13``` 14 15## EventType<sup>9+</sup> 16 17Defines the system event type. 18 19**System capability**: SystemCapability.MiscServices.ScreenLock 20 21**System API**: This is a system API. 22 23| Event Type | Description | 24| ------------------ | ------------------------ | 25| beginWakeUp | Wakeup starts.| 26| endWakeUp | Wakeup ends.| 27| beginScreenOn | Screen turn-on starts.| 28| endScreenOn | Screen turn-on ends.| 29| beginScreenOff | Screen turn-off starts.| 30| endScreenOff | Screen turn-off ends.| 31| unlockScreen | The screen is unlocked. | 32| lockScreen | The screen is locked. | 33| beginExitAnimation | Exit animation starts. | 34| beginSleep | The device enters sleep mode. | 35| endSleep | The device exits sleep mode. | 36| changeUser | The user is switched. | 37| screenlockEnabled | Screen lock is enabled. | 38| serviceRestart | The screen lock service is restarted. | 39 40## SystemEvent<sup>9+</sup> 41 42Defines the structure of the system event callback. 43 44**System capability**: SystemCapability.MiscServices.ScreenLock 45 46**System API**: This is a system API. 47 48| Name | Type | Mandatory| Description | 49| --------- | ------ | ---- | ------------- | 50| eventType | [EventType](#eventtype9) | Yes | System event type.| 51| params | string | Yes | System event parameters.| 52 53## screenLock.isLocked<sup>9+</sup> 54 55isLocked(): boolean 56 57Checks whether the screen is locked. 58 59**System capability**: SystemCapability.MiscServices.ScreenLock 60 61**System API**: This is a system API. 62 63**Return value** 64 65| Type | Description | 66| ------- | ------------------------------------------------- | 67| boolean | Returns **true** if the screen is locked; returns **false** otherwise.| 68 69**Example** 70 71```ts 72let isLocked = screenLock.isLocked(); 73``` 74 75## screenLock.unlock<sup>9+</sup> 76 77unlock(callback: AsyncCallback<boolean>): void 78 79Unlocks the screen. This API uses an asynchronous callback to return the result. 80 81**System capability**: SystemCapability.MiscServices.ScreenLock 82 83**System API**: This is a system API. 84 85**Parameters** 86 87| Name | Type | Mandatory| Description | 88| -------- | --------------------- | ---- | ------------------------- | 89| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| 90 91**Error codes** 92 93For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 94 95| ID| Error Message| 96| -------- | ---------------------------------------- | 97| 13200002 | the screenlock management service is abnormal. | 98 99**Example** 100 101 ```ts 102 import { BusinessError } from '@ohos.base'; 103 104 screenLock.unlock((err: BusinessError, data: Boolean) => { 105 if (err) { 106 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 107 return; 108 } 109 console.info(`Succeeded in unlocking the screen. result: ${data}`); 110 }); 111 ``` 112 113## screenLock.unlock<sup>9+</sup> 114 115unlock(): Promise<boolean> 116 117Unlocks the screen. This API uses a promise to return the result. 118 119**System capability**: SystemCapability.MiscServices.ScreenLock 120 121**System API**: This is a system API. 122 123**Return value** 124 125| Type | Description | 126| ------------------- | ------------------------------------------------------------ | 127| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means the opposite.| 128 129**Error codes** 130 131For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 132 133| ID| Error Message| 134| -------- | ---------------------------------------- | 135| 13200002 | the screenlock management service is abnormal. | 136 137**Example** 138 139 ```ts 140 import { BusinessError } from '@ohos.base'; 141 142 screenLock.unlock().then((data: Boolean) => { 143 console.info(`Succeeded in unlocking the screen. result: ${data}`); 144 }).catch((err: BusinessError) => { 145 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 146 }); 147 ``` 148 149## screenLock.lock<sup>9+</sup> 150 151lock(callback: AsyncCallback<boolean>): void 152 153Locks the screen. This API uses an asynchronous callback to return the result. 154 155**System capability**: SystemCapability.MiscServices.ScreenLock 156 157**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 158 159**System API**: This is a system API. 160 161**Parameters** 162 163| Name | Type | Mandatory| Description | 164| -------- | ---------------------- | ---- | ---------------- | 165| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 166 167**Error codes** 168 169For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 170 171| ID| Error Message| 172| -------- | ---------------------------------------- | 173| 13200002 | the screenlock management service is abnormal. | 174 175**Example** 176 177 ```ts 178 import { BusinessError } from '@ohos.base'; 179 180 screenLock.lock((err: BusinessError, data: Boolean) => { 181 if (err) { 182 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 183 return; 184 } 185 console.info(`Succeeded in locking the screen. result: ${data}`); 186 }); 187 ``` 188 189## screenLock.lock<sup>9+</sup> 190 191lock(): Promise<boolean> 192 193Locks the screen. This API uses a promise to return the result. 194 195**System capability**: SystemCapability.MiscServices.ScreenLock 196 197**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 198 199**System API**: This is a system API. 200 201**Return value** 202 203| Type | Description | 204| ---------------------- | ------------------------------------------------------------ | 205| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 206 207**Error codes** 208 209For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 210 211| ID| Error Message| 212| -------- | ---------------------------------------- | 213| 13200002 | the screenlock management service is abnormal. | 214 215**Example** 216 217 ```ts 218 import { BusinessError } from '@ohos.base'; 219 220 screenLock.lock().then((data: Boolean) => { 221 console.info(`Succeeded in locking the screen. result: ${data}`); 222 }).catch((err: BusinessError) => { 223 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 224 }); 225 ``` 226 227## screenLock.onSystemEvent<sup>9+</sup> 228 229onSystemEvent(callback: Callback<SystemEvent>): boolean 230 231Registers a callback for system events related to screen locking. This API can be called only by screen lock applications. 232 233**System capability**: SystemCapability.MiscServices.ScreenLock 234 235**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 236 237**System API**: This is a system API. 238 239**Parameters** 240 241| Name | Type | Mandatory| Description | 242| -------- | ------------------------- | ---- | ----------------- | 243| callback | Callback\<[SystemEvent](#systemevent9)> | Yes | Callback for system events related to screen locking.| 244 245**Return value** 246 247| Type | Description | 248| ------- | ------------------------------------------------- | 249| boolean | Returns **true** if the callback is registered successfully; returns **false** otherwise.| 250 251**Error codes** 252 253For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 254 255| ID| Error Message| 256| -------- | ---------------------------------------- | 257| 13200002 | the screenlock management service is abnormal. | 258 259**Example** 260 261 ```ts 262 try { 263 let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => { 264 console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`) 265 }); 266 } catch (err) { 267 let error = err as BusinessError; 268 console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`) 269 } 270 ``` 271 272## screenLock.sendScreenLockEvent<sup>9+</sup> 273 274sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 275 276Sends an event to the screen lock service. This API can be called only by screen lock applications. It uses an asynchronous callback to return the result. 277 278**System capability**: SystemCapability.MiscServices.ScreenLock 279 280**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 281 282**System API**: This is a system API. 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287| --------- | ------------------------ | ---- | -------------------- | 288| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 289| parameter | number | Yes | Result.<br>- **0**: The operation is successful. For example, the screen is locked or unlocked successfully.<br>- **1**, the operation fails. For example, screen locking or unlocking fails.<br>- **2**: The operation is canceled. For example, screen locking or unlocking is canceled.| 290| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite. | 291 292**Error codes** 293 294For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 295 296| ID| Error Message| 297| -------- | ---------------------------------------- | 298| 13200002 |the screenlock management service is abnormal. | 299 300**Example** 301 302 ```ts 303 import { BusinessError } from '@ohos.base'; 304 305 screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => { 306 if (err) { 307 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 308 return; 309 } 310 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 311 }); 312 ``` 313 314## screenLock.sendScreenLockEvent<sup>9+</sup> 315 316sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 317 318Sends an event to the screen lock service. This API can be called only by screen lock applications. It uses a promise to return the result. 319 320**System capability**: SystemCapability.MiscServices.ScreenLock 321 322**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 323 324**System API**: This is a system API. 325 326**Parameters** 327 328| Name | Type | Mandatory| Description | 329| --------- | ------ | ---- | --------------------------------------- | 330| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 331| parameter | number | Yes | Result.<br>- **0**: The operation is successful. For example, the screen is locked or unlocked successfully.<br>- **1**, the operation fails. For example, screen locking or unlocking fails.<br>- **2**: The operation is canceled. For example, screen locking or unlocking is canceled.| 332 333**Return value** 334 335| Type | Description | 336| ----------------- | ---------------------------------------------- | 337| Promise\<boolean> | Promise used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite.| 338 339**Error codes** 340 341For details about the error codes, see [Screen Lock Management Error Codes](../errorcodes/errorcode-screenlock.md). 342 343| ID| Error Message| 344| -------- | ---------------------------------------- | 345| 13200002 | the screenlock management service is abnormal. | 346 347**Example** 348 349 ```ts 350 import { BusinessError } from '@ohos.base'; 351 352 screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => { 353 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 354 }).catch((err: BusinessError) => { 355 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 356 }); 357 ``` 358 359## screenLock.isScreenLocked<sup>(deprecated)</sup> 360 361isScreenLocked(callback: AsyncCallback<boolean>): void 362 363Checks whether the screen is locked. This API uses an asynchronous callback to return the result. 364 365> **NOTE** 366> 367> This API is supported since API version 7 and deprecated since API version 9. 368 369**System capability**: SystemCapability.MiscServices.ScreenLock 370 371**Parameters** 372 373| Name | Type | Mandatory| Description | 374| -------- | ---------------------------- | ---- | ----------------------------------------------------------- | 375| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 376 377**Example** 378 379 ```ts 380 import { BusinessError } from '@ohos.base'; 381 382 screenLock.isScreenLocked((err: BusinessError, data: Boolean)=>{ 383 if (err) { 384 console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`); 385 return; 386 } 387 console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`); 388 }); 389 ``` 390 391## screenLock.isScreenLocked<sup>(deprecated)</sup> 392 393isScreenLocked(): Promise<boolean> 394 395Checks whether the screen is locked. This API uses a promise to return the result. 396 397> **NOTE** 398> 399> This API is supported since API version 7 and deprecated since API version 9. 400 401**System capability**: SystemCapability.MiscServices.ScreenLock 402 403**Return value** 404 405| Type | Description | 406| ---------------------- | ------------------------------------------- | 407| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked, and **false** means the opposite.| 408 409**Example** 410 411 ```ts 412 import { BusinessError } from '@ohos.base'; 413 414 screenLock.isScreenLocked().then((data: Boolean) => { 415 console.info(`Succeeded in Obtaining whether the screen is locked. result: ${data}`); 416 }).catch((err: BusinessError) => { 417 console.error(`Failed to obtain whether the screen is locked, Code: ${err.code}, message: ${err.message}`); 418 }); 419 ``` 420 421## screenLock.isSecureMode<sup>(deprecated)</sup> 422 423isSecureMode(callback: AsyncCallback<boolean>): void 424 425Checks whether the device is in secure mode. When the device is in secure mode, its screen requires a password, unlock pattern, or other user credentials to unlock. This API uses an asynchronous callback to return the result. 426 427> **NOTE** 428> 429> This API is supported since API version 7 and deprecated since API version 9. 430 431**System capability**: SystemCapability.MiscServices.ScreenLock 432 433**Parameters** 434 435| Name | Type | Mandatory| Description | 436| -------- | --------------------- | ---- | ------------------------ | 437| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| 438 439**Example** 440 441 ```ts 442 import { BusinessError } from '@ohos.base'; 443 444 screenLock.isSecureMode((err: BusinessError, data: Boolean)=>{ 445 if (err) { 446 console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`); 447 return; 448 } 449 console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`); 450 }); 451 ``` 452 453## screenLock.isSecureMode<sup>(deprecated)</sup> 454 455isSecureMode(): Promise<boolean> 456 457Checks whether the device is in secure mode. When the device is in secure mode, its screen requires a password, unlock pattern, or other user credentials to unlock. This API uses a promise to return the result. 458 459> **NOTE** 460> 461> This API is supported since API version 7 and deprecated since API version 9. 462 463**System capability**: SystemCapability.MiscServices.ScreenLock 464 465**Return value** 466 467| Type | Description | 468| ---------------------- | ------------------------------------------------------------ | 469| Promise<boolean> | Promise used to return the result. The value **true** means that the device is in secure mode, and **false** means the opposite.| 470 471**Example** 472 473 ```ts 474 import { BusinessError } from '@ohos.base'; 475 476 screenLock.isSecureMode().then((data: Boolean) => { 477 console.info(`Succeeded in Obtaining whether the device is in secure mode. result: ${data}`); 478 }).catch((err: BusinessError) => { 479 console.error(`Failed to obtain whether the device is in secure mode, Code: ${err.code}, message: ${err.message}`); 480 }); 481 ``` 482 483## screenLock.unlockScreen<sup>(deprecated)</sup> 484 485unlockScreen(callback: AsyncCallback<void>): void 486 487Unlocks the screen. This API uses an asynchronous callback to return the result. 488 489> **NOTE** 490> 491> This API is supported since API version 7 and deprecated since API version 9. 492 493**System capability**: SystemCapability.MiscServices.ScreenLock 494 495**Parameters** 496 497| Name | Type | Mandatory| Description | 498| -------- | ------------- | ---- | --------------- | 499| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the screen is unlocked successfully, **err** is **undefined**; otherwise, **err** is an error object.| 500 501**Example** 502 503 ```ts 504 import { BusinessError } from '@ohos.base'; 505 506 screenLock.unlockScreen((err: BusinessError) => { 507 if (err) { 508 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 509 return; 510 } 511 console.info(`Succeeded unlocking the screen.`); 512 }); 513 ``` 514 515## screenLock.unlockScreen<sup>(deprecated)</sup> 516 517unlockScreen(): Promise<void> 518 519Unlocks the screen. This API uses a promise to return the result. 520 521> **NOTE** 522> 523> This API is supported since API version 7 and deprecated since API version 9. 524 525**System capability**: SystemCapability.MiscServices.ScreenLock 526 527**Return value** 528 529| Type | Description | 530| ------------------- | ------------------------- | 531| Promise<void> | Promise that returns no value.| 532 533**Example** 534 535 ```ts 536 import { BusinessError } from '@ohos.base'; 537 538 screenLock.unlockScreen().then(() => { 539 console.info('Succeeded unlocking the screen.'); 540 }).catch((err: BusinessError) => { 541 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 542 }); 543 ``` 544