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 * @syscap SystemCapability.MiscServices.ScreenLock 311 * @systemapi Hide this for inner system use. 312 * @since 9 313 */ 314 eventType: EventType; 315 /** 316 * Identifies the customized extended parameter of an event. 317 * 318 * @syscap SystemCapability.MiscServices.ScreenLock 319 * @systemapi Hide this for inner system use. 320 * @since 9 321 */ 322 params: string; 323 } 324 325 /** 326 * Register system event related to screen lock service. 327 * 328 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 329 * @param { Callback<SystemEvent> } callback - the callback of onSystemEvent. 330 * @returns { boolean } returns true if register system event is success, returns false otherwise. 331 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 332 * <br>2. Incorrect parameter types. 333 * @throws { BusinessError } 201 - permission denied. 334 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 335 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 336 * @syscap SystemCapability.MiscServices.ScreenLock 337 * @systemapi Hide this for inner system use. 338 * @since 9 339 */ 340 function onSystemEvent(callback: Callback<SystemEvent>): boolean; 341 342 /** 343 * The screen lock app sends the event to the screen lock service. 344 * 345 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 346 * @param { String } event - event type. 347 * @param { number } parameter - operation result of the event. 348 * @param { AsyncCallback<boolean> } callback - the callback of sendScreenLockEvent. 349 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 350 * <br>2. Incorrect parameter types. 351 * @throws { BusinessError } 201 - permission denied. 352 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 353 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 354 * @syscap SystemCapability.MiscServices.ScreenLock 355 * @systemapi Hide this for inner system use. 356 * @since 9 357 */ 358 function sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; 359 360 /** 361 * The screen lock app sends the event to the screen lock service. 362 * 363 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 364 * @param { String } event - event type. 365 * @param { number } parameter - operation result of the event. 366 * @returns { Promise<boolean> } the promise returned by the function. 367 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 368 * <br>2. Incorrect parameter types. 369 * @throws { BusinessError } 201 - permission denied. 370 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 371 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 372 * @syscap SystemCapability.MiscServices.ScreenLock 373 * @systemapi Hide this for inner system use. 374 * @since 9 375 */ 376 function sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; 377 378 /** 379 * Request strong authentication for os account local userId. 380 * 381 * @permission ohos.permission.ACCESS_SCREEN_LOCK 382 * @param { StrongAuthReasonFlags } reasonFlag - The strong authentication reason flag. 383 * @param { number } userId - Os account local userId. 384 * @returns { Promise<void> } the promise returned by the function. 385 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 386 * <br>2. Incorrect parameter types. 387 * @throws { BusinessError } 201 - permission denied. 388 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 389 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 390 * @syscap SystemCapability.MiscServices.ScreenLock 391 * @systemapi Hide this for inner system use. 392 * @since 12 393 */ 394 function requestStrongAuth(reasonFlag: StrongAuthReasonFlags, userId: number): Promise<void>; 395 396 /** 397 * Obtain strong authentication reason flags for os account local userId. 398 * 399 * @permission ohos.permission.ACCESS_SCREEN_LOCK 400 * @param { number } userId - Os account local userId. 401 * @returns { number } the strong authentication reason flags. 402 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 403 * <br>2. Incorrect parameter types. 404 * @throws { BusinessError } 201 - permission denied. 405 * @throws { BusinessError } 202 - permission verification failed. A non-system application calls a system API. 406 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 407 * @syscap SystemCapability.MiscServices.ScreenLock 408 * @systemapi Hide this for inner system use. 409 * @since 12 410 */ 411 function getStrongAuth(userId: number): number; 412 413 /** 414 * Disable screen lock showing for os account local userId. This only becomes effective when there is no password. 415 * 416 * @permission ohos.permission.ACCESS_SCREEN_LOCK 417 * @param { boolean } disable - disable or enable screen lock showing. 418 * @param { number } userId - Os account local userId. 419 * @returns { Promise<boolean> } the promise returned by the function. 420 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 421 * <br>2. Incorrect parameter types. 422 * @throws { BusinessError } 201 - permission denied. 423 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 424 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 425 * @syscap SystemCapability.MiscServices.ScreenLock 426 * @systemapi Hide this for inner system use. 427 * @since 12 428 */ 429 function setScreenLockDisabled(disable: boolean, userId: number): Promise<boolean>; 430 431 /** 432 * Check whether screen lock is disabled for os account local userId. 433 * 434 * @permission ohos.permission.ACCESS_SCREEN_LOCK 435 * @param { number } userId - Os account local userId. 436 * @returns { boolean } whether screen lock is disabled. 437 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 438 * <br>2. Incorrect parameter types. 439 * @throws { BusinessError } 201 - permission denied. 440 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 441 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 442 * @syscap SystemCapability.MiscServices.ScreenLock 443 * @systemapi Hide this for inner system use. 444 * @since 12 445 */ 446 function isScreenLockDisabled(userId: number): boolean; 447 448 /** 449 * Set the screen lock authentication state for os account local userId. 450 * 451 * @permission ohos.permission.ACCESS_SCREEN_LOCK_INNER 452 * @param { AuthState } state - the screen lock authentication state. 453 * @param { number } userId - Os account local userId. 454 * @param { Uint8Array } authToken - the authentication token for this state 455 * @returns { Promise<boolean> } the promise returned by the function. 456 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 457 * <br>2. Incorrect parameter types. 458 * @throws { BusinessError } 201 - permission denied. 459 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 460 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 461 * @syscap SystemCapability.MiscServices.ScreenLock 462 * @systemapi Hide this for inner system use. 463 * @since 12 464 */ 465 function setScreenLockAuthState(state: AuthState, userId: number, authToken: Uint8Array): Promise<boolean>; 466 467 /** 468 * Obtain the screen lock authentication state for os account local userId. 469 * 470 * @permission ohos.permission.ACCESS_SCREEN_LOCK 471 * @param { number } userId - Os account local userId. 472 * @returns { AuthState } the screen lock authentication state. 473 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 474 * <br>2. Incorrect parameter types. 475 * @throws { BusinessError } 201 - permission denied. 476 * @throws { BusinessError } 202 - permission verification failed, application which is not a system application uses system API. 477 * @throws { BusinessError } 13200002 - the screenlock management service is abnormal. 478 * @syscap SystemCapability.MiscServices.ScreenLock 479 * @systemapi Hide this for inner system use. 480 * @since 12 481 */ 482 function getScreenLockAuthState(userId: number): AuthState; 483} 484 485export default screenLock;