@ohos.screenLock (Screen Lock) (System API)

The 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.

NOTE

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.

This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.screenLock (Screen Lock).

Modules to Import

import screenLock from '@ohos.screenLock';

EventType⁹⁺

Defines the system event type.

System capability: SystemCapability.MiscServices.ScreenLock

System API: This is a system API.

SystemEvent⁹⁺

Defines the structure of the system event callback.

System capability: SystemCapability.MiscServices.ScreenLock

System API: This is a system API.

screenLock.isLocked⁹⁺

isLocked(): boolean

Checks whether the screen is locked.

System capability: SystemCapability.MiscServices.ScreenLock

System API: This is a system API.

Return value

Example

let isLocked = screenLock.isLocked();

screenLock.unlock⁹⁺

unlock(callback: AsyncCallback<boolean>): void

Unlocks the screen. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.ScreenLock

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.unlock((err: BusinessError, data: Boolean) => {
  if (err) {
    console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in unlocking the screen. result: ${data}`);
});

NOTE

The error code 13200003 illegal use is added since API version 11.

screenLock.unlock⁹⁺

unlock(): Promise<boolean>

Unlocks the screen. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.ScreenLock

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.unlock().then((data: Boolean) => {
  console.info(`Succeeded in unlocking the screen. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to unlock the screen, Code: ${err.code}, message: ${err.message}`);
});

NOTE

The error code 13200003 illegal use is added since API version 11.

screenLock.lock⁹⁺

lock(callback: AsyncCallback<boolean>): void

Locks the screen. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.ScreenLock

Required permissions: ohos.permission.ACCESS_SCREEN_LOCK_INNER

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.lock((err: BusinessError, data: Boolean) => {
  if (err) {
    console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in locking the screen. result: ${data}`);
});

screenLock.lock⁹⁺

lock(): Promise<boolean>

Locks the screen. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.ScreenLock

Required permissions: ohos.permission.ACCESS_SCREEN_LOCK_INNER

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.lock().then((data: Boolean) => {
  console.info(`Succeeded in locking the screen. result: ${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to lock the screen, Code: ${err.code}, message: ${err.message}`);
});

screenLock.onSystemEvent⁹⁺

onSystemEvent(callback: Callback<SystemEvent>): boolean

Registers a callback for system events related to screen locking. This API can be called only by screen lock applications.

System capability: SystemCapability.MiscServices.ScreenLock

Required permissions: ohos.permission.ACCESS_SCREEN_LOCK_INNER

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

try {
  let isSuccess = screenLock.onSystemEvent((event: screenLock.SystemEvent) => {
    console.log(`Succeeded in Registering the system event which related to screenlock. eventType: ${event.eventType}`)
  });
} catch (err) {
  let error = err as BusinessError;
  console.error(`Failed to register the system event which related to screenlock, Code: ${error.code}, message: ${error.message}`)
}

screenLock.sendScreenLockEvent⁹⁺

sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void

Sends 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.

System capability: SystemCapability.MiscServices.ScreenLock

Required permissions: ohos.permission.ACCESS_SCREEN_LOCK_INNER

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.sendScreenLockEvent('unlockScreenResult', 0, (err: BusinessError, result: Boolean) => {
  if (err) {
    console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.info(`Succeeded in Sending screenlock event. result: ${result}`);
});

screenLock.sendScreenLockEvent⁹⁺

sendScreenLockEvent(event: String, parameter: number): Promise<boolean>

Sends 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.

System capability: SystemCapability.MiscServices.ScreenLock

Required permissions: ohos.permission.ACCESS_SCREEN_LOCK_INNER

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see Screen Lock Management Error Codes.

Example

import { BusinessError } from '@ohos.base';

screenLock.sendScreenLockEvent('unlockScreenResult', 0).then((result: Boolean) => {
  console.info(`Succeeded in Sending screenlock event. result: ${result}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to send screenlock event, Code: ${err.code}, message: ${err.message}`);
});