• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.ability.screenLockFileManager (Sensitive Data Access Management Under Lock Screen)
2
3Once the screen is locked, the keys for sensitive data are destroyed, preventing any read or write operations on that data. These keys can be restored only after the screen is unlocked. To facilitate data access on the lock screen, the screenLockFileManager module has been introduced. This module provides APIs to request and release the permission to access sensitive data on the lock screen, thereby managing sensitive data access securely.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { screenLockFileManager } from '@kit.AbilityKit';
13```
14
15## AccessStatus
16
17Enumerates the statuses for requesting access to sensitive data on the lock screen.
18
19 **System capability**: SystemCapability.Security.ScreenLockFileManager
20
21| Name          | Value  | Description                    |
22| -------------- | ---- | ------------------------ |
23| ACCESS_DENIED  | -1   | Access to sensitive data on the lock screen is denied.|
24| ACCESS_GRANTED | 0    | Access to sensitive data on the lock screen is granted.    |
25
26
27## ReleaseStatus
28
29Enumerates the statuses for releasing access permissions to sensitive data on the lock screen.
30
31 **System capability**: SystemCapability.Security.ScreenLockFileManager
32
33| Name| Value| Description|
34|-----------------|----|----|
35| RELEASE_DENIED |  -1 | Release of access to sensitive data on the lock screen is denied.|
36| RELEASE_GRANTED |  0  |  Release of access to sensitive data on the lock screen is granted. |
37
38## screenLockFileManager.acquireAccess
39
40acquireAccess(): AccessStatus
41
42Requests the permission to access sensitive data on the lock screen. This API returns the result synchronously. Generally sensitive data cannot be accessed after the screen is locked. However, you can call this API to access sensitive data on the lock screen.
43
44**System capability**: SystemCapability.Security.ScreenLockFileManager
45
46**Return value**
47
48| Type                                                       | Description                                 |
49| ----------------------------------------------------------- | ------------------------------------- |
50| [AccessStatus](#accessstatus) | State for requesting access to sensitive data on the lock screen.|
51
52**Error codes**
53
54For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md).
55
56| ID| Error Message                                                    |
57| -------- | ------------------------------------------------------------ |
58| 801 | The specified SystemCapability name was not found. |
59| 29300002 | The system ability work abnormally. |
60| 29300003 | The application is not enabled the data protection under lock screen. |
61| 29300004 | File access is denied. |
62
63**Example**
64
65```ts
66// Request the permission to access sensitive data on the lock screen.
67import { screenLockFileManager } from '@kit.AbilityKit';
68import { BusinessError } from '@kit.BasicServicesKit';
69import { hilog } from '@kit.PerformanceAnalysisKit';
70
71try {
72    let acquireStatus = screenLockFileManager.acquireAccess();
73    if (acquireStatus === screenLockFileManager.AccessStatus.ACCESS_GRANTED) {
74        hilog.info(0x0000, 'testTag', 'acquireAccess successfully.');
75    }
76} catch (err) {
77    let message = (err as BusinessError).message;
78    hilog.error(0x0000, 'testTag', 'acquireAccess failed: %{public}s', message);
79}
80```
81
82## screenLockFileManager.releaseAccess
83
84releaseAccess(): ReleaseStatus
85
86Releases the permission to access sensitive data on the lock screen. This API returns the result synchronously.
87
88**System capability**: SystemCapability.Security.ScreenLockFileManager
89
90**Return value**
91
92| Type                           | Description                          |
93| ------------------------------- | ------------------------------ |
94| [ReleaseStatus](#releasestatus) | State for releasing access permissions to sensitive data on the lock screen.|
95
96**Error codes**
97
98For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md).
99
100| ID| Error Message                                                    |
101| -------- | ------------------------------------------------------------ |
102| 801      | The specified SystemCapability name was not found.           |
103| 29300002 | The system ability work abnormally.                          |
104| 29300003 | The application is not enabled the data protection under lock screen. |
105| 29300005 | File access was not acquired. |
106
107**Example**
108
109```ts
110// Release the permission to access sensitive data on the lock screen.
111import { screenLockFileManager } from '@kit.AbilityKit';
112import { BusinessError } from '@kit.BasicServicesKit';
113import { hilog } from '@kit.PerformanceAnalysisKit';
114
115try {
116    let releaseStatus = screenLockFileManager.releaseAccess();
117    if (releaseStatus === screenLockFileManager.ReleaseStatus.RELEASE_GRANTED) {
118        hilog.info(0x0000, 'testTag', 'releaseAccess successfully.');
119    }
120} catch (err) {
121    let message = (err as BusinessError).message;
122    hilog.error(0x0000, 'testTag', 'releaseAccess failed: %{public}s', message);
123}
124```
125