1# Persisting Temporary Permissions (ArkTS)
2
3## When to Use
4
5If an application accesses a file by using Picker, the permission for accessing the file will be automatically invalidated after the application exits or the device restarts. To retain the permission for accessing the file, you need to persist the temporarily granted permission.
6
7## Persisting a Temporary Permission Granted by Picker
8
9### Persisting a Temporary Permission
10You can use Picker to select a file or folder, and persist the temporary permission granted by Picker by using the API provided by [ohos.fileshare](../reference/apis-core-file-kit/js-apis-fileShare.md).
11
12When an application needs to temporarily access data in a user directory, for example, a communication application needs to send a user file or image, it calls [select()](../reference/apis-core-file-kit/js-apis-file-picker.md#select-3) of Picker to select the file or image to be sent. In this case, the application obtains the temporary permission for accessing the file or image. To access the file or image after the application or device is restarted, the application still needs to call a Picker API.
13
14Sometimes, an application needs to access a file or folder multiple times. For example, after editing a user file, a file editor application needs to select and open the file directly from the history records. To address this need, you can use Picker to select the file, and use [ohos.fileshare.persistPermission](../reference/apis-core-file-kit/js-apis-fileShare.md#filesharepersistpermission11) to persist the temporary permission granted by Picker.
15
16To persist a temporary permission: 
17- The device must have the SystemCapability.FileManagement.File.Environment.FolderObtain system capability. You can use **canIUse()** to check whether the device has the required system capability.
18
19```ts
20if (!canIUse('SystemCapability.FileManagement.File.Environment.FolderObtain')) {
21    console.error('this api is not supported on this device');
22    return;
23}
24```
25
26- The application must have the ohos.permission.FILE_ACCESS_PERSIST permission.
27  
28  The ohos.permission.FILE_ACCESS_PERSIST permission is of the system_basic Ability Privilege Level (APL) and is available only to the applications of the same or higher APL. To enable an application of the normal APL to have this permission, you need to declare the permission in the Access Control List (ACL). For details, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
29
30**Example**
31
32```ts
33import { BusinessError } from '@kit.BasicServicesKit';
34import { picker } from '@kit.CoreFileKit';
35import { fileShare } from '@kit.CoreFileKit';
36
37async function persistPermissionExample() {
38    try {
39        let DocumentSelectOptions = new picker.DocumentSelectOptions();
40        let documentPicker = new picker.DocumentViewPicker();
41        let uris = await documentPicker.select(DocumentSelectOptions);
42        let policyInfo: fileShare.PolicyInfo = {
43            uri: uris[0],
44            operationMode: fileShare.OperationMode.READ_MODE,
45        };
46        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
47        fileShare.persistPermission(policies).then(() => {
48            console.info("persistPermission successfully");
49        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
50            console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code);
51            if (err.code == 13900001 && err.data) {
52                for (let i = 0; i < err.data.length; i++) {
53                    console.error("error code : " + JSON.stringify(err.data[i].code));
54                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
55                    console.error("error reason : " + JSON.stringify(err.data[i].message));
56                }
57            }
58        });
59    } catch (error) {
60        let err: BusinessError = error as BusinessError;
61        console.error('persistPermission failed with err: ' + JSON.stringify(err));
62    }
63}
64```
65**NOTE**
66> - You are advised to save the URI of the file with persistent permission for the related application locally to facilitate the subsequent activation.
67> - The permission persistence data is also stored in the system database. After the application or device is restarted, the persistent permission can be used only after being activated. For details, see [Activating a Persistent Permission](#activating-a-persistent-permission-for-accessing-a-file-or-folder).
68> - The APIs used for persisting permissions are available only for 2-in-1 devices. You can use **canIUse()** to check whether the device has the required system capability. The caller must also have the required permissions.
69> - When an application is uninstalled, all the permission authorization data will be deleted. After the application is reinstalled, re-authorization is required.
70
71For details about how to persist a temporary permission using C/C++ APIs, see [OH_FileShare_PersistPermission](native-fileshare-guidelines.md).
72
73### Revoking a Temporary Permission
74You can use [ohos.fileshare.revokePermission](../reference/apis-core-file-kit/js-apis-fileShare.md#filesharerevokepermission11) to revoke the persistent permission from a file, and update the data stored in the application to delete the file URI from the recently accessed data.
75
76The caller must have the ohos.permission.FILE_ACCESS_PERSIST permission, which is of the system_basic APL and is available only to the applications of the same or higher APL. To enable an application of the normal APL to have this permission, you need to declare the permission in the Access Control List (ACL). For details, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
77
78**Example**
79
80```ts
81import { BusinessError } from '@kit.BasicServicesKit';
82import { picker } from '@kit.CoreFileKit';
83import { fileShare } from '@kit.CoreFileKit';
84
85async function revokePermissionExample() {
86    try {
87        let uri = "file://docs/storage/Users/username/tmp.txt";
88        let policyInfo: fileShare.PolicyInfo = {
89            uri: uri,
90            operationMode: fileShare.OperationMode.READ_MODE,
91        };
92        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
93        fileShare.revokePermission(policies).then(() => {
94            console.info("revokePermission successfully");
95        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
96            console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code);
97            if (err.code == 13900001 && err.data) {
98                for (let i = 0; i < err.data.length; i++) {
99                    console.error("error code : " + JSON.stringify(err.data[i].code));
100                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
101                    console.error("error reason : " + JSON.stringify(err.data[i].message));
102                }
103            }
104        });
105    } catch (error) {
106        let err: BusinessError = error as BusinessError;
107        console.error('revokePermission failed with err: ' + JSON.stringify(err));
108    }
109}
110```
111**NOTE**
112> - The URI in the example comes from the permission persistence data stored for the application.
113> - You are advised to activate the persistent permissions based on service requirements. Do not activate all persistent permissions.
114> - The APIs used for persisting permissions are available only for 2-in-1 devices. You can use **canIUse()** to check whether the device has the required system capability. The caller must also have the required permissions.
115
116For details about how to revoke temporary permission using C/C++ APIs, see [OH_FileShare_RevokePermission](native-fileshare-guidelines.md).
117
118## Activating a Persistent Permission for Accessing a File or Folder
119
120Each time an application is started, its persistent permissions have not been loaded to the memory. To make a persistent permission still valid after the application is restarted, use [ohos.fileshare.activatePermission](../reference/apis-core-file-kit/js-apis-fileShare.md#fileshareactivatepermission11) to activate the permission.
121
122The caller must have the ohos.permission.FILE_ACCESS_PERSIST permission, which is of the system_basic APL and is available only to the applications of the same or higher APL. To enable an application of the normal APL to have this permission, you need to declare the permission in the Access Control List (ACL). For details, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
123
124**Example**
125
126```ts
127import { BusinessError } from '@kit.BasicServicesKit';
128import { picker } from '@kit.CoreFileKit';
129import { fileShare } from '@kit.CoreFileKit';
130
131async function activatePermissionExample() {
132    try {
133        let uri = "file://docs/storage/Users/username/tmp.txt";
134        let policyInfo: fileShare.PolicyInfo = {
135            uri: uri,
136            operationMode: fileShare.OperationMode.READ_MODE,
137        };
138        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
139        fileShare.activatePermission(policies).then(() => {
140            console.info("activatePermission successfully");
141        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
142            console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code);
143            if (err.code == 13900001 && err.data) {
144                for (let i = 0; i < err.data.length; i++) {
145                    console.error("error code : " + JSON.stringify(err.data[i].code));
146                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
147                    console.error("error reason : " + JSON.stringify(err.data[i].message));
148                    if (err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED) {
149                        // Persist the permission for a file or folder and then activate it.
150                    }
151                }
152            }
153        });
154    } catch (error) {
155        let err: BusinessError = error as BusinessError;
156        console.error('activatePermission failed with err: ' + JSON.stringify(err));
157    }
158}
159```
160**NOTE**
161> - The URI in the example comes from the permission persistence data stored for the application.
162> - You are advised to activate the persistent permissions based on service requirements. Do not activate all persistent permissions.
163> - If the activation fails because the permission has not been persisted, persist the permission first.
164> - The APIs used for persisting permissions are available only for 2-in-1 devices. You can use **canIUse()** to check whether the device has the required system capability. The caller must also have the required permissions.
165
166For details about how to activate a persistent permission using C/C++ APIs, see [OH_FileShare_ActivatePermission](native-fileshare-guidelines.md).