README.md
1# theme_screenlock_mgr
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/theme/screenlock_mgr
12
13#### Introduction to framework code
14/base/theme/screenlock_mgr
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/theme/screenlock_mgr
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
33## 说明
34
35### 接口说明
36
37**表 1** 锁屏管理服务的主要方法说明
38
39| 接口名 | 描述 |
40| -------------------------- | -------------------------- |
41| isScreenLocked(callback: AsyncCallback<boolean>): void; | 判断屏幕是否锁屏，callback方式 |
42| isScreenLocked(): Promise<boolean>; | 判断屏幕是否锁屏，Promise方式 |
43| isLocked(): boolean; | 判断屏幕是否锁屏。如果屏幕当前已锁定，则返回true，否则返回false，同步方式 |
44| isSecureMode(callback: AsyncCallback<boolean>): void; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，callback方式 |
45| isSecureMode(): Promise<boolean>; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，Promise方式 |
46| isSecure(): boolean; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)。如果当前设备的屏幕锁定安全，则返回true，否则返回false，同步方式 |
47| unlockScreen(callback: AsyncCallback<void>): void; | 三方应用解锁屏幕，callback方式 |
48| unlockScreen(): Promise<void>; | 三方应用解锁屏幕，Promise方式 |
49| unlock(callback: AsyncCallback<boolean>): void; | 三方应用解锁屏幕，如果屏幕解锁成功。则返回true，否则返回false，callback方式 |
50| unlock():Promise<boolean>; | 三方应用解锁屏幕，如果屏幕解锁成功。则返回true，否则返回false，Promise方式 |
51| lock(callback: AsyncCallback<boolean>): void; | 系统API，锁定屏幕。如果屏幕锁定成功，则返回true，否则返回false，callback方式 |
52| lock():Promise<boolean>; | 系统API，锁定屏幕。如果屏幕锁定成功，则返回true，否则返回false，Promise方式 |
53| SystemEvent { eventType: EventType, params: string } | 定义了系统事件回调参数结构，包含事件类型以及string类型的参数 |
54| onSystemEvent(callback: Callback<SystemEvent>): boolean; | 系统API，注册与系统屏幕锁定相关的系统事件。如果注册系统事件成功，则返回true，否则返回false，callback方式 |
55| sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback<boolean>): void; | 系统API，锁屏应用给锁屏管理服务发送事件,callback方式 |
56| sendScreenLockEvent(event: String, parameter: number): Promise<boolean>; | 系统API，锁屏应用给锁屏管理服务发送事件,promise方式 |
57
58
59**表 2** EventType-事件类型说明
60
61| 事件类型 | 描述 |
62| -------------------------- | -------------------------- |
63| beginWakeUp | 表示开始唤醒监听事件 |
64| endWakeUp | 表示结束唤醒监听事件 |
65| beginScreenOn | 表示开始亮屏监听事件 |
66| endScreenOn | 表示结束亮屏监听事件 |
67| beginScreenOff | 表示开始灭屏监听事件 |
68| endScreenOff | 表示结束灭屏监听事件 |
69| unlockScreen | 表示请求解锁监听事件 |
70| lockScreen | 表示请求锁定监听事件 |
71| beginExitAnimation | 表示开始退场监听事件 |
72| beginSleep | 表示开始休眠监听事件 |
73| endSleep | 表示结束休眠监听事件 |
74| changeUser | 表示切换用户监听事件 |
75| screenlockEnabled | 表示锁屏是否启用监听事件 |
76| serviceRestart | 表示服务重新启动监听事件 |
77
78### JS 接口使用示例
79
80三方应用向锁屏管理服务进行查询屏幕锁屏状态
81
82```js
83导入模块
84import screenLock from '@ohos.screenlock';
85
86//Promise方式，在异步回调里面获取锁屏状态结果
87screenLock.isScreenLocked()
88 .then((value) => {
89 //异步回调打印查询锁屏状态的结果
90 console.log(`success to screenLock.isScreenLocked: ${value}`);
91 }).catch((err) => {
92 //打印错误信息
93 console.error(`failed to screenLock.isScreenLocked because ${err.message}`)
94});
95
96//callback方式，在异步回调里面获取锁屏状态结果
97screenLock.isScreenLocked((err, value) => {
98 if (err) {
99 //打印错误信息
100 console.error(`failed to screenLock.isScreenLocked because ${err.message}`);
101 return;
102 }
103 //打印查询锁屏状态的结果
104 console.log(`success to screenLock.isScreenLocked: ${value}`);
105});
106
107 //同步方式里面获取锁屏状态结果，如果屏幕当前已锁定，则返回true，否则返回false
108 screenLock.isLocked();
109
110```
111
112判断当前设备的屏幕锁定是否安全
113
114```js
115
116//Promise方式，在异步回调里面获取是否安全结果
117screenlock.isSecureMode().then((data) => {
118 console.log('isSecureMode success: data->${JSON.stringify(data)}');
119}).catch((err) => {
120 console.error('isSecureMode fail, promise: err->${JSON.stringify(err)}');
121});
122
123//callback方式，在异步回调里面获取是否安全结果
124screenlock.isSecureMode((err, data)=>{
125 if (err) {
126 console.error('isSecureMode callback error -> ${JSON.stringify(err)}');
127 return;
128 }
129 console.info('isSecureMode callback success data -> ${JSON.stringify(err)}');
130});
131
132 //同步方式里面获取是否安全结果，如果当前设备的屏幕锁定安全，则返回true，否则返回false
133screenlock.isSecure();
134
135```
136
137锁定屏幕
138
139```js
140
141//Promise方式，在异步回调里面获取是否安全结果
142screenlock.lock().then(() => {
143 console.log('lock success');
144}).catch((err) => {
145 console.error('lock fail, promise: err->${JSON.stringify(err)}');
146});
147
148//callback方式，在异步回调里面获取是否安全结果
149screenlock.lock((err) => {
150 if (err) {
151 console.error('lock callback error -> ${JSON.stringify(err)}');
152 return;
153 }
154 console.info('lock callback success');
155});
156
157```
158
159锁屏应用注册事件说明:锁屏应用向锁屏管理服务注册相关监听事件
160
161 ```js
162let isSuccess = screenlock.onSystemEvent((err, event)=>{
163 console.log(`onSystemEvent:callback:${event.eventType}`)
164 if (err) {
165 console.log(`onSystemEvent callback error -> ${JSON.stringify(err)}`);
166 }
167});
168if (!isSuccess) {
169 console.log(`onSystemEvent result is false`)
170}
171 ```
172
173三方应用向锁屏管理服务发起解锁屏幕请求
174
175 ```js
176
177//三方应用callback方式调用请求解锁
178
179screenLock.unlockScreen((err, data) => {
180 console.log("Screenlock_Test_2300: send unlockScreen issue begin");
181 if (err) {
182 console.log("Screenlock_Test_2300: unlockScreen fail-->"+err);
183 return;
184 }
185 console.log("Screenlock_Test_2300: unlockScreen success-->"+data);
186});
187
188screenlock.unlock((err,data) => {
189 if (err) {
190 console.error('unlock error -> ${JSON.stringify(err)}');
191 return;
192 }
193 console.info('unlock success data -> ${JSON.stringify(data)}');
194});
195
196//三方应用Promise方式调用请求解锁
197
198screenLock.unlockScreen().then((data) => {
199 console.log("ScreenLock_Test_Promise_0500: unlockScreen success-->"+data);
200}).catch((error) => {
201 console.error("ScreenLock_Test_Promise_0500: unlockScreen fail--> " + error);
202});
203
204screenlock.unlock().then((data) => {
205 console.log('unlock success');
206}).catch((err) => {
207 console.error('unlock fail, : err->${JSON.stringify(err)}');
208});
209
210```
211
212## 相关仓
213
214**主题框架子系统**
215
216[theme\_screenlock_mgr](https://gitee.com/openharmony/theme_screenlock_mgr)
217
218
