1# @ohos.ability.screenLockFileManager (Sensitive Data Access Management Under Lock Screen) (System API) 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> - 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. 7> 8> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.ability.screenLockFileManager](js-apis-screenLockFileManager.md). 9 10## Modules to Import 11 12```ts 13import { screenLockFileManager } from '@kit.AbilityKit'; 14``` 15 16## DataType 17 18Enumerates the types of sensitive data that can be accessed on the lock screen. 19 20 **System capability**: SystemCapability.Security.ScreenLockFileManager 21 22 **System API**: This is a system API. 23 24| Name | Value | Description | 25| ---------- | ---------- | -------------- | 26| MEDIA_DATA | 0x00000001 | Media data.| 27| ALL_DATA | 0xffffffff | All encrypted data. | 28 29## screenLockFileManager.acquireAccess 30 31acquireAccess(dataType: DataType): AccessStatus 32 33Requests the permission to access a specified type of 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 sensitive data of the specified type on the lock screen. 34 35**System API**: This is a system API. 36 37**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_MEDIA_DATA or ohos.permission.ACCESS_SCREEN_LOCK_ALL_DATA 38 39**System capability**: SystemCapability.Security.ScreenLockFileManager 40 41**Parameters** 42 43| Name | Type | Mandatory| Description | 44| ----------- | ------ | ---- | ---------------------------- | 45| dataType | [DataType](#datatype) | Yes | Type of sensitive data that is accessible on the lock screen.| 46 47**Return value** 48 49| Type | Description | 50| ----------------------------------------------------------- | ------------------------------------- | 51| [AccessStatus](js-apis-screenLockFileManager.md#accessstatus) | State for requesting access to sensitive data on the lock screen.| 52 53**Error codes** 54 55For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 56 57| ID| Error Message | 58| -------- | ------------------------------------------------------------ | 59| 201 | Permission verification failed, usually returned by VerifyAccessToken. | 60| 202 | Permission verification failed, application which is not a system application uses system API. | 61| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 62| 801 | The specified SystemCapability name was not found. | 63| 29300001 | Invalid parameter. | 64| 29300002 | The system ability work abnormally. | 65| 29300003 | The application is not enabled the data protection under lock screen. | 66| 29300004 | File access is denied. | 67 68**Example** 69 70```ts 71// Request the permission to access media data on the lock screen. 72import { screenLockFileManager } from '@kit.AbilityKit'; 73import { BusinessError } from '@kit.BasicServicesKit'; 74import { hilog } from '@kit.PerformanceAnalysisKit'; 75 76try { 77 let acquireStatus = screenLockFileManager.acquireAccess(screenLockFileManager.DataType.MEDIA_DATA); 78 if (acquireStatus === screenLockFileManager.AccessStatus.ACCESS_GRANTED) { 79 hilog.info(0x0000, 'testTag', 'acquireAccess successfully.'); 80 } 81} catch (err) { 82 let message = (err as BusinessError).message; 83 hilog.error(0x0000, 'testTag', 'acquireAccess failed: %{public}s', message); 84} 85``` 86 87## screenLockFileManager.releaseAccess 88 89releaseAccess(dataType: DataType): ReleaseStatus 90 91Releases the permission to access a specified type of sensitive data on the lock screen. This API returns the result synchronously. 92 93**System API**: This is a system API. 94 95**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_MEDIA_DATA or ohos.permission.ACCESS_SCREEN_LOCK_ALL_DATA 96 97**System capability**: SystemCapability.Security.ScreenLockFileManager 98 99**Parameters** 100 101| Name | Type | Mandatory| Description | 102| ----------- | ------ | ---- | ---------------------------- | 103| dataType | [DataType](#datatype) | Yes | Type of sensitive data that is accessible on the lock screen.| 104 105**Return value** 106 107| Type | Description | 108| ------------------------------------------------------------ | ------------------------------ | 109| [ReleaseStatus](js-apis-screenLockFileManager.md#releasestatus) | State for releasing access permissions to sensitive data on the lock screen.| 110 111**Error codes** 112 113For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 114 115| ID| Error Message | 116| -------- | ------------------------------------------------------------ | 117| 201 | Permission verification failed, usually returned by VerifyAccessToken. | 118| 202 | Permission verification failed, application which is not a system application uses system API. | 119| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 120| 801 | The specified SystemCapability name was not found. | 121| 29300001 | Invalid parameter. | 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 media 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(screenLockFileManager.DataType.MEDIA_DATA); 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(dataType: DataType): KeyStatus 148 149Obtains the state of access permissions for a specified type of sensitive data on the lock screen. This API returns the result synchronously. 150 151**System API**: This is a system API. 152 153**Required permissions**: ohos.permission.ACCESS_SCREEN_LOCK_MEDIA_DATA or ohos.permission.ACCESS_SCREEN_LOCK_ALL_DATA 154 155**System capability**: SystemCapability.Security.ScreenLockFileManager 156 157**Parameters** 158 159| Name | Type | Mandatory| Description | 160| ----------- | ------ | ---- | ---------------------------- | 161| dataType | [DataType](#datatype) | Yes | Type of sensitive data that is accessible on the lock screen.| 162 163**Return value** 164 165| Type | Description | 166| ------------------------------------------------------------ | ------------------------------ | 167| [KeyStatus](js-apis-screenLockFileManager.md#keystatus18) | State of access permissions for sensitive data on the lock screen.| 168 169**Error codes** 170 171For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [ohos.screenLockFileManager](errorcode-screenLockFileManager.md). 172 173| ID| Error Message | 174| -------- | ------------------------------------------------------------ | 175| 201 | Permission verification failed, usually returned by VerifyAccessToken. | 176| 202 | Permission verification failed, application which is not a system application uses system API. | 177| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 178| 801 | The specified SystemCapability name was not found. | 179| 29300001 | Invalid parameter. | 180| 29300002 | The system ability work abnormally. | 181 182**Example** 183 184```ts 185// Obtain the state of access permissions for media data on the lock screen. 186import { screenLockFileManager } from '@kit.AbilityKit'; 187import { BusinessError } from '@kit.BasicServicesKit'; 188import { hilog } from '@kit.PerformanceAnalysisKit'; 189 190try { 191 let keyStatus = screenLockFileManager.queryAppKeyState(screenLockFileManager.DataType.MEDIA_DATA); 192 if (keyStatus === screenLockFileManager.KeyStatus.KEY_NOT_EXIST) { 193 hilog.info(0x0000, 'testTag', 'Key does not exist.'); 194 } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_RELEASED) { 195 hilog.info(0x0000, 'testTag', 'Key has been released.'); 196 } else if (keyStatus === screenLockFileManager.KeyStatus.KEY_EXIST) { 197 hilog.info(0x0000, 'testTag', 'Key exists.'); 198 } 199} catch (err) { 200 let message = (err as BusinessError).message; 201 hilog.error(0x0000, 'testTag', 'queryAppKeyState failed: %{public}s', message); 202} 203``` 204