# theme_screenlock_mgr

#### Introduction
Provide three-party APP with the ability to request unlockScreen, query the screenlock status, and query whether to set the screenlock password.
Provide screenOn callback, screenOff callback, screenSaver in and out callback, user switching callback, and screenlock manager service running status callback to the operation management

**subsystem architecture diagram**
![](figures/subsystem_architecture_zh.png "subsystem architecture diagram")

#### Warehouse path
/base/theme/screenlock_mgr

#### Introduction to framework code
/base/theme/screenlock_mgr
├── figures                  # architecture diagram
├── frameworks
│   ├── js/napi              # the js interface resolves to the napi interface
│   └── native               # interface provided for app
├── sa_profile               # module contains the config files of system services and processes
├── services                 # implementation of screenlock manager service
├── test                     # unit test of interface
└── utils                    # module contains log printing and constants for ordered commonEvent

#### JS APIs and instructions
1.   JS APIs
function isScreenLocked(callback: AsyncCallback<boolean>): void; query the screenlock status，callback mode
function isScreenLocked(): Promise<boolean>; void; query the screenlock status，Promise mode

function isSecureMode(callback: AsyncCallback<boolean>): void; query whether to set screenlock password (gesture, digital password, pin, SIM)，callback mode
function isSecureMode(): Promise<boolean>; query whether to set screenlock password (gesture, digital password, pin, SIM)，Promise mode

function unlockScreen(callback: AsyncCallback<void>): void; request unlockScreen，callback mode
function unlockScreen(): Promise<void>; request unlockScreen，Promise mode

2.  JS APIs instructions
// Import module
import screenLock from '@ohos.screenLock';

// query the screenlock status asynchronously with a Promise
screenLock.isScreenLocked()
      .then((value) => {
          console.log(`success to screenLock.isScreenLocked: ${value}`);
       }).catch((err) => {
          console.error(`failed to screenLock.isScreenLocked because ${err.message}`)
    });


// query the screenlock status asynchronously with a callback
screenLock.isScreenLocked((err, value) => {
     if (err) {
          console.error(`failed to screenLock.isScreenLocked because ${err.message}`);
           return;
         }
       console.log(`success to screenLock.isScreenLocked: ${value}`);
    });

#### Debugging method

1.   Compile command

./build.sh --product-name (Fill in the specific product name, such as：Hi3516DV300) --build-target screenlock_native

2.  push so file

in $root\out\ohos-arm-release\miscservices\screenlock_native，push libscreenlock_server.z.so libscreenlock_client.z.so
libscreenlock_utils.z.so to system/lib，and push libscreenlockability.z.so to system/lib/module/app下.make sure the four so files is readable at least.

3.  reboot

#### Participation contribution

1. Fork warehouse
2. Submission code
3. Create a new pull request
4. Commit is complete

# 锁屏管理服务

## 简介
### 内容介绍
锁屏管理服务是OpenHarmony中系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。

**图 1** 架构图

![](figures/subsystem_architecture_zh.png "子系统架构图")

### 框架图介绍
1.三方应用支持操作请求解锁、查询锁屏状态、查询是否设置锁屏密码接口调用。\
2.锁屏应用注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听等事件 \
3.框架层API用来处理三方应用和锁屏应用的js接口请求处理，NAPI层进行js调用的处理 \
4.框架层IDL用来处理NAPI接口向锁屏管理服务之间的桥梁，进行IPC通讯 \
5.锁屏管理服务用来处理三方应用和锁屏应用接口请求，并作出对应处理，提供相应的返回结果。

## 目录

```
/base/theme/screenlock_mgr
├── figures                  # 构架图
├── frameworks
│   ├── js/napi              # js接口解析成napi接口
│   └── native               # 对客户端提供的接口
├── sa_profile               # 组件包含的系统服务的配置文件和进程的配置文件
├── services                 # 锁屏管理服务实现
├── test                     # 接口的单元测试
└── utils                    # 组件包含日志打印和有序公共事件定义的常量
```

## 说明

### 接口说明

**表 1**   锁屏管理服务的主要方法说明

| 接口名                      | 描述                       |
| -------------------------- | -------------------------- |
| isScreenLocked(callback: AsyncCallback<boolean>): void; | 判断屏幕是否锁屏。callback方式 |
| isScreenLocked(): Promise<boolean>; | 判断屏幕是否锁屏。Promise方式 |
| isLocked(): boolean; | 判断屏幕是否锁屏。返回true表示屏幕已锁屏；返回false表示屏幕未锁屏。同步方式 |
| isSecureMode(callback: AsyncCallback<boolean>): void; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)。callback方式 |
| isSecureMode(): Promise<boolean>; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)。Promise方式 |
| isSecure(): boolean; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)。返回true表示当前设备的屏幕锁定安全；返回false表示当前设备的屏幕锁定不安全。同步方式 |
| unlockScreen(callback: AsyncCallback<void>): void; | 三方应用解锁屏幕。callback方式 |
| unlockScreen(): Promise<void>; | 三方应用解锁屏幕。Promise方式 |
| unlock(callback: AsyncCallback<boolean>): void; | 三方应用解锁屏幕。如果屏幕解锁成功，则返回true，否则返回false。callback方式 |
| unlock():Promise<boolean>; | 三方应用解锁屏幕。如果屏幕解锁成功，则返回true，否则返回false。Promise方式 |
| lock(callback: AsyncCallback<boolean>): void; | 系统API，锁定屏幕。如果屏幕锁定成功，则返回true，否则返回false。callback方式 |
| lock():Promise<boolean>; | 系统API，锁定屏幕。如果屏幕锁定成功，则返回true，否则返回false。Promise方式 |
| SystemEvent { eventType: EventType, params: string } | 定义了系统事件回调参数结构，包含事件类型以及string类型的参数 |
| onSystemEvent(callback: Callback<SystemEvent>): boolean; | 系统API，注册与系统屏幕锁定相关的系统事件。如果注册系统事件成功，则返回true，否则返回false。callback方式 |
| sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; | 系统API，锁屏应用给锁屏管理服务发送事件。callback方式 |
| sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; | 系统API，锁屏应用给锁屏管理服务发送事件。promise方式 |


**表 2**   EventType-事件类型说明

| 事件类型                     | 描述                       |
| -------------------------- | -------------------------- |
| beginWakeUp | 表示设备开始唤醒。 |
| endWakeUp | 表示设备结束唤醒。 |
| beginScreenOn | 表示设备开始亮屏。 |
| endScreenOn | 表示设备结束亮屏。 |
| beginScreenOff | 表示设备开始灭屏。 |
| endScreenOff | 表示设备结束灭屏。 |
| unlockScreen | 表示请求屏幕解锁。 |
| lockScreen | 表示请求屏幕锁定。 |
| beginExitAnimation | 表示开始退场动画。 |
| beginSleep | 表示设备开始休眠。 |
| endSleep | 表示设备结束休眠。 |
| changeUser | 表示切换用户。 |
| screenlockEnabled | 表示锁屏是否启用。 |
| serviceRestart | 表示锁屏服务进行重启。 |

### JS 接口使用示例

三方应用向锁屏管理服务进行查询屏幕锁屏状态

```js
导入模块
import screenLock from '@ohos.screenlock';

// Promise方式，在异步回调里面获取锁屏状态结果
screenLock.isScreenLocked()
    .then((data) => {
        // 异步回调打印查询锁屏状态的结果
        console.log(`Obtain whether the screen is locked successfully. result: ${data}`);
    }).catch((err) => {
        // 打印错误信息
        console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`)
});

// callback方式，在异步回调里面获取锁屏状态结果
screenLock.isScreenLocked((err, data) => {
    if (err) {
        // 打印错误信息
        console.error(`Failed to obtain whether the screen is locked, because: ${err.message}`)
        return;
        }
    // 打印查询锁屏状态的结果
    console.log(`Obtain whether the screen is locked successfully. result: ${data}`);
});

 // 同步方式里面获取锁屏状态结果。如果屏幕当前已锁定，则返回true，否则返回false
let isLocked = screenLock.isLocked();

```

判断当前设备的屏幕锁定是否安全

```js

// Promise方式，在异步回调里面获取当前设备的屏幕锁定是否安全结果
screenLock.isSecureMode().then((data) => {
    console.log(`Obtain whether the device is in secure mode successfully. result: ${data}`);
}).catch((err) => {
    console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`);
});

// callback方式，在异步回调里面获取当前设备的屏幕锁定是否安全结果
screenLock.isSecureMode((err, data)=>{
    if (err) {
        console.error(`Failed to obtain whether the device is in secure mode, because: ${err.message}`);
        return;
    }
    console.info(`Obtain whether the device is in secure mode successfully. result: ${data}`);
});

 // 同步方式里面获取当前设备的屏幕锁定是否安全结果。如果当前设备的屏幕锁定安全，则返回true，否则返回false
let isSecure = screenLock.isSecure();

```

锁定屏幕

```js

// Promise方式，在异步回调里面获取锁屏是否成功的结果
screenLock.lock().then((data) => {
    console.log(`lock the screen successfully. result: ${data}`);
}).catch((err) => {
    console.error(`Failed to lock the screen, because: ${err.message}`);
});

// callback方式，在异步回调里面获取锁屏是否成功的结果
screenLock.lock((err, data) => {
    if (err) {
        console.error(`Failed to lock the screen, because: ${err.message}`);
        return;
    }
    console.info(`lock the screen successfully. result: ${data}`);
});

```

锁屏应用注册事件说明:锁屏应用向锁屏管理服务注册相关监听事件

 ```js
try {
    let isSuccess = screenLock.onSystemEvent((event) => {
        console.log(`Register the system event which related to screenlock successfully. eventType: ${event.eventType}`)
    });
} catch (err) {
    console.error(`Failed to register the system event which related to screenlock, because: ${err.message}`)
}
 ```

三方应用向锁屏管理服务发起解锁屏幕请求

 ```js

// 三方应用callback方式调用请求解锁
screenLock.unlockScreen((err) => {
    if (err) {
        console.error(`Failed to unlock the screen, because: ${err.message}`);
        return;
    }
    console.info('unlock the screen success successfully.');
});

screenLock.unlock((err, data) => {
    if (err) {
        console.error(`Failed to unlock the screen, because: ${err.message}`);
        return;
    }
    console.info(`unlock the screen success successfully. result: ${data}`);
});

// 三方应用Promise方式调用请求解锁
screenLock.unlockScreen().then(() => {
    console.info('unlock the screen success successfully.');
}).catch((err) => {
    console.error(`Failed to unlock the screen, because: ${err.message}`);
});

screenLock.unlock().then((data) => {
    console.info(`unlock the screen success successfully. result: ${data}`);
}).catch((err) => {
    console.error(`Failed to unlock the screen, because: ${err.message}`);
});

```

## 相关仓

**主题框架子系统**

[theme\_screenlock_mgr](https://gitee.com/openharmony/theme_screenlock_mgr)