README.md
1# miscservices_screenlock
2
3#### Introduction
4Provide three-party APP with the ability to request unlockScreen, query the screenlock status, and query whether to set the screenlock password.
5Provide screenOn callback, screenOff callback, screenSaver in and out callback, user switching callback, and screenlock manager service running status callback to the operation management
6
7**subsystem architecture diagram**
8
9
10#### Warehouse path
11/base/miscservices/screenlock
12
13#### Introduction to framework code
14/base/miscservices/screenlock
15├── figures # architecture diagram
16├── frameworks/innerkitsimpl # interface provided for app
17├── interfaces # interface code provided by module
18│ ├── innerkits # inter service interface
19│ └── kits # napi interface
20├── sa_profile # module contains the config files of system services and processes
21├── services # implementation of screenlock manager service
22├── test # unit test of interface
23└── utils # module contains log printing and constants for ordered commonEvent
24
25#### JS APIs and instructions
261. JS APIs
27function isScreenLocked(callback: AsyncCallback<boolean>): void; query the screenlock status，callback mode
28function isScreenLocked(): Promise<boolean>; void; query the screenlock status，Promise mode
29
30function isSecureMode(callback: AsyncCallback<boolean>): void; query whether to set screenlock password (gesture, digital password, pin, SIM)，callback mode
31function isSecureMode(): Promise<boolean>; query whether to set screenlock password (gesture, digital password, pin, SIM)，Promise mode
32
33function unlockScreen(callback: AsyncCallback<void>): void; request unlockScreen，callback mode
34function unlockScreen(): Promise<void>; request unlockScreen，Promise mode
35
362. JS APIs instructions
37// Import module
38import screenLock from '@ohos.screenLock';
39
40// query the screenlock status asynchronously with a Promise
41screenLock.isScreenLocked()
42 .then((value) => {
43 console.log(`success to screenLock.isScreenLocked: ${value}`);
44 }).catch((err) => {
45 console.error(`failed to screenLock.isScreenLocked because ${err.message}`)
46 });
47
48
49// query the screenlock status asynchronously with a callback
50screenLock.isScreenLocked((err, value) => {
51 if (err) {
52 console.error(`failed to screenLock.isScreenLocked because ${err.message}`);
53 return;
54 }
55 console.log(`success to screenLock.isScreenLocked: ${value}`);
56 });
57
58#### Debugging method
59
601. Compile command
61
62./build.sh --product-name (Fill in the specific product name, such as：Hi3516DV300) --build-target screenlock_native
63
642. push so file
65
66in $root\out\ohos-arm-release\miscservices\screenlock_native，push libscreenlock_server.z.so libscreenlock_client.z.so
67libscreenlock_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.
68
693. reboot
70
71#### Participation contribution
72
731. Fork warehouse
742. Submission code
753. Create a new pull request
764. Commit is complete
77
78
README_ZH.md
1# 锁屏管理服务
2
3## 简介
4### 内容介绍
5锁屏管理服务是OpenHarmony中系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。
6
7**图 1** 架构图
8
9
10
11### 框架图介绍
121.三方应用支持操作请求解锁、查询锁屏状态、查询是否设置锁屏密码接口调用。\
132.锁屏应用注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听等事件 \
143.框架层API用来处理三方应用和锁屏应用的js接口请求处理，NAPI层进行js调用的处理 \
154.框架层IDL用来处理NAPI接口向锁屏管理服务之间的桥梁，进行IPC通讯 \
165.锁屏管理服务用来处理三方应用和锁屏应用接口请求，并作出对应处理，提供相应的返回结果。
17
18## 目录
19
20```
21/base/miscservices/screenlock
22├── figures # 构架图
23├── frameworks/kitsimpl # 对应用提供的接口
24├── interfaces/kits # 组件对外提供的接口代码
25│ ├── jskits # 服务间接口
26│ └── napi # js接口解析成napi接口
27├── sa_profile # 组件包含的系统服务的配置文件和进程的配置文件
28├── services # 锁屏管理服务实现
29├── test # 接口的单元测试
30└── utils # 组件包含日志打印和有序公共事件定义的常量
31```
32## JS 接口说明
33
34| 接口名 | 描述 |
35| -------------------------- | -------------------------- |
36| isScreenLocked(callback: AsyncCallback<boolean>): void; | 判断屏幕是否锁屏，callback方式 |
37| isScreenLocked(): Promise<boolean>; | 判断屏幕是否锁屏，Promise方式 |
38| isSecureMode(callback: AsyncCallback<boolean>): void; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，callback方式 |
39| isSecureMode(): Promise<boolean>; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，Promise方式 |
40| unlockScreen(callback: AsyncCallback<void>): void; | 三方应用解锁屏幕，callback方式 |
41| unlockScreen(): Promise<void>; | 三方应用解锁屏幕，Promise方式 |
42| on(type: 'beginWakeUp' , callback: Callback<void>): void; | 锁屏应用注册开始唤醒监听事件 |
43| on(type: 'endWakeUp' , callback: Callback<void>): void; | 锁屏应用注册结束唤醒监听事件 |
44| on(type: 'beginScreenOn' , callback: Callback<void>): void; | 锁屏应用注册开始亮屏监听事件 |
45| on(type: 'endScreenOn' , callback: Callback<void>): void; | 锁屏应用注册结束亮屏监听事件 |
46| on(type: 'beginScreenOff' , callback: Callback<void>): void; | 锁屏应用注册开始灭屏监听事件 |
47| on(type: 'endScreenOff' , callback: Callback<void>): void; | 锁屏应用注册结束灭屏监听事件 |
48| on(type: 'unlockScreen' , callback: Callback<void>): void; | 锁屏应用注册请求解锁监听事件 |
49| on(type: 'beginExitAnimation' , callback: Callback<void>): void; | 锁屏应用注册开始退场监听事件 |
50| on(type: 'systemReady' , callback: Callback<void>): void; | 锁屏应用注册锁屏管理服务系统准备完成监听事件 |
51| on(type: 'beginSleep' , callback: Callback<number>): void; | 锁屏应用注册开始休眠监听事件 |
52| on(type: 'endSleep' , callback: Callback<number>): void; | 锁屏应用注册结束休眠监听事件 |
53| on(type: 'changeUser', callback: Callback<number>): void; | 锁屏应用注册切换用户监听事件 |
54| on(type: 'screenlockEnabled', callback: Callback<boolean>): void; | 锁屏应用注册锁屏是否启用监听事件 |
55| off(type: 'beginWakeUp' , callback: Callback<void>): void; | 锁屏应用取消开始唤醒监听事件 |
56| off(type: 'endWakeUp' , callback: Callback<void>): void; | 锁屏应用取消结束唤醒监听事件 |
57| off(type: 'beginScreenOn' , callback: Callback<void>): void; | 锁屏应用取消开始亮屏监听事件 |
58| off(type: 'endScreenOn' , callback: Callback<void>): void; | 锁屏应用取消结束亮屏监听事件 |
59| off(type: 'beginScreenOff' , callback: Callback<void>): void; | 锁屏应用取消开始灭屏监听事件 |
60| off(type: 'endScreenOff' , callback: Callback<void>): void; | 锁屏应用取消结束灭屏监听事件 |
61| off(type: 'unlockScreen' , callback: Callback<void>): void; | 锁屏应用取消请求解锁监听事件 |
62| off(type: 'beginExitAnimation' , callback: Callback<void>): void; | 锁屏应用取消开始退场监听事件 |
63| off(type: 'systemReady', callback: Callback<void>): void; | 锁屏应用取消锁屏管理服务系统准备完成监听事件 |
64| off(type: 'beginSleep' , callback: Callback<number>): void;<boolean>): void; | 锁屏应用取消开始休眠监听事件 |
65| off(type: 'endSleep' , callback: Callback<number>): void;<boolean>): void; | 锁屏应用取消结束休眠监听事件 |
66| off(type: 'changeUser', callback: Callback<number>): void;<boolean>): void; | 锁屏应用取消切换用户监听事件 |
67| off(type: 'screenlockEnabled', callback: Callback<boolean>): void; | 锁屏应用取消锁屏是否启用监听事件 |
68| sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; | 锁屏应用给锁屏管理服务发送事件,callback方式 |
69| sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; | 锁屏应用给锁屏管理服务发送事件,promise方式 |
70
71## JS 接口使用示例
72
73```js
74导入模块
75import screenLock from '@ohos.screenlock';
76
77查询屏幕状态接口说明: 三方应用向锁屏管理服务进行查询屏幕锁屏状态
78//Promise方式，在异步回调里面获取锁屏状态结果
79screenLock.isScreenLocked()
80 .then((value) => {
81 //异步回调打印查询锁屏状态的结果
82 console.log(`success to screenLock.isScreenLocked: ${value}`);
83 }).catch((err) => {
84 //打印错误信息
85 console.error(`failed to screenLock.isScreenLocked because ${err.message}`)
86});
87```
88
89 ```js
90 //callback方式，在异步回调里面获取锁屏状态结果
91screenLock.isScreenLocked((err, value) => {
92 if (err) {
93 //打印错误信息
94 console.error(`failed to screenLock.isScreenLocked because ${err.message}`);
95 return;
96 }
97 //打印查询锁屏状态的结果
98 console.log(`success to screenLock.isScreenLocked: ${value}`);
99});
100```
101
102锁屏应用注册事件说明:锁屏应用向锁屏管理服务注册相关监听事件
103
104事件类型beginWakeUp示例代码如下
105 ```js
106var eventType = "beginWakeUp";
107screenLock.on(eventType, (err, value) => {
108 if (err) {
109 // 接口调用失败，打印错误信息
110 console.error(`screenlockOn_unlockScreen_callback failed, because ${err.message}`);
111 return;
112 }
113 // 接口调用成功，打印返回信息
114 console.log(`screenlockOn_unlockScreen_callback success to ${value} `);
115});
116 ```
117
118三方应用向锁屏管理服务发起解锁屏幕请求
119 ```js
120//三方应用callback方式调用请求解锁
121screenLock.unlockScreen((err, data) => {
122 console.log("Screenlock_Test_2300: send unlockScreen issue begin");
123 if (err) {
124 // 接口调用失败，打印错误信息
125 console.log("Screenlock_Test_2300: unlockScreen fail-->"+err);
126 return;
127 }
128 // 接口调用成功，打印返回信息
129 console.log("Screenlock_Test_2300: unlockScreen success-->"+data);
130});
131
132screenLock.unlockScreen().then((data) => {
133 // 接口调用成功，打印返回信息
134 console.log("ScreenLock_Test_Promise_0500: unlockScreen success-->"+data);
135}).catch((error) => {
136 // 接口调用失败，打印错误信息
137 console.error("ScreenLock_Test_Promise_0500: unlockScreen fail--> " + error);
138});
139```
140
141## 相关仓
142
143**Misc软件服务子系统**
144
145 miscservices_screenlock
146
