1# @ohos.screenLock (Screen Lock) (System API) 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>This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.screenLock (Screen Lock)](js-apis-screen-lock.md). 10 11## Modules to Import 12 13```ts 14import screenLock from '@ohos.screenLock'; 15``` 16 17## EventType<sup>9+</sup> 18 19Defines the system event type. 20 21**System capability**: SystemCapability.MiscServices.ScreenLock 22 23**System API**: This is a system API. 24 25| Event Type | Description | 26| ------------------ | ------------------------ | 27| beginWakeUp | Wakeup starts.| 28| endWakeUp | Wakeup ends.| 29| beginScreenOn | Screen turn-on starts.| 30| endScreenOn | Screen turn-on ends.| 31| beginScreenOff | Screen turn-off starts.| 32| endScreenOff | Screen turn-off ends.| 33| unlockScreen | The screen is unlocked. | 34| lockScreen | The screen is locked. | 35| beginExitAnimation | Exit animation starts. | 36| beginSleep | The device enters sleep mode. | 37| endSleep | The device exits sleep mode. | 38| changeUser | The user is switched. | 39| screenlockEnabled | Screen lock is enabled. | 40| serviceRestart | The screen lock service is restarted. | 41 42## SystemEvent<sup>9+</sup> 43 44Defines the structure of the system event callback. 45 46**System capability**: SystemCapability.MiscServices.ScreenLock 47 48**System API**: This is a system API. 49 50| Name | Type | Mandatory| Description | 51| --------- | ------ | ---- | ------------- | 52| eventType | [EventType](#eventtype9) | Yes | System event type.| 53| params | string | Yes | System event parameters.| 54 55## screenLock.isLocked<sup>9+</sup> 56 57isLocked(): boolean 58 59Checks whether the screen is locked. 60 61**System capability**: SystemCapability.MiscServices.ScreenLock 62 63**System API**: This is a system API. 64 65**Return value** 66 67| Type | Description | 68| ------- | ------------------------------------------------- | 69| boolean | Returns **true** if the screen is locked; returns **false** otherwise.| 70 71**Error codes** 72 73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 74 75| ID| Error Message| 76| -------- | ---------------------------------------- | 77| 202 | permission verification failed, application which is not a system application uses system API. | 78 79**Example** 80 81```ts 82let isLocked = screenLock.isLocked(); 83``` 84 85## screenLock.unlock<sup>9+</sup> 86 87unlock(callback: AsyncCallback<boolean>): void 88 89Unlocks the screen. This API uses an asynchronous callback to return the result. 90 91**System capability**: SystemCapability.MiscServices.ScreenLock 92 93**System API**: This is a system API. 94 95**Parameters** 96 97| Name | Type | Mandatory| Description | 98| -------- | --------------------- | ---- | ------------------------- | 99| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means that screen unlocked is canceled.| 100 101**Error codes** 102 103For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 104 105| ID| Error Message| 106| -------- | ---------------------------------------- | 107| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 108| 202 | permission verification failed, application which is not a system application uses system API. | 109| 13200002 | the screenlock management service is abnormal. | 110| 13200003 | illegal use. | 111 112**Example** 113 114 ```ts 115 import { BusinessError } from '@ohos.base'; 116 117 screenLock.unlock((err: BusinessError, data: Boolean) => { 118 if (err) { 119 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 120 return; 121 } 122 console.info(`Succeeded in unlocking the screen. result: ${data}`); 123 }); 124 ``` 125 126> **NOTE** 127> 128> The error code **13200003 illegal use** is added since API version 11. 129 130## screenLock.unlock<sup>9+</sup> 131 132unlock(): Promise<boolean> 133 134Unlocks the screen. This API uses a promise to return the result. 135 136**System capability**: SystemCapability.MiscServices.ScreenLock 137 138**System API**: This is a system API. 139 140**Return value** 141 142| Type | Description | 143| ------------------- | ------------------------------------------------------------ | 144| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is unlocked successfully, and **false** means that screen unlocked is canceled.| 145 146**Error codes** 147 148For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 149 150| ID| Error Message| 151| -------- | ---------------------------------------- | 152| 202 | permission verification failed, application which is not a system application uses system API. | 153| 13200002 | the screenlock management service is abnormal. | 154| 13200003 | illegal use. | 155 156**Example** 157 158 ```ts 159 import { BusinessError } from '@ohos.base'; 160 161 screenLock.unlock().then((data: Boolean) => { 162 console.info(`Succeeded in unlocking the screen. result: ${data}`); 163 }).catch((err: BusinessError) => { 164 console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`); 165 }); 166 ``` 167 168> **NOTE** 169> 170> The error code **13200003 illegal use** is added since API version 11. 171 172## screenLock.lock<sup>9+</sup> 173 174lock(callback: AsyncCallback<boolean>): void 175 176Locks the screen. This API uses an asynchronous callback to return the result. 177 178**System capability**: SystemCapability.MiscServices.ScreenLock 179 180**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 181 182**System API**: This is a system API. 183 184**Parameters** 185 186| Name | Type | Mandatory| Description | 187| -------- | ---------------------- | ---- | ---------------- | 188| 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.| 189 190**Error codes** 191 192For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 193 194| ID| Error Message| 195| -------- | ---------------------------------------- | 196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 197| 201 | permission denied. | 198| 202 | permission verification failed, application which is not a system application uses system API. | 199| 13200002 | the screenlock management service is abnormal. | 200 201**Example** 202 203 ```ts 204 import { BusinessError } from '@ohos.base'; 205 206 screenLock.lock((err: BusinessError, data: Boolean) => { 207 if (err) { 208 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 209 return; 210 } 211 console.info(`Succeeded in locking the screen. result: ${data}`); 212 }); 213 ``` 214 215## screenLock.lock<sup>9+</sup> 216 217lock(): Promise<boolean> 218 219Locks the screen. This API uses a promise to return the result. 220 221**System capability**: SystemCapability.MiscServices.ScreenLock 222 223**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 224 225**System API**: This is a system API. 226 227**Return value** 228 229| Type | Description | 230| ---------------------- | ------------------------------------------------------------ | 231| Promise<boolean> | Promise used to return the result. The value **true** means that the screen is locked successfully, and **false** means the opposite.| 232 233**Error codes** 234 235For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 236 237| ID| Error Message| 238| -------- | ---------------------------------------- | 239| 201 | permission denied. | 240| 202 | permission verification failed, application which is not a system application uses system API. | 241| 13200002 | the screenlock management service is abnormal. | 242 243**Example** 244 245 ```ts 246 import { BusinessError } from '@ohos.base'; 247 248 screenLock.lock().then((data: Boolean) => { 249 console.info(`Succeeded in locking the screen. result: ${data}`); 250 }).catch((err: BusinessError) => { 251 console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`); 252 }); 253 ``` 254 255## screenLock.onSystemEvent<sup>9+</sup> 256 257onSystemEvent(callback: Callback<SystemEvent>): boolean 258 259Registers a callback for system events related to screen locking. This API can be called only by screen lock applications. 260 261**System capability**: SystemCapability.MiscServices.ScreenLock 262 263**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 264 265**System API**: This is a system API. 266 267**Parameters** 268 269| Name | Type | Mandatory| Description | 270| -------- | ------------------------- | ---- | ----------------- | 271| callback | Callback\<[SystemEvent](#systemevent9)> | Yes | Callback for system events related to screen locking.| 272 273**Return value** 274 275| Type | Description | 276| ------- | ------------------------------------------------- | 277| boolean | Returns **true** if the callback is registered successfully; returns **false** otherwise.| 278 279**Error codes** 280 281For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 282 283| ID| Error Message| 284| -------- | ---------------------------------------- | 285| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 286| 201 | permission denied. | 287| 202 | permission verification failed, application which is not a system application uses system API. | 288| 13200002 | the screenlock management service is abnormal. | 289 290**Example** 291 292 ```ts 293 try { 294 let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => { 295 console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`) 296 }); 297 } catch (err) { 298 let error = err as BusinessError; 299 console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`) 300 } 301 ``` 302 303## screenLock.sendScreenLockEvent<sup>9+</sup> 304 305sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void 306 307Sends 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. 308 309**System capability**: SystemCapability.MiscServices.ScreenLock 310 311**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 312 313**System API**: This is a system API. 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| --------- | ------------------------ | ---- | -------------------- | 319| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 320| 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.| 321| 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. | 322 323**Error codes** 324 325For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 326 327| ID| Error Message| 328| -------- | ---------------------------------------- | 329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 330| 201 | permission denied. | 331| 202 | permission verification failed, application which is not a system application uses system API. | 332| 13200002 |the screenlock management service is abnormal. | 333 334**Example** 335 336 ```ts 337 import { BusinessError } from '@ohos.base'; 338 339 screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => { 340 if (err) { 341 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 342 return; 343 } 344 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 345 }); 346 ``` 347 348## screenLock.sendScreenLockEvent<sup>9+</sup> 349 350sendScreenLockEvent(event: String, parameter: number): Promise<boolean> 351 352Sends 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. 353 354**System capability**: SystemCapability.MiscServices.ScreenLock 355 356**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_INNER 357 358**System API**: This is a system API. 359 360**Parameters** 361 362| Name | Type | Mandatory| Description | 363| --------- | ------ | ---- | --------------------------------------- | 364| event | String | Yes | Event type.<br>- **"unlockScreenResult"**: Screen unlock result.<br>- **"lockScreenResult"**: Screen lock result.<br>- **"screenDrawDone"**: Screen drawing is complete.| 365| 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.| 366 367**Return value** 368 369| Type | Description | 370| ----------------- | ---------------------------------------------- | 371| Promise\<boolean> | Promise used to return the result. The **value** true means that the event is sent successfully, and **false** means the opposite.| 372 373**Error codes** 374 375For details about error codes, see [Universal Error Codes](../errorcode-universal.md) and [Screen Lock Error Codes](errorcode-screenlock.md). 376 377| ID| Error Message| 378| -------- | ---------------------------------------- | 379| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 380| 201 | permission denied. | 381| 202 | permission verification failed, application which is not a system application uses system API. | 382| 13200002 | the screenlock management service is abnormal. | 383 384**Example** 385 386 ```ts 387 import { BusinessError } from '@ohos.base'; 388 389 screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => { 390 console.info(`Succeeded in Sending screenlock event. result: ${result}`); 391 }).catch((err: BusinessError) => { 392 console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`); 393 }); 394 ``` 395