1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit BasicServicesKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22import { Callback } from './@ohos.base'; 23 24/** 25 * systemScreenLock 26 * 27 * @namespace screenLock 28 * @syscap SystemCapability.MiscServices.ScreenLock 29 * @since 7 30 */ 31declare namespace screenLock { 32 /** 33 * Checks whether the screen is currently locked. 34 * 35 * @param { AsyncCallback<boolean> } callback - the callback of isScreenLocked. 36 * @syscap SystemCapability.MiscServices.ScreenLock 37 * @since 7 38 * @deprecated since 9 39 */ 40 function isScreenLocked(callback: AsyncCallback<boolean>): void; 41 42 /** 43 * Checks whether the screen is currently locked. 44 * 45 * @returns { Promise<boolean> } the promise returned by the function. 46 * @syscap SystemCapability.MiscServices.ScreenLock 47 * @since 7 48 * @deprecated since 9 49 */ 50 function isScreenLocked(): Promise<boolean>; 51 52 /** 53 * Checks whether the screen is currently locked. 54 * 55 * @returns { boolean } returns true if the screen is currently locked, returns false otherwise. 56 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 57 * @syscap SystemCapability.MiscServices.ScreenLock 58 * @systemapi Hide this for inner system use. 59 * @since 9 60 */ 61 function isLocked(): boolean; 62 63 /** 64 * Checks whether the screen lock of the current device is secure. 65 * 66 * @param { AsyncCallback<boolean> } callback - the callback of isSecureMode. 67 * @syscap SystemCapability.MiscServices.ScreenLock 68 * @since 7 69 * @deprecated since 9 70 */ 71 function isSecureMode(callback: AsyncCallback<boolean>): void; 72 73 /** 74 * Checks whether the screen lock of the current device is secure. 75 * 76 * @returns { Promise<boolean> } the promise returned by the function. 77 * @syscap SystemCapability.MiscServices.ScreenLock 78 * @since 7 79 * @deprecated since 9 80 */ 81 function isSecureMode(): Promise<boolean>; 82 83 /** 84 * Unlock the screen. 85 * 86 * @param { AsyncCallback<void> } callback - the callback of unlockScreen. 87 * @syscap SystemCapability.MiscServices.ScreenLock 88 * @since 7 89 * @deprecated since 9 90 */ 91 function unlockScreen(callback: AsyncCallback<void>): void; 92 93 /** 94 * Unlock the screen. 95 * 96 * @returns { Promise<void> } the promise returned by the function. 97 * @syscap SystemCapability.MiscServices.ScreenLock 98 * @since 7 99 * @deprecated since 9 100 */ 101 function unlockScreen(): Promise<void>; 102 103 /** 104 * Unlock the screen. 105 * 106 * @param { AsyncCallback<boolean> } callback - the callback of unlock. 107 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 108 * <br>2. Incorrect parameter types. 109 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 110 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 111 * @syscap SystemCapability.MiscServices.ScreenLock 112 * @systemapi Hide this for inner system use. 113 * @since 9 114 */ 115 /** 116 * Unlock the screen. 117 * 118 * @param { AsyncCallback<boolean> } callback - the callback of unlock. 119 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 120 * <br>2. Incorrect parameter types. 121 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 122 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 123 * @throws { BusinessError } 13200003 - Invalid use. 124 * @syscap SystemCapability.MiscServices.ScreenLock 125 * @systemapi Hide this for inner system use. 126 * @since 11 127 */ 128 function unlock(callback: AsyncCallback<boolean>): void; 129 130 /** 131 * Unlock the screen. 132 * 133 * @returns { Promise<boolean> } the promise returned by the function. 134 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 135 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 136 * @syscap SystemCapability.MiscServices.ScreenLock 137 * @systemapi Hide this for inner system use. 138 * @since 9 139 */ 140 /** 141 * Unlock the screen. 142 * 143 * @returns { Promise<boolean> } the promise returned by the function. 144 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 145 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 146 * @throws { BusinessError } 13200003 - Invalid use. 147 * @syscap SystemCapability.MiscServices.ScreenLock 148 * @systemapi Hide this for inner system use. 149 * @since 11 150 */ 151 function unlock(): Promise<boolean>; 152 153 /** 154 * Lock the screen. 155 * 156 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 157 * @param { AsyncCallback<boolean> } callback - the callback of lock. 158 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 159 * <br>2. Incorrect parameter types. 160 * @throws { BusinessError } 201 - permission denied. 161 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 162 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 163 * @syscap SystemCapability.MiscServices.ScreenLock 164 * @systemapi Hide this for inner system use. 165 * @since 9 166 */ 167 function lock(callback: AsyncCallback<boolean>): void; 168 169 /** 170 * Lock the screen. 171 * 172 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 173 * @returns { Promise<boolean> } the promise returned by the function. 174 * @throws { BusinessError } 201 - permission denied. 175 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 176 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 177 * @syscap SystemCapability.MiscServices.ScreenLock 178 * @systemapi Hide this for inner system use. 179 * @since 9 180 */ 181 function lock(): Promise<boolean>; 182 183 /** 184 * Indicates the system event type related to the screenlock management service. 185 * 186 * @syscap SystemCapability.MiscServices.ScreenLock 187 * @systemapi Hide this for inner system use. 188 * @since 9 189 */ 190 /** 191 * Indicates the system event type related to the screenlock management service. Adding strongAuthChanged and screenLockDisabledChanged. 192 * 193 * @typedef {('beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | 'unlockScreen' 194 * | 'lockScreen' | 'beginExitAnimation' | 'beginSleep' | 'endSleep' | 'changeUser' | 'screenlockEnabled' | 'serviceRestart' 195 * | 'strongAuthChanged' | 'screenLockDisabledChanged')} 196 * @syscap SystemCapability.MiscServices.ScreenLock 197 * @systemapi Hide this for inner system use. 198 * @since 12 199 */ 200 type EventType = 201 'beginWakeUp' 202 | 'endWakeUp' 203 | 'beginScreenOn' 204 | 'endScreenOn' 205 | 'beginScreenOff' 206 | 'endScreenOff' 207 | 'unlockScreen' 208 | 'lockScreen' 209 | 'beginExitAnimation' 210 | 'beginSleep' 211 | 'endSleep' 212 | 'changeUser' 213 | 'screenlockEnabled' 214 | 'serviceRestart' 215 | 'strongAuthChanged' 216 | 'screenLockDisabledChanged'; 217 218 /** 219 * Indicates the strong authentication reason flags used to request. 220 * 221 * @enum { number } 222 * @syscap SystemCapability.MiscServices.ScreenLock 223 * @systemapi Hide this for inner system use. 224 * @since 12 225 */ 226 enum StrongAuthReasonFlags { 227 /** 228 * Indicates that there are no strong authentication reason flags. 229 * 230 * @syscap SystemCapability.MiscServices.ScreenLock 231 * @systemapi Hide this for inner system use. 232 * @since 12 233 */ 234 NONE = 0x00000000, 235 236 /** 237 * Indicates the strong authentication reason requested after boot. 238 * 239 * @syscap SystemCapability.MiscServices.ScreenLock 240 * @systemapi Hide this for inner system use. 241 * @since 12 242 */ 243 AFTER_BOOT = 0x00000001, 244 245 /** 246 * Indicates the strong authentication reason requested after timeout. 247 * 248 * @syscap SystemCapability.MiscServices.ScreenLock 249 * @systemapi Hide this for inner system use. 250 * @since 12 251 */ 252 AFTER_TIMEOUT = 0x00000002, 253 254 /** 255 * Indicates the strong authentication reason requested by active request. 256 * 257 * @syscap SystemCapability.MiscServices.ScreenLock 258 * @systemapi Hide this for inner system use. 259 * @since 12 260 */ 261 ACTIVE_REQUEST = 0x00000004, 262 263 /** 264 * Indicates the strong authentication reason requested by policy restriction. 265 * 266 * @syscap SystemCapability.MiscServices.ScreenLock 267 * @systemapi Hide this for inner system use. 268 * @since 12 269 */ 270 POLICY_RESTRICTION = 0x00000008 271 } 272 273 /** 274 * Indicates the screen lock authentication state. 275 * 276 * @enum { number } 277 * @syscap SystemCapability.MiscServices.ScreenLock 278 * @systemapi Hide this for inner system use. 279 * @since 12 280 */ 281 enum AuthState { 282 /** 283 * Indicates the screen lock is not authenticated. 284 * 285 * @syscap SystemCapability.MiscServices.ScreenLock 286 * @systemapi Hide this for inner system use. 287 * @since 12 288 */ 289 NOT_AUTHED = 0, 290 291 /** 292 * Indicates the screen lock is pre authenticated by credential. 293 * 294 * @syscap SystemCapability.MiscServices.ScreenLock 295 * @systemapi Hide this for inner system use. 296 * @since 12 297 */ 298 PRE_AUTHED_BY_CREDENTIAL = 1, 299 300 /** 301 * Indicates the screen lock is pre authenticated by fingerprint. 302 * 303 * @syscap SystemCapability.MiscServices.ScreenLock 304 * @systemapi Hide this for inner system use. 305 * @since 12 306 */ 307 PRE_AUTHED_BY_FINGERPRINT = 2, 308 309 /** 310 * Indicates the screen lock is pre authenticated by face. 311 * 312 * @syscap SystemCapability.MiscServices.ScreenLock 313 * @systemapi Hide this for inner system use. 314 * @since 12 315 */ 316 PRE_AUTHED_BY_FACE = 3, 317 318 /** 319 * Indicates the screen lock is authenticated by credential. 320 * 321 * @syscap SystemCapability.MiscServices.ScreenLock 322 * @systemapi Hide this for inner system use. 323 * @since 12 324 */ 325 AUTHED_BY_CREDENTIAL = 4, 326 327 /** 328 * Indicates the screen lock is authenticated by fingerprint. 329 * 330 * @syscap SystemCapability.MiscServices.ScreenLock 331 * @systemapi Hide this for inner system use. 332 * @since 12 333 */ 334 AUTHED_BY_FINGERPRINT = 5, 335 336 /** 337 * Indicates the screen lock is authenticated by face. 338 * 339 * @syscap SystemCapability.MiscServices.ScreenLock 340 * @systemapi Hide this for inner system use. 341 * @since 12 342 */ 343 AUTHED_BY_FACE = 6, 344 } 345 346 /** 347 * Indicates the system event type and parameter related to the screenlock management service. 348 * 349 * @typedef SystemEvent 350 * @syscap SystemCapability.MiscServices.ScreenLock 351 * @systemapi Hide this for inner system use. 352 * @since 9 353 */ 354 interface SystemEvent { 355 /** 356 * Indicates the system event type related to the screenlock management service. 357 * 358 * @type { EventType } 359 * @syscap SystemCapability.MiscServices.ScreenLock 360 * @systemapi Hide this for inner system use. 361 * @since 9 362 */ 363 eventType: EventType; 364 /** 365 * Identifies the customized extended parameter of an event. 366 * 367 * @type { string } 368 * @syscap SystemCapability.MiscServices.ScreenLock 369 * @systemapi Hide this for inner system use. 370 * @since 9 371 */ 372 params: string; 373 } 374 375 /** 376 * Register system event related to screen lock service. 377 * 378 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 379 * @param { Callback<SystemEvent> } callback - the callback of onSystemEvent. 380 * @returns { boolean } returns true if register system event is success, returns false otherwise. 381 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 382 * <br>2. Incorrect parameter types. 383 * @throws { BusinessError } 201 - permission denied. 384 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 385 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 386 * @syscap SystemCapability.MiscServices.ScreenLock 387 * @systemapi Hide this for inner system use. 388 * @since 9 389 */ 390 function onSystemEvent(callback: Callback<SystemEvent>): boolean; 391 392 /** 393 * The screen lock app sends the event to the screen lock service. 394 * 395 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 396 * @param { String } event - event type. 397 * @param { number } parameter - operation result of the event. 398 * @param { AsyncCallback<boolean> } callback - the callback of sendScreenLockEvent. 399 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 400 * <br>2. Incorrect parameter types. 401 * @throws { BusinessError } 201 - permission denied. 402 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 403 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 404 * @syscap SystemCapability.MiscServices.ScreenLock 405 * @systemapi Hide this for inner system use. 406 * @since 9 407 */ 408 function sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; 409 410 /** 411 * The screen lock app sends the event to the screen lock service. 412 * 413 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 414 * @param { String } event - event type. 415 * @param { number } parameter - operation result of the event. 416 * @returns { Promise<boolean> } the promise returned by the function. 417 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 418 * <br>2. Incorrect parameter types. 419 * @throws { BusinessError } 201 - permission denied. 420 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 421 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 422 * @syscap SystemCapability.MiscServices.ScreenLock 423 * @systemapi Hide this for inner system use. 424 * @since 9 425 */ 426 function sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; 427 428 /** 429 * Request strong authentication for os account local userId. 430 * 431 * @permission ohos.permission.ACCESS_SCREEN_LOCK 432 * @param { StrongAuthReasonFlags } reasonFlag - The strong authentication reason flag. 433 * @param { number } userId - Os account local userId. 434 * @returns { Promise<void> } the promise returned by the function. 435 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 436 * <br>2. Incorrect parameter types. 437 * @throws { BusinessError } 201 - permission denied. 438 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 439 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 440 * @syscap SystemCapability.MiscServices.ScreenLock 441 * @systemapi Hide this for inner system use. 442 * @since 12 443 */ 444 function requestStrongAuth(reasonFlag: StrongAuthReasonFlags, userId: number): Promise<void>; 445 446 /** 447 * Obtain strong authentication reason flags for os account local userId. 448 * 449 * @permission ohos.permission.ACCESS_SCREEN_LOCK 450 * @param { number } userId - Os account local userId. 451 * @returns { number } the strong authentication reason flags. 452 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 453 * <br>2. Incorrect parameter types. 454 * @throws { BusinessError } 201 - permission denied. 455 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 456 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 457 * @syscap SystemCapability.MiscServices.ScreenLock 458 * @systemapi Hide this for inner system use. 459 * @since 12 460 */ 461 function getStrongAuth(userId: number): number; 462 463 /** 464 * Disable screen lock showing for os account local userId. This only becomes effective when there is no password. 465 * 466 * @permission ohos.permission.ACCESS_SCREEN_LOCK 467 * @param { boolean } disable - disable or enable screen lock showing. 468 * @param { number } userId - Os account local userId. 469 * @returns { Promise<boolean> } the promise returned by the function. 470 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 471 * <br>2. Incorrect parameter types. 472 * @throws { BusinessError } 201 - permission denied. 473 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 474 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 475 * @syscap SystemCapability.MiscServices.ScreenLock 476 * @systemapi Hide this for inner system use. 477 * @since 12 478 */ 479 function setScreenLockDisabled(disable: boolean, userId: number): Promise<boolean>; 480 481 /** 482 * Check whether screen lock is disabled for os account local userId. 483 * 484 * @permission ohos.permission.ACCESS_SCREEN_LOCK 485 * @param { number } userId - Os account local userId. 486 * @returns { boolean } whether screen lock is disabled. 487 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 488 * <br>2. Incorrect parameter types. 489 * @throws { BusinessError } 201 - permission denied. 490 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 491 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 492 * @syscap SystemCapability.MiscServices.ScreenLock 493 * @systemapi Hide this for inner system use. 494 * @since 12 495 */ 496 function isScreenLockDisabled(userId: number): boolean; 497 498 /** 499 * Set the screen lock authentication state for os account local userId. 500 * 501 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 502 * @param { AuthState } state - the screen lock authentication state. 503 * @param { number } userId - Os account local userId. 504 * @param { Uint8Array } authToken - the authentication token for this state 505 * @returns { Promise<boolean> } the promise returned by the function. 506 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 507 * <br>2. Incorrect parameter types. 508 * @throws { BusinessError } 201 - permission denied. 509 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 510 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 511 * @syscap SystemCapability.MiscServices.ScreenLock 512 * @systemapi Hide this for inner system use. 513 * @since 12 514 */ 515 function setScreenLockAuthState(state: AuthState, userId: number, authToken: Uint8Array): Promise<boolean>; 516 517 /** 518 * Obtain the screen lock authentication state for os account local userId. 519 * 520 * @permission ohos.permission.ACCESS_SCREEN_LOCK 521 * @param { number } userId - Os account local userId. 522 * @returns { AuthState } the screen lock authentication state. 523 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 524 * <br>2. Incorrect parameter types. 525 * @throws { BusinessError } 201 - permission denied. 526 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 527 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 528 * @syscap SystemCapability.MiscServices.ScreenLock 529 * @systemapi Hide this for inner system use. 530 * @since 12 531 */ 532 function getScreenLockAuthState(userId: number): AuthState; 533 534 /** 535 * Check whether the device is currently locked and the screenlock requires an identity to authenticate and unlock. 536 * 537 * @param { number } userId - Os account local userId. 538 * @returns { boolean } Whether the device is currently locked. 539 * @throws { BusinessError } 202 - Permission verification failed, application which is not a system application uses system API. 540 * @throws { BusinessError } 13200002 - The screenlock management service is abnormal. 541 * @throws { BusinessError } 13200004 - The userId is not same as the caller, and is not allowed for the caller. 542 * @syscap SystemCapability.MiscServices.ScreenLock 543 * @systemapi Hide this for inner system use. 544 * @since 20 545 */ 546 function isDeviceLocked(userId: number): boolean; 547} 548 549export default screenLock;