diff --git a/README_ZH.md b/README_ZH.md index 0c89409..9384ab6 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -1,223 +1,145 @@ -# 锁屏组件 - -- [简介](#section11660541593) -- [目录](#section161941989596) -- [说明](#section38521239153117) - - [js接口说明](#section11908203714422) - - [js接口使用说明](#section9938411124317) -- [编译调试](#section38521239153118) -- [相关仓](#section1371113476307) -- [参与贡献](#section1371113476308) - -## 简介 - -向三方应用提供请求解锁，查询锁屏状态，查询是否设置锁屏密码的能力。向应运行管理提供亮屏回调，灭屏回调，屏保进入退出回调，用户切换回调,锁屏管理服务运行状态回调 - -**图 1** 子系统架构图 -![](figures/subsystem_architecture_zh.png "子系统架构图") - - -## 目录 - -``` -/base/miscservices/screenlock -├── figures # 构架图 -├── frameworks/kitsimpl # 对应用提供的接口 -├── interfaces/kits # 组件对外提供的接口代码 -│ ├── jskits # 服务间接口 -│ └── napi # js接口解析成napi接口 -├── sa_profile # 组件包含的系统服务的配置文件和进程的配置文件 -├── services # 锁屏管理服务实现 -├── test # 接口的单元测试 -└── utils # 组件包含日志打印和有序公共事件定义的常量 -``` - -## 说明 - -1. js 接口使用说明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

接口名

-

描述

-

function isScreenLocked(callback: AsyncCallback): void;

-

判断屏幕是否锁屏，callback方式

-

function isScreenLocked(): Promise;

-

判断屏幕是否锁屏，Promise方式

-

function isSecureMode(callback: AsyncCallback): void;

-

判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，callback方式

-

function isSecureMode(): Promise;

-

判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，Promise方式

-

function unlockScreen(callback: AsyncCallback): void;

-

解锁屏幕，callback方式

-

function unlockScreen(): Promise;

-

解锁屏幕，Promise方式

-

function on(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | 'unlockScreen' | 'beginExitAnimation' | 'systemReady', callback: Callback): void;

-

注册系系统事件

-

function on(type: 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback): void;

-

注册系系统事件

-

function on(type: 'screenlockEnabled', callback: Callback): void;

-

注册系系统事件

-

function off(type: 'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | 'unlockScreen' | 'beginExitAnimation' | 'systemReady', callback: Callback): void;

-

取消注册系系统事件

-

function off(type: 'beginSleep' | 'endSleep' | 'changeUser', callback: Callback): void;): void;

-

取消注册系系统事件

-

function off(type: 'screenlockEnabled', callback: Callback): void;

-

取消注册系系统事件

-

function sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback): void;

-

锁屏应用给锁屏服务发送事件

-

function sendScreenLockEvent(event: String, parameter: number): Promise;

-

锁屏应用给锁屏服务发送事件

-
-2. js 接口使用说明 - -``` -// 导入模块 -import screenLock from '@ohos.screenlock'; - -// Promise方式的异步方法查询屏幕锁屏状态 -screenLock.isScreenLocked() - .then((value) => { - console.log(`success to screenLock.isScreenLocked: ${value}`); - }).catch((err) => { - console.error(`failed to screenLock.isScreenLocked because ${err.message}`) -}); - - -// callback方式的异步方法设置时间 -screenLock.isScreenLocked((err, value) => { - if (err) { - console.error(`failed to screenLock.isScreenLocked because ${err.message}`); - return; - } - console.log(`success to screenLock.isScreenLocked: ${value}`); -}); - -//注册系统事件 - -//'beginWakeUp' | 'endWakeUp' | 'beginScreenOn' | 'endScreenOn' | 'beginScreenOff' | 'endScreenOff' | -//'unlockScreen' | 'beginExitAnimation' | 'beginSleep' | 'endSleep' | 'changeUser' | 'screenlockEnabled' -var eventType = "beginWakeUp"; -screenLock.on(eventType, (err, value) => { - if (err) { - // 接口调用失败，err非空 - console.error(`screenlockOn_unlockScreen_callback failed, because ${err.message}`); - return; - } - // 接口调用成功，err为空 - console.log(`screenlockOn_unlockScreen_callback success to ${value} `); -}); - -//解锁屏幕 -screenLock.unlockScreen((err, data) => { - console.log("Screenlock_Test_2300: send unlockScreen issue success"); - if (err) { - console.log("Screenlock_Test_2300: unlockScreen fail-->"+err); - return; - } - console.log("Screenlock_Test_2300: unlockScreen success-->"+data); -}); - -screenLock.unlockScreen().then((data) => { - console.log("ScreenLock_Test_Promise_0500: unlockScreen success-->"+data); -}).catch((error) => { - console.error("ScreenLock_Test_Promise_0500: unlockScreen fail--> " + error); -}); -``` - -## 编译调试 - -1. 配置编译参数 -``` -1. 仓库代码下载下来，修改工程名为screenlock，放在源码 \base\miscservices 目录下 -``` -``` -2. OpenHarmony/productdefine/common/products/Hi3516DV300.json中在文件末尾添加 "miscservices:screenlock":{} -``` - -![](figures/step1.png "step 1") - -``` -3. 在foundation/distributedschedule/samgr/interfaces/innerkits/samgr_proxy/include 的system_ability_definition.h中添加自己服务的id:3704。 -信息：SCREENLOCK_SERVICE_ID = 3704, -``` - -![](figures/step2.png "step 2") - -``` - -2. 编译命令 - -``` -./build.sh --product-name (填写具体的产品名，如：Hi3516DV300) --build-target screenlock_native -``` - -3. 推送 so 文件 - -``` -将工程目录下out\ohos-arm-release\miscservices\screenlock_native下的libscreenlock_server.z.so libscreenlock_client.z.so -libscreenlock_utils.z.so三大so推送到system/lib， - -将libscreenlockability.z.so推送到system/lib/module/app下，并确保四个so至少为可读状态。 -``` - -4. 重启设备 -``` -## 相关仓 - -**Misc软件服务子系统** - -/base/miscservices/screenlock - -## 参与贡献 - -1. Fork 本仓库 -2. 提交代码 -3. 新建 Pull Request -4. commit 完成即可 +# 锁屏管理服务 + +## 简介 +### 内容介绍 +锁屏管理服务是OpenHarmony中系统服务，为锁屏应用提供注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听，并提供回调结果给锁屏应用。锁屏管理服务向三方应用提供请求解锁、查询锁屏状态、查询是否设置锁屏密码的能力。 + +**图 1** 架构图 + +![](figures/subsystem_architecture_zh.png "子系统架构图") + +### 框架图介绍 +1.三方应用支持操作请求解锁、查询锁屏状态、查询是否设置锁屏密码接口调用。\ +2.锁屏应用注册亮屏、灭屏、开启屏幕、结束休眠、退出动画、请求解锁结果监听等事件 \ +3.框架层API用来处理三方应用和锁屏应用的js接口请求处理，NAPI层进行js调用的处理 \ +4.框架层IDL用来处理NAPI接口向锁屏管理服务之间的桥梁，进行IPC通讯 \ +5.锁屏管理服务用来处理三方应用和锁屏应用接口请求，并作出对应处理，提供相应的返回结果。 + +## 目录 + +``` +/base/miscservices/screenlock +├── figures # 构架图 +├── frameworks/kitsimpl # 对应用提供的接口 +├── interfaces/kits # 组件对外提供的接口代码 +│ ├── jskits # 服务间接口 +│ └── napi # js接口解析成napi接口 +├── sa_profile # 组件包含的系统服务的配置文件和进程的配置文件 +├── services # 锁屏管理服务实现 +├── test # 接口的单元测试 +└── utils # 组件包含日志打印和有序公共事件定义的常量 +``` +## JS 接口说明 + +| 接口名 | 描述 | +| -------------------------- | -------------------------- | +| isScreenLocked(callback: AsyncCallback): void; | 判断屏幕是否锁屏，callback方式 | +| isScreenLocked(): Promise; | 判断屏幕是否锁屏，Promise方式 | +| isSecureMode(callback: AsyncCallback): void; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，callback方式 | +| isSecureMode(): Promise; | 判断当前设备的屏幕锁定是否安全(安全屏幕锁定意味着解锁屏幕需要密码、图案或其他用户身份识别)，Promise方式 | +| unlockScreen(callback: AsyncCallback): void; | 三方应用解锁屏幕，callback方式 | +| unlockScreen(): Promise; | 三方应用解锁屏幕，Promise方式 | +| on(type: 'beginWakeUp' , callback: Callback): void; | 锁屏应用注册开始唤醒监听事件 | +| on(type: 'endWakeUp' , callback: Callback): void; | 锁屏应用注册结束唤醒监听事件 | +| on(type: 'beginScreenOn' , callback: Callback): void; | 锁屏应用注册开始亮屏监听事件 | +| on(type: 'endScreenOn' , callback: Callback): void; | 锁屏应用注册结束亮屏监听事件 | +| on(type: 'beginScreenOff' , callback: Callback): void; | 锁屏应用注册开始灭屏监听事件 | +| on(type: 'endScreenOff' , callback: Callback): void; | 锁屏应用注册结束灭屏监听事件 | +| on(type: 'unlockScreen' , callback: Callback): void; | 锁屏应用注册请求解锁监听事件 | +| on(type: 'beginExitAnimation' , callback: Callback): void; | 锁屏应用注册开始退场监听事件 | +| on(type: 'systemReady' , callback: Callback): void; | 锁屏应用注册锁屏管理服务系统准备完成监听事件 | +| on(type: 'beginSleep' , callback: Callback): void; | 锁屏应用注册开始休眠监听事件 | +| on(type: 'endSleep' , callback: Callback): void; | 锁屏应用注册结束休眠监听事件 | +| on(type: 'changeUser', callback: Callback): void; | 锁屏应用注册切换用户监听事件 | +| on(type: 'screenlockEnabled', callback: Callback): void; | 锁屏应用注册锁屏是否启用监听事件 | +| off(type: 'beginWakeUp' , callback: Callback): void; | 锁屏应用取消开始唤醒监听事件 | +| off(type: 'endWakeUp' , callback: Callback): void; | 锁屏应用取消结束唤醒监听事件 | +| off(type: 'beginScreenOn' , callback: Callback): void; | 锁屏应用取消开始亮屏监听事件 | +| off(type: 'endScreenOn' , callback: Callback): void; | 锁屏应用取消结束亮屏监听事件 | +| off(type: 'beginScreenOff' , callback: Callback): void; | 锁屏应用取消开始灭屏监听事件 | +| off(type: 'endScreenOff' , callback: Callback): void; | 锁屏应用取消结束灭屏监听事件 | +| off(type: 'unlockScreen' , callback: Callback): void; | 锁屏应用取消请求解锁监听事件 | +| off(type: 'beginExitAnimation' , callback: Callback): void; | 锁屏应用取消开始退场监听事件 | +| off(type: 'systemReady', callback: Callback): void; | 锁屏应用取消锁屏管理服务系统准备完成监听事件 | +| off(type: 'beginSleep' , callback: Callback): void;): void; | 锁屏应用取消开始休眠监听事件 | +| off(type: 'endSleep' , callback: Callback): void;): void; | 锁屏应用取消结束休眠监听事件 | +| off(type: 'changeUser', callback: Callback): void;): void; | 锁屏应用取消切换用户监听事件 | +| off(type: 'screenlockEnabled', callback: Callback): void; | 锁屏应用取消锁屏是否启用监听事件 | +| sendScreenLockEvent(event: String, parameter: number, callback: AsyncCallback): void; | 锁屏应用给锁屏管理服务发送事件,callback方式 | +| sendScreenLockEvent(event: String, parameter: number): Promise; | 锁屏应用给锁屏管理服务发送事件,promise方式 | + +## JS 接口使用示例 + +```js +导入模块 +import screenLock from '@ohos.screenlock'; + +查询屏幕状态接口说明: 三方应用向锁屏管理服务进行查询屏幕锁屏状态 +//Promise方式，在异步回调里面获取锁屏状态结果 +screenLock.isScreenLocked() + .then((value) => { + //异步回调打印查询锁屏状态的结果 + console.log(`success to screenLock.isScreenLocked: ${value}`); + }).catch((err) => { + //打印错误信息 + console.error(`failed to screenLock.isScreenLocked because ${err.message}`) +}); +``` + + ```js + //callback方式，在异步回调里面获取锁屏状态结果 +screenLock.isScreenLocked((err, value) => { + if (err) { + //打印错误信息 + console.error(`failed to screenLock.isScreenLocked because ${err.message}`); + return; + } + //打印查询锁屏状态的结果 + console.log(`success to screenLock.isScreenLocked: ${value}`); +}); +``` + +锁屏应用注册事件说明:锁屏应用向锁屏管理服务注册相关监听事件 + +事件类型beginWakeUp示例代码如下 + ```js +var eventType = "beginWakeUp"; +screenLock.on(eventType, (err, value) => { + if (err) { + // 接口调用失败，打印错误信息 + console.error(`screenlockOn_unlockScreen_callback failed, because ${err.message}`); + return; + } + // 接口调用成功，打印返回信息 + console.log(`screenlockOn_unlockScreen_callback success to ${value} `); +}); + ``` + +三方应用向锁屏管理服务发起解锁屏幕请求 + ```js +//三方应用callback方式调用请求解锁 +screenLock.unlockScreen((err, data) => { + console.log("Screenlock_Test_2300: send unlockScreen issue begin"); + if (err) { + // 接口调用失败，打印错误信息 + console.log("Screenlock_Test_2300: unlockScreen fail-->"+err); + return; + } + // 接口调用成功，打印返回信息 + console.log("Screenlock_Test_2300: unlockScreen success-->"+data); +}); + +screenLock.unlockScreen().then((data) => { + // 接口调用成功，打印返回信息 + console.log("ScreenLock_Test_Promise_0500: unlockScreen success-->"+data); +}).catch((error) => { + // 接口调用失败，打印错误信息 + console.error("ScreenLock_Test_Promise_0500: unlockScreen fail--> " + error); +}); +``` + +## 相关仓 + +**Misc软件服务子系统** + + miscservices_screenlock