1# @ohos.ability.screenLockFileManager (Sensitive Data Access Management Under Lock Screen) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @hongjin-li_admin--> 6<!--Designer: @JerryH1011--> 7<!--Tester: @leiyuqian--> 8<!--Adviser: @zengyawen--> 9 10Once 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. 11 12> **NOTE** 13> 14> 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. 15 16## Modules to Import 17 18```ts 19import { screenLockFileManager } from '@kit.AbilityKit'; 20``` 21 22## AccessStatus 23 24Enumerates the statuses for requesting access to sensitive data on the lock screen. 25 26 **System capability**: SystemCapability.Security.ScreenLockFileManager 27 28| Name | Value | Description | 29| -------------- | ---- | ------------------------ | 30| ACCESS_DENIED | -1 | Access to sensitive data on the lock screen is denied.| 31| ACCESS_GRANTED | 0 | Access to sensitive data on the lock screen is granted. | 32 33 34## ReleaseStatus 35 36Enumerates the statuses for releasing access permissions to sensitive data on the lock screen. 37 38 **System capability**: SystemCapability.Security.ScreenLockFileManager 39 40| Name| Value| Description| 41|-----------------|----|----| 42| RELEASE_DENIED | -1 | Release of access to sensitive data on the lock screen is denied.| 43| RELEASE_GRANTED | 0 | Release of access to sensitive data on the lock screen is granted. | 44 45## KeyStatus<sup>18+</sup> 46 47Enumerates the statuses for access permissions for sensitive data on the lock screen. 48 49 **System capability**: SystemCapability.Security.ScreenLockFileManager 50 51| Name| Value| Description| 52|-----------------|----|----| 53| KEY_NOT_EXIST | -2 | The application has not enabled sensitive data protection on the lock screen.| 54| KEY_RELEASED | -1 | The access permission for sensitive data on the lock screen has been released.| 55| KEY_EXIST | 0 | The application can access sensitive data on the lock screen. | 56 57## screenLockFileManager.acquireAccess 58 59acquireAccess(): AccessStatus 60 61Requests the permission to access the application's sensitive data on the lock screen. This API returns the result synchronously. Generally, sensitive data cannot be accessed once the screen is locked. However, you can call this API to access the application's sensitive data on the lock screen. 62 63**System capability**: SystemCapability.Security.ScreenLockFileManager 64 65**Return value** 66 67| Type | Description | 68| ----------------------------------------------------------- | ------------------------------------- | 69| [AccessStatus](#accessstatus) | State for requesting access to sensitive data on the lock screen.| 70 71**Error codes** 72 73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 74 75| ID| Error Message | 76| -------- | ------------------------------------------------------------ | 77| 801 | The specified SystemCapability name was not found. | 78| 29300002 | The system ability work abnormally. | 79| 29300003 | The application is not enabled the data protection under lock screen. | 80| 29300004 | File access is denied. | 81 82**Example** 83 84```ts 85// Request the permission to access sensitive data on the lock screen. 86import { screenLockFileManager } from '@kit.AbilityKit'; 87import { BusinessError } from '@kit.BasicServicesKit'; 88import { hilog } from '@kit.PerformanceAnalysisKit'; 89 90try { 91 let acquireStatus = screenLockFileManager.acquireAccess(); 92 if (acquireStatus === screenLockFileManager.AccessStatus.ACCESS_GRANTED) { 93 hilog.info(0x0000, 'testTag', 'acquireAccess successfully.'); 94 } 95} catch (err) { 96 let message = (err as BusinessError).message; 97 hilog.error(0x0000, 'testTag', 'acquireAccess failed: %{public}s', message); 98} 99``` 100 101## screenLockFileManager.releaseAccess 102 103releaseAccess(): ReleaseStatus 104 105Releases the permission to access the application's sensitive data on the lock screen. This API returns the result synchronously. 106 107**System capability**: SystemCapability.Security.ScreenLockFileManager 108 109**Return value** 110 111| Type | Description | 112| ------------------------------- | ------------------------------ | 113| [ReleaseStatus](#releasestatus) | State for releasing access permissions to sensitive data on the lock screen.| 114 115**Error codes** 116 117For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 118 119| ID| Error Message | 120| -------- | ------------------------------------------------------------ | 121| 801 | The specified SystemCapability name was not found. | 122| 29300002 | The system ability work abnormally. | 123| 29300003 | The application is not enabled the data protection under lock screen. | 124| 29300005 | File access was not acquired. | 125 126**Example** 127 128```ts 129// Release the permission to access sensitive data on the lock screen. 130import { screenLockFileManager } from '@kit.AbilityKit'; 131import { BusinessError } from '@kit.BasicServicesKit'; 132import { hilog } from '@kit.PerformanceAnalysisKit'; 133 134try { 135 let releaseStatus = screenLockFileManager.releaseAccess(); 136 if (releaseStatus === screenLockFileManager.ReleaseStatus.RELEASE_GRANTED) { 137 hilog.info(0x0000, 'testTag', 'releaseAccess successfully.'); 138 } 139} catch (err) { 140 let message = (err as BusinessError).message; 141 hilog.error(0x0000, 'testTag', 'releaseAccess failed: %{public}s', message); 142} 143``` 144 145## screenLockFileManager.queryAppKeyState<sup>18+</sup> 146 147queryAppKeyState(): KeyStatus 148 149Obtains the state of access permissions for the application's sensitive data on the lock screen. This API returns the result synchronously. 150 151**System capability**: SystemCapability.Security.ScreenLockFileManager 152 153**Return value** 154 155| Type | Description | 156| ------------------------------- | ------------------------------ | 157| [KeyStatus](#keystatus18) | State of access permissions for sensitive data on the lock screen.| 158 159**Error codes** 160 161For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 162 163| ID| Error Message | 164| -------- | ------------------------------------------------------------ | 165| 801 | The specified SystemCapability name was not found. | 166| 29300002 | The system ability work abnormally. | 167 168**Example** 169 170```ts 171// Obtain the state of access permissions for sensitive data on the lock screen. 172import { screenLockFileManager } from '@kit.AbilityKit'; 173import { BusinessError } from '@kit.BasicServicesKit'; 174import { hilog } from '@kit.PerformanceAnalysisKit'; 175 176try { 177 let keyStatus = screenLockFileManager.queryAppKeyState(); 178 if (keyStatus === screenLockFileManager.KeyStatus.KEY_NOT_EXIST) { 179 hilog.info(0x0000, 'testTag', 'Key does not exist.'); 180 } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_RELEASED) { 181 hilog.info(0x0000, 'testTag', 'Key has been released.'); 182 } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_EXIST) { 183 hilog.info(0x0000, 'testTag', 'Key exists.'); 184 } 185} catch (err) { 186 let message = (err as BusinessError).message; 187 hilog.error(0x0000, 'testTag', 'queryAppKeyState failed: %{public}s', message); 188} 189``` 190