• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Persisting Temporary Permissions (C/C++)
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 permission](file-persistPermission.md#when-to-use). You can use the **FileShare** module to manage persistent permissions on files or directories based on their URIs, including activating, deactivating, and checking these permissions.
12
13## Available APIs
14
15For details about the APIs, see [API Reference](../reference/apis-core-file-kit/capi-oh-file-share-h.md).
16
17| API| Description|
18| -------- | -------- |
19| OH_FileShare_PersistPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, FileShare_PolicyErrorResult **result, unsigned int *resultNum) | Persists the permissions on files or directories.|
20| OH_FileShare_RevokePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, FileShare_PolicyErrorResult **result, unsigned int *resultNum) | Revokes the permissions from files or directories.|
21| OH_FileShare_ActivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, FileShare_PolicyErrorResult **result, unsigned int *resultNum) | Activates the persistent permissions on files or directories.|
22| OH_FileShare_DeactivatePermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, FileShare_PolicyErrorResult **result, unsigned int *resultNum) | Deactivates the persistent permissions on files or directories.|
23| OH_FileShare_CheckPersistentPermission(const FileShare_PolicyInfo *policies, unsigned int policyNum, bool **result, unsigned int *resultNum) | Checks the persistent permissions on files or directories.|
24| OH_FileShare_ReleasePolicyErrorResult(FileShare_PolicyErrorResult *errorResult, unsigned int resultNum) | Releases the memory allocated for **FileShare_PolicyErrorResult**.|
25
26## Constraints
27
28- Before using the **FileShare** APIs, check that your device has SystemCapability.FileManagement.AppFileService.FolderAuthorization.
29
30- To call **FileShare** APIs, the application must have the ohos.permission.FILE_ACCESS_PERSIST permission. For details about how to request the permission, see [Workflow for Using Permissions](../security/AccessToken/determine-application-mode.md).
31
32## How to Develop
33
34The following example describes how to use the `FileShare` APIs.
35
36**Adding the Dynamic Link Library**
37
38Add the following library to **CMakeLists.txt**.
39
40```txt
41target_link_libraries(sample PUBLIC libohfileshare.so)
42```
43
44**Including Header Files**
45
46```c++
47#include <filemanagement/fileshare/oh_file_share.h>
48#include <iostream>
49```
501. Create a **FileShare_PolicyInfo** instance, and use **OH_FileShare_PersistPermission** to persist the permissions on files based on their URI. The maximum value of **policyNum** is **500**.
51    ```c++
52    static const uint32_t POLICY_NUM = 2;
53    char strTestPath1[] = "file://com.example.fileshare/data/storage/el2/base/files/test1.txt";
54    char strTestPath2[] = "file://com.example.fileshare/data/storage/el2/base/files/test2.txt";
55    FileShare_PolicyInfo policy[POLICY_NUM] = {
56        {strTestPath1, static_cast<unsigned int>(strlen(strTestPath1)), FileShare_OperationMode::READ_MODE},
57        {strTestPath2, static_cast<unsigned int>(strlen(strTestPath2)), FileShare_OperationMode::WRITE_MODE}};
58    FileShare_PolicyErrorResult* result = nullptr;
59    uint32_t resultNum = 0;
60    auto ret = OH_FileShare_PersistPermission(policy, POLICY_NUM, &result, &resultNum);
61    if (ret != ERR_OK) {
62        if (ret == ERR_EPERM && result != nullptr) {
63            for(uint32_t i = 0; i < resultNum; i++) {
64                std::cout << "error uri: " <<  result[i].uri << std::endl;
65                std::cout << "error code: " <<  result[i].code << std::endl;
66                std::cout << "error message: " << result[i].message << std::endl;
67            }
68        }
69    }
70    OH_FileShare_ReleasePolicyErrorResult(result, resultNum);
71    ```
722. Call **OH_FileShare_ActivatePermission** to activate the persistent permissions on files. The maximum value of **policyNum** is **500**.
73    ```c++
74    auto ret = OH_FileShare_ActivatePermission(policy, POLICY_NUM, &result, &resultNum);
75    if (ret != ERR_OK) {
76        if (ret == ERR_EPERM && result != nullptr) {
77            for(uint32_t i = 0; i < resultNum; i++) {
78                std::cout << "error uri: " <<  result[i].uri << std::endl;
79                std::cout << "error code: " <<  result[i].code << std::endl;
80                std::cout << "error message: " << result[i].message << std::endl;
81            }
82        }
83    }
84    OH_FileShare_ReleasePolicyErrorResult(result, resultNum);
85    ```
863. Call **OH_FileShare_DeactivatePermission** to deactivate the persistent permissions on files. The maximum value of **policyNum** is **500**.
87    ```c++
88    auto ret = OH_FileShare_DeactivatePermission(policy, POLICY_NUM, &result, &resultNum);
89    if (ret != ERR_OK) {
90        if (ret == ERR_EPERM && result != nullptr) {
91            for(uint32_t i = 0; i < resultNum; i++) {
92                std::cout << "error uri: " <<  result[i].uri << std::endl;
93                std::cout << "error code: " <<  result[i].code << std::endl;
94                std::cout << "error message: " << result[i].message << std::endl;
95            }
96        }
97    }
98    OH_FileShare_ReleasePolicyErrorResult(result, resultNum);
99    ```
1004. Call **OH_FileShare_RevokePermission** to revoke the persistent permissions from files. The maximum value of **policyNum** is **500**.
101    ```c++
102    auto ret = OH_FileShare_RevokePermission(policy, POLICY_NUM, &result, &resultNum);
103    if (ret != ERR_OK) {
104        if (ret == ERR_EPERM && result != nullptr) {
105            for(uint32_t i = 0; i < resultNum; i++) {
106                std::cout << "error uri: " <<  result[i].uri << std::endl;
107                std::cout << "error code: " <<  result[i].code << std::endl;
108                std::cout << "error message: " << result[i].message << std::endl;
109            }
110        }
111    }
112    OH_FileShare_ReleasePolicyErrorResult(result, resultNum);
113    ```
1145. Call **OH_FileShare_CheckPersistentPermission** to check the persistent permissions on files. The maximum value of **policyNum** is **500**.
115    ```c++
116    bool *result = nullptr;
117    auto ret = OH_FileShare_CheckPersistentPermission(policy, POLICY_NUM, &result, &resultNum);
118    if (result != nullptr && resultNum > 0) {
119        for(uint32_t i = 0; i < resultNum && resultNum <= POLICY_NUM; i++) {
120            std::cout << "uri: " <<  policy[i].uri << std::endl;
121            std::cout << "result: " <<  result[i] << std::endl;
122        }
123    }
124    std::cout << "retCode: " <<  ret << std::endl;
125    free(result);
126    ```
127