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 NONE = 0x00000000, 231 232 /** 233 * Indicates the strong authentication reason requested after boot. 234 */ 235 AFTER_BOOT = 0x00000001, 236 237 /** 238 * Indicates the strong authentication reason requested after timeout. 239 */ 240 AFTER_TIMEOUT = 0x00000002, 241 242 /** 243 * Indicates the strong authentication reason requested by active request. 244 */ 245 ACTIVE_REQUEST = 0x00000004, 246 247 /** 248 * Indicates the strong authentication reason requested by policy restriction. 249 */ 250 POLICY_RESTRICTION = 0x00000008 251 } 252 253 /** 254 * Indicates the screen lock authentication state. 255 * 256 * @enum { number } 257 * @syscap SystemCapability.MiscServices.ScreenLock 258 * @systemapi Hide this for inner system use. 259 * @since 12 260 */ 261 enum AuthState { 262 /** 263 * Indicates the screen lock is not authenticated. 264 */ 265 NOT_AUTHED = 0, 266 267 /** 268 * Indicates the screen lock is pre authenticated by credential. 269 */ 270 PRE_AUTHED_BY_CREDENTIAL = 1, 271 272 /** 273 * Indicates the screen lock is pre authenticated by fingerprint. 274 */ 275 PRE_AUTHED_BY_FINGERPRINT = 2, 276 277 /** 278 * Indicates the screen lock is pre authenticated by face. 279 */ 280 PRE_AUTHED_BY_FACE = 3, 281 282 /** 283 * Indicates the screen lock is authenticated by credential. 284 */ 285 AUTHED_BY_CREDENTIAL = 4, 286 287 /** 288 * Indicates the screen lock is authenticated by fingerprint. 289 */ 290 AUTHED_BY_FINGERPRINT = 5, 291 292 /** 293 * Indicates the screen lock is authenticated by face. 294 */ 295 AUTHED_BY_FACE = 6, 296 } 297 298 /** 299 * Indicates the system event type and parameter related to the screenlock management service. 300 * 301 * @typedef SystemEvent 302 * @syscap SystemCapability.MiscServices.ScreenLock 303 * @systemapi Hide this for inner system use. 304 * @since 9 305 */ 306 interface SystemEvent { 307 /** 308 * Indicates the system event type related to the screenlock management service. 309 * 310 * @type { EventType } 311 * @syscap SystemCapability.MiscServices.ScreenLock 312 * @systemapi Hide this for inner system use. 313 * @since 9 314 */ 315 eventType: EventType; 316 /** 317 * Identifies the customized extended parameter of an event. 318 * 319 * @type { string } 320 * @syscap SystemCapability.MiscServices.ScreenLock 321 * @systemapi Hide this for inner system use. 322 * @since 9 323 */ 324 params: string; 325 } 326 327 /** 328 * Register system event related to screen lock service. 329 * 330 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 331 * @param { Callback<SystemEvent> } callback - the callback of onSystemEvent. 332 * @returns { boolean } returns true if register system event is success, returns false otherwise. 333 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 334 * <br>2. Incorrect parameter types. 335 * @throws { BusinessError } 201 - permission denied. 336 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 337 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 338 * @syscap SystemCapability.MiscServices.ScreenLock 339 * @systemapi Hide this for inner system use. 340 * @since 9 341 */ 342 function onSystemEvent(callback: Callback<SystemEvent>): boolean; 343 344 /** 345 * The screen lock app sends the event to the screen lock service. 346 * 347 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 348 * @param { String } event - event type. 349 * @param { number } parameter - operation result of the event. 350 * @param { AsyncCallback<boolean> } callback - the callback of sendScreenLockEvent. 351 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 352 * <br>2. Incorrect parameter types. 353 * @throws { BusinessError } 201 - permission denied. 354 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 355 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 356 * @syscap SystemCapability.MiscServices.ScreenLock 357 * @systemapi Hide this for inner system use. 358 * @since 9 359 */ 360 function sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; 361 362 /** 363 * The screen lock app sends the event to the screen lock service. 364 * 365 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 366 * @param { String } event - event type. 367 * @param { number } parameter - operation result of the event. 368 * @returns { Promise<boolean> } the promise returned by the function. 369 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 370 * <br>2. Incorrect parameter types. 371 * @throws { BusinessError } 201 - permission denied. 372 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 373 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 374 * @syscap SystemCapability.MiscServices.ScreenLock 375 * @systemapi Hide this for inner system use. 376 * @since 9 377 */ 378 function sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; 379 380 /** 381 * Request strong authentication for os account local userId. 382 * 383 * @permission ohos.permission.ACCESS_SCREEN_LOCK 384 * @param { StrongAuthReasonFlags } reasonFlag - The strong authentication reason flag. 385 * @param { number } userId - Os account local userId. 386 * @returns { Promise<void> } the promise returned by the function. 387 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 388 * <br>2. Incorrect parameter types. 389 * @throws { BusinessError } 201 - permission denied. 390 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 391 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 392 * @syscap SystemCapability.MiscServices.ScreenLock 393 * @systemapi Hide this for inner system use. 394 * @since 12 395 */ 396 function requestStrongAuth(reasonFlag: StrongAuthReasonFlags, userId: number): Promise<void>; 397 398 /** 399 * Obtain strong authentication reason flags for os account local userId. 400 * 401 * @permission ohos.permission.ACCESS_SCREEN_LOCK 402 * @param { number } userId - Os account local userId. 403 * @returns { number } the strong authentication reason flags. 404 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 405 * <br>2. Incorrect parameter types. 406 * @throws { BusinessError } 201 - permission denied. 407 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 408 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 409 * @syscap SystemCapability.MiscServices.ScreenLock 410 * @systemapi Hide this for inner system use. 411 * @since 12 412 */ 413 function getStrongAuth(userId: number): number; 414 415 /** 416 * Disable screen lock showing for os account local userId. This only becomes effective when there is no password. 417 * 418 * @permission ohos.permission.ACCESS_SCREEN_LOCK 419 * @param { boolean } disable - disable or enable screen lock showing. 420 * @param { number } userId - Os account local userId. 421 * @returns { Promise<boolean> } the promise returned by the function. 422 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 423 * <br>2. Incorrect parameter types. 424 * @throws { BusinessError } 201 - permission denied. 425 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 426 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 427 * @syscap SystemCapability.MiscServices.ScreenLock 428 * @systemapi Hide this for inner system use. 429 * @since 12 430 */ 431 function setScreenLockDisabled(disable: boolean, userId: number): Promise<boolean>; 432 433 /** 434 * Check whether screen lock is disabled for os account local userId. 435 * 436 * @permission ohos.permission.ACCESS_SCREEN_LOCK 437 * @param { number } userId - Os account local userId. 438 * @returns { boolean } whether screen lock is disabled. 439 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 440 * <br>2. Incorrect parameter types. 441 * @throws { BusinessError } 201 - permission denied. 442 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 443 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 444 * @syscap SystemCapability.MiscServices.ScreenLock 445 * @systemapi Hide this for inner system use. 446 * @since 12 447 */ 448 function isScreenLockDisabled(userId: number): boolean; 449 450 /** 451 * Set the screen lock authentication state for os account local userId. 452 * 453 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 454 * @param { AuthState } state - the screen lock authentication state. 455 * @param { number } userId - Os account local userId. 456 * @param { Uint8Array } authToken - the authentication token for this state 457 * @returns { Promise<boolean> } the promise returned by the function. 458 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 459 * <br>2. Incorrect parameter types. 460 * @throws { BusinessError } 201 - permission denied. 461 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 462 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 463 * @syscap SystemCapability.MiscServices.ScreenLock 464 * @systemapi Hide this for inner system use. 465 * @since 12 466 */ 467 function setScreenLockAuthState(state: AuthState, userId: number, authToken: Uint8Array): Promise<boolean>; 468 469 /** 470 * Obtain the screen lock authentication state for os account local userId. 471 * 472 * @permission ohos.permission.ACCESS_SCREEN_LOCK 473 * @param { number } userId - Os account local userId. 474 * @returns { AuthState } the screen lock authentication state. 475 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 476 * <br>2. Incorrect parameter types. 477 * @throws { BusinessError } 201 - permission denied. 478 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 479 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 480 * @syscap SystemCapability.MiscServices.ScreenLock 481 * @systemapi Hide this for inner system use. 482 * @since 12 483 */ 484 function getScreenLockAuthState(userId: number): AuthState; 485} 486 487export default screenLock;