• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Persisting Temporary Permissions (ArkTS)
2<!--Kit: Core File Kit-->
3<!--Subsystem: FileManagement-->
4<!--Owner: @lvzhenjie; @hongjin-li_admin-->
5<!--Designer: @chenxi0605; @JerryH1011-->
6<!--Tester: @leiyuqian-->
7<!--Adviser: @foryourself-->
8
9## When to Use
10
11If 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.
12
13## Persisting a Temporary Permission Granted by Picker
14
15You 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).
16
171. When 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. After the application or device is restarted, the application still needs to call a Picker API to access the file or image.
18
192. Sometimes, 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. In this case, 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.
20
21Before persisting a temporary permission, ensure that:<br>The device must have the system capability SystemCapability.FileManagement.AppFileService.FolderAuthorization. You can use **canIUse()** to check whether the device has the required system capability.
22
23```ts
24if (!canIUse('SystemCapability.FileManagement.AppFileService.FolderAuthorization')) {
25    console.error('this api is not supported on this device');
26    return;
27}
28```
29
30**Required Permissions**<br>
31ohos.permission.FILE_ACCESS_PERSIST. For details about how to request the permission, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
32
33**Example**
34
35```ts
36import { BusinessError } from '@kit.BasicServicesKit';
37import { picker } from '@kit.CoreFileKit';
38import { fileShare } from '@kit.CoreFileKit';
39
40async function persistPermissionExample() {
41    try {
42        let DocumentSelectOptions = new picker.DocumentSelectOptions();
43        let documentPicker = new picker.DocumentViewPicker();
44        let uris = await documentPicker.select(DocumentSelectOptions);
45        let policyInfo: fileShare.PolicyInfo = {
46            uri: uris[0],
47            operationMode: fileShare.OperationMode.READ_MODE,
48        };
49        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
50        fileShare.persistPermission(policies).then(() => {
51            console.info("persistPermission successfully");
52        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
53            console.error("persistPermission failed with error message: " + err.message + ", error code: " + err.code);
54            if (err.code == 13900001 && err.data) {
55                for (let i = 0; i < err.data.length; i++) {
56                    console.error("error code : " + JSON.stringify(err.data[i].code));
57                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
58                    console.error("error reason : " + JSON.stringify(err.data[i].message));
59                }
60            }
61        });
62    } catch (error) {
63        let err: BusinessError = error as BusinessError;
64        console.error(`persistPermission failed with err, Error code: ${err.code}, message: ${err.message}`);
65    }
66}
67```
68
69> **NOTE**
70>
71> - You are advised to save the URI of the file with persistent permission for the related application locally to facilitate the subsequent activation.
72> - 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).
73> - Before persisting permissions, use **canIUse()** to check whether the device has the required system capability and permission.
74> - When an application is uninstalled, all the permission authorization data will be deleted. After the application is reinstalled, re-authorization is required.
75
76For details about how to persist a temporary permission using C/C++ APIs, see [OH_FileShare_PersistPermission](native-fileshare-guidelines.md).
77
78You 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.
79
80**Required Permissions**<br>
81ohos.permission.FILE_ACCESS_PERSIST. For details about how to request the permission, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
82
83**Example**
84
85```ts
86import { BusinessError } from '@kit.BasicServicesKit';
87import { picker } from '@kit.CoreFileKit';
88import { fileShare } from '@kit.CoreFileKit';
89
90async function revokePermissionExample() {
91    try {
92        let uri = "file://docs/storage/Users/username/tmp.txt";
93        let policyInfo: fileShare.PolicyInfo = {
94            uri: uri,
95            operationMode: fileShare.OperationMode.READ_MODE,
96        };
97        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
98        fileShare.revokePermission(policies).then(() => {
99            console.info("revokePermission successfully");
100        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
101            console.error("revokePermission failed with error message: " + err.message + ", error code: " + err.code);
102            if (err.code == 13900001 && err.data) {
103                for (let i = 0; i < err.data.length; i++) {
104                    console.error("error code : " + JSON.stringify(err.data[i].code));
105                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
106                    console.error("error reason : " + JSON.stringify(err.data[i].message));
107                }
108            }
109        });
110    } catch (error) {
111        let err: BusinessError = error as BusinessError;
112        console.error(`revokePermission failed with err, Error code: ${err.code}, message: ${err.message}`);
113    }
114}
115```
116
117> **NOTE**
118>
119> - The URI in the example comes from the permission persistence data stored for the application.
120> - You are advised to activate the persistent permissions based on service requirements. Do not activate all persistent permissions.
121> - Before persisting permissions, use **canIUse()** to check whether the device has the required system capability and permission.
122
123For details about how to revoke a persistent permission using C/C++ APIs, see [OH_FileShare_RevokePermission](native-fileshare-guidelines.md).
124
125## Activating a Persistent Permission for Accessing a File or Folder
126
127Each 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.
128
129**Required Permissions**<br>
130ohos.permission.FILE_ACCESS_PERSIST. For details about how to request the permission, see [Workflow for Requesting Permissions](../security/AccessToken/determine-application-mode.md).
131
132**Example**
133
134```ts
135import { BusinessError } from '@kit.BasicServicesKit';
136import { picker } from '@kit.CoreFileKit';
137import { fileShare } from '@kit.CoreFileKit';
138
139async function activatePermissionExample() {
140    try {
141        let uri = "file://docs/storage/Users/username/tmp.txt";
142        let policyInfo: fileShare.PolicyInfo = {
143            uri: uri,
144            operationMode: fileShare.OperationMode.READ_MODE,
145        };
146        let policies: Array<fileShare.PolicyInfo> = [policyInfo];
147        fileShare.activatePermission(policies).then(() => {
148            console.info("activatePermission successfully");
149        }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
150            console.error("activatePermission failed with error message: " + err.message + ", error code: " + err.code);
151            if (err.code == 13900001 && err.data) {
152                for (let i = 0; i < err.data.length; i++) {
153                    console.error("error code : " + JSON.stringify(err.data[i].code));
154                    console.error("error uri : " + JSON.stringify(err.data[i].uri));
155                    console.error("error reason : " + JSON.stringify(err.data[i].message));
156                    if (err.data[i].code == fileShare.PolicyErrorCode.PERMISSION_NOT_PERSISTED) {
157                        // Persist the permission for a file or folder and then activate it.
158                    }
159                }
160            }
161        });
162    } catch (error) {
163        let err: BusinessError = error as BusinessError;
164        console.error(`activatePermission failed with err, Error code: ${err.code}, message: ${err.message}`);
165    }
166}
167```
168
169> **NOTE**
170>
171> - The URI in the example comes from the permission persistence data stored for the application.
172> - You are advised to activate the persistent permissions based on service requirements. Do not activate all persistent permissions.
173> - If the activation fails because the permission has not been persisted, persist the permission first.
174> - Before persisting permissions, use **canIUse()** to check whether the device has the required system capability and permission.
175
176For details about how to activate a persistent permission using C/C++ APIs, see [OH_FileShare_ActivatePermission](native-fileshare-guidelines.md).
177