• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.ability.screenLockFileManager (锁屏敏感数据管理)
2
3敏感数据密钥在锁屏后会触发销毁，销毁后敏感数据无法读写，需解锁屏幕触发恢复敏感数据密钥后方可访问。本模块提供应用锁屏下敏感数据保护的能力，支持申请和释放锁屏下敏感数据访问权限等。
4
5> **说明：**
6> 本模块首批接口从API version 12 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
7
8## 导入模块
9
10```ts
11import { screenLockFileManager } from '@kit.AbilityKit';
12```
13
14## AccessStatus
15
16枚举，锁屏下敏感数据访问权限申请的状态。
17
18 **系统能力：** SystemCapability.Security.ScreenLockFileManager
19
20| 名称           | 值   | 说明                     |
21| -------------- | ---- | ------------------------ |
22| ACCESS_DENIED  | -1   | 拒绝授予锁屏下敏感数据访问。 |
23| ACCESS_GRANTED | 0    | 授予锁屏下敏感数据访问。     |
24
25
26## ReleaseStatus
27
28枚举，锁屏下敏感数据访问权限释放的状态。
29
30 **系统能力：** SystemCapability.Security.ScreenLockFileManager
31
32| 名称 | 值 | 说明 |
33|-----------------|----|----|
34| RELEASE_DENIED |  -1 | 拒绝锁屏下敏感数据访问释放。 |
35| RELEASE_GRANTED |  0  |  释放锁屏下敏感数据访问。  |
36
37## KeyStatus<sup>18+</sup>
38
39枚举，锁屏下敏感数据访问权限的状态。
40
41 **系统能力：** SystemCapability.Security.ScreenLockFileManager
42
43| 名称 | 值 | 说明 |
44|-----------------|----|----|
45| KEY_NOT_EXIST |  -2 | 应用未开启锁屏敏感数据保护功能。 |
46| KEY_RELEASED |  -1 | 锁屏敏感数据访问权限已释放。 |
47| KEY_EXIST |  0  |  应用可以访问锁屏敏感数据。  |
48
49## screenLockFileManager.acquireAccess
50
51acquireAccess(): AccessStatus
52
53以同步方法申请锁屏下应用敏感数据访问权限。锁屏后，敏感数据无法被访问，但可通过调用该方法，访问指定类型的敏感数据。
54
55**系统能力：** SystemCapability.Security.ScreenLockFileManager
56
57**返回值：**
58
59| 类型                                                        | 说明                                  |
60| ----------------------------------------------------------- | ------------------------------------- |
61| [AccessStatus](#accessstatus) | 锁屏下敏感数据访问权限申请的状态。 |
62
63**错误码：**
64
65以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.screenLockFileManager错误码](errorcode-screenLockFileManager.md)。
66
67| 错误码ID | 错误信息                                                     |
68| -------- | ------------------------------------------------------------ |
69| 801 | The specified SystemCapability name was not found. |
70| 29300002 | The system ability work abnormally. |
71| 29300003 | The application is not enabled the data protection under lock screen. |
72| 29300004 | File access is denied. |
73
74**示例：**
75
76```ts
77// 申请锁屏下应用敏感数据访问权限
78import { screenLockFileManager } from '@kit.AbilityKit';
79import { BusinessError } from '@kit.BasicServicesKit';
80import { hilog } from '@kit.PerformanceAnalysisKit';
81
82try {
83    let acquireStatus = screenLockFileManager.acquireAccess();
84    if (acquireStatus === screenLockFileManager.AccessStatus.ACCESS_GRANTED) {
85        hilog.info(0x0000, 'testTag', 'acquireAccess successfully.');
86    }
87} catch (err) {
88    let message = (err as BusinessError).message;
89    hilog.error(0x0000, 'testTag', 'acquireAccess failed: %{public}s', message);
90}
91```
92
93## screenLockFileManager.releaseAccess
94
95releaseAccess(): ReleaseStatus
96
97以同步方法取消锁屏下应用敏感数据访问权限。
98
99**系统能力：** SystemCapability.Security.ScreenLockFileManager
100
101**返回值：**
102
103| 类型                            | 说明                           |
104| ------------------------------- | ------------------------------ |
105| [ReleaseStatus](#releasestatus) | 锁屏下敏感数据访问权限释放的状态。 |
106
107**错误码：**
108
109以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.screenLockFileManager错误码](errorcode-screenLockFileManager.md)。
110
111| 错误码ID | 错误信息                                                     |
112| -------- | ------------------------------------------------------------ |
113| 801      | The specified SystemCapability name was not found.           |
114| 29300002 | The system ability work abnormally.                          |
115| 29300003 | The application is not enabled the data protection under lock screen. |
116| 29300005 | File access was not acquired. |
117
118**示例：**
119
120```ts
121// 释放锁屏下应用敏感数据访问权限
122import { screenLockFileManager } from '@kit.AbilityKit';
123import { BusinessError } from '@kit.BasicServicesKit';
124import { hilog } from '@kit.PerformanceAnalysisKit';
125
126try {
127    let releaseStatus = screenLockFileManager.releaseAccess();
128    if (releaseStatus === screenLockFileManager.ReleaseStatus.RELEASE_GRANTED) {
129        hilog.info(0x0000, 'testTag', 'releaseAccess successfully.');
130    }
131} catch (err) {
132    let message = (err as BusinessError).message;
133    hilog.error(0x0000, 'testTag', 'releaseAccess failed: %{public}s', message);
134}
135```
136
137## screenLockFileManager.queryAppKeyState<sup>18+</sup>
138
139queryAppKeyState(): KeyStatus
140
141以同步方法查询锁屏下应用敏感数据访问权限。
142
143**系统能力：** SystemCapability.Security.ScreenLockFileManager
144
145**返回值：**
146
147| 类型                            | 说明                           |
148| ------------------------------- | ------------------------------ |
149| [KeyStatus](#keystatus18) | 锁屏下敏感数据访问权限的状态。 |
150
151**错误码：**
152
153以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[ohos.screenLockFileManager错误码](errorcode-screenLockFileManager.md)。
154
155| 错误码ID | 错误信息                                                     |
156| -------- | ------------------------------------------------------------ |
157| 801      | The specified SystemCapability name was not found.           |
158| 29300002 | The system ability work abnormally.                          |
159
160**示例：**
161
162```ts
163// 查询锁屏下应用敏感数据访问权限
164import { screenLockFileManager } from '@kit.AbilityKit';
165import { BusinessError } from '@kit.BasicServicesKit';
166import { hilog } from '@kit.PerformanceAnalysisKit';
167
168try {
169    let keyStatus = screenLockFileManager.queryAppKeyState();
170    if (keyStatus === screenLockFileManager.KeyStatus.KEY_NOT_EXIST) {
171        hilog.info(0x0000, 'testTag', 'Key does not exist.');
172    } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_RELEASED) {
173        hilog.info(0x0000, 'testTag', 'Key has been released.');
174    } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_EXIST) {
175        hilog.info(0x0000, 'testTag', 'Key exists.');
176    }
177} catch (err) {
178    let message = (err as BusinessError).message;
179    hilog.error(0x0000, 'testTag', 'queryAppKeyState failed: %{public}s', message);
180}
181```