1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16#ifndef FILE_MANAGEMENT_OH_FILE_SHARE_H
17#define FILE_MANAGEMENT_OH_FILE_SHARE_H
18
19#include "error_code.h"
20#include <stdbool.h>
21
22/**
23 * @addtogroup fileShare
24 * @{
25 *
26 * @brief This module provides file sharing capabilities to authorize Uniform Resource Identifiers (URIs)
27 * for public directory files that have read and write access to other applications.
28 * @since 12
29 */
30
31/**
32 * @file oh_file_share.h
33 * @kit CoreFileKit
34 *
35 * @brief Provides URI-based file and directory authorization and persistence, permission activation, permission query,
36 * and other methods.
37 * @library libohfileshare.so
38 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
39 * @since 12
40 */
41#ifdef __cplusplus
42extern "C" {
43#endif
44/**
45 * @brief Enumerates the uri operate mode types.
46 *
47 * @since 12
48 */
49typedef enum FileShare_OperationMode {
50    /**
51     * @brief Indicates read permissions.
52     */
53    READ_MODE = 1 << 0,
54
55    /**
56     * @brief Indicates write permissions.
57     */
58    WRITE_MODE = 1 << 1
59} FileShare_OperationMode;
60
61/**
62 * @brief Enumerates the error code of the permission policy for the URI operation.
63 *
64 * @since 12
65 */
66typedef enum FileShare_PolicyErrorCode {
67    /**
68     * @brief Indicates that the policy is not allowed to be persisted.
69     */
70    PERSISTENCE_FORBIDDEN = 1,
71
72    /**
73     * @brief Indicates that the mode of this policy is invalid.
74     */
75    INVALID_MODE = 2,
76
77    /**
78     * @brief Indicates that the path of this policy is invalid.
79     */
80    INVALID_PATH = 3,
81
82    /**
83     * @brief Indicates that the policy is no persistent capability.
84     */
85    PERMISSION_NOT_PERSISTED = 4
86} FileShare_PolicyErrorCode;
87
88/**
89 * @brief Define the FileShare_PolicyErrorResult structure type.
90 *
91 * Failed policy result on URI.
92 *
93 * @since 12
94 */
95typedef struct FileShare_PolicyErrorResult {
96    /**
97     * Indicates the failed uri of the policy information.
98     */
99    char *uri;
100
101    /**
102     * Indicates the error code of the failure in the policy information.
103     */
104    FileShare_PolicyErrorCode code;
105
106    /**
107     * Indicates the reason of the failure in the policy information.
108     */
109    char *message;
110} FileShare_PolicyErrorResult;
111
112/**
113 * @brief Define the FileShare_PolicyInfo structure type.
114 *
115 * Policy information to manager permissions on a URI.
116 *
117 * @since 12
118 */
119typedef struct FileShare_PolicyInfo {
120    /**
121     * Indicates the uri of the policy information.
122     */
123    char *uri;
124
125    /**
126     * Indicates The length of the uri.
127     */
128    unsigned int length;
129
130    /**
131     * Indicates the mode of operation for the URI.
132     * example { FileShare_OperationMode.READ_MODE } or { FileShare_OperationMode.READ_MODE |
133     * FileShare_OperationMode.WRITE_MODE }.
134     */
135    unsigned int operationMode;
136} FileShare_PolicyInfo;
137
138/**
139 * @brief Set persistent permissions for the URI.
140 *
141 * @permission ohos.permission.FILE_ACCESS_PERSIST
142 * @param policies Input a pointer to an {@link FileShare_PolicyInfo} instance.
143 * @param policyNum Indicates the size of the policies array.
144 * @param result Output a pointer to an {@link FileShare_PolicyErrorResult} instance. Please use
145 * OH_FileShare_ReleasePolicyErrorResult() to clear Resource.
146 * @param resultNum Output the size of the result array.
147 * @return Returns the status code of the execution.
148 *         {@link E_PARAMS} 401 - Invalid input parameter.
149 *         {@link E_DEVICE_NOT_SUPPORT} 801 - Device not supported.
150 *         {@link E_PERMISSION} 201 - No permission to perform this operation.
151 *         {@link E_EPERM} 13900001 - operation not permitted.
152 *         {@link E_ENOMEM} 13900011 - Failed to apply for memory or failed to copy memory.
153 *         {@link E_NO_ERROR} 0 - This operation was successfully executed.
154 * @since 12
155 */
156FileManagement_ErrCode OH_FileShare_PersistPermission(const FileShare_PolicyInfo *policies,
157                                                      unsigned int policyNum,
158                                                      FileShare_PolicyErrorResult **result,
159                                                      unsigned int *resultNum);
160
161/**
162 * @brief Revoke persistent permissions for the URI.
163 *
164 * @permission ohos.permission.FILE_ACCESS_PERSIST
165 * @param policies Input a pointer to an {@link FileShare_PolicyInfo} instance.
166 * @param policyNum Indicates the size of the policies array.
167 * @param result Output a pointer to an {@link FileShare_PolicyErrorResult} instance. Please use
168 * OH_FileShare_ReleasePolicyErrorResult() to clear Resource.
169 * @param resultNum Output the size of the result array.
170 * @return Returns the status code of the execution.
171 *         {@link E_PARAMS} 401 - Invalid input parameter.
172 *         {@link E_DEVICE_NOT_SUPPORT} 801 - Device not supported.
173 *         {@link E_PERMISSION} 201 - No permission to perform this operation.
174 *         {@link E_EPERM} 13900001 - operation not permitted.
175 *         {@link E_ENOMEM} 13900011 - Failed to apply for memory or failed to copy memory.
176 *         {@link E_NO_ERROR} 0 - This operation was successfully executed.
177 * @since 12
178 */
179FileManagement_ErrCode OH_FileShare_RevokePermission(const FileShare_PolicyInfo *policies,
180                                                     unsigned int policyNum,
181                                                     FileShare_PolicyErrorResult **result,
182                                                     unsigned int *resultNum);
183
184/**
185 * @brief Enable the URI that have been permanently authorized.
186 *
187 * @permission ohos.permission.FILE_ACCESS_PERSIST
188 * @param policies Input a pointer to an {@link FileShare_PolicyInfo} instance.
189 * @param policyNum Indicates the size of the policies array.
190 * @param result Output a pointer to an {@link FileShare_PolicyErrorResult} instance. Please use
191 * OH_FileShare_ReleasePolicyErrorResult() to clear Resource.
192 * @param resultNum Output the size of the result array.
193 * @return Returns the status code of the execution.
194 *         {@link E_PARAMS} 401 - Invalid input parameter.
195 *         {@link E_DEVICE_NOT_SUPPORT} 801 - Device not supported.
196 *         {@link E_PERMISSION} 201 - No permission to perform this operation.
197 *         {@link E_EPERM} 13900001 - operation not permitted.
198 *         {@link E_ENOMEM} 13900011 - Failed to apply for memory or failed to copy memory.
199 *         {@link E_NO_ERROR} 0 - This operation was successfully executed.
200 * @since 12
201 */
202FileManagement_ErrCode OH_FileShare_ActivatePermission(const FileShare_PolicyInfo *policies,
203                                                       unsigned int policyNum,
204                                                       FileShare_PolicyErrorResult **result,
205                                                       unsigned int *resultNum);
206
207/**
208 * @brief Stop the authorized URI that has been enabled.
209 *
210 * @permission ohos.permission.FILE_ACCESS_PERSIST
211 * @param policies Input a pointer to an {@link FileShare_PolicyInfo} instance.
212 * @param policyNum Indicates the size of the policies array.
213 * @param result Output a pointer to an {@link FileShare_PolicyErrorResult} instance. Please use
214 * OH_FileShare_ReleasePolicyErrorResult() to clear Resource.
215 * @param resultNum Output the size of the result array.
216 * @return Returns the status code of the execution.
217 *         {@link E_PARAMS} 401 - Invalid input parameter.
218 *         {@link E_DEVICE_NOT_SUPPORT} 801 - Device not supported.
219 *         {@link E_PERMISSION} 201 - No permission to perform this operation.
220 *         {@link E_EPERM} 13900001 - operation not permitted.
221 *         {@link E_ENOMEM} 13900011 - Failed to apply for memory or failed to copy memory.
222 *         {@link E_NO_ERROR} 0 - This operation was successfully executed.
223 * @since 12
224 */
225FileManagement_ErrCode OH_FileShare_DeactivatePermission(const FileShare_PolicyInfo *policies,
226                                                         unsigned int policyNum,
227                                                         FileShare_PolicyErrorResult **result,
228                                                         unsigned int *resultNum);
229
230/**
231 * @brief Check persistent permissions for the URI.
232 *
233 * @permission ohos.permission.FILE_ACCESS_PERSIST
234 * @param policies Input a pointer to an {@link FileShare_PolicyInfo} instance.
235 * @param policyNum Indicates the size of the policies array.
236 * @param result Output a pointer to an bool instance. Please use free() to clear Resource.
237 * @param resultNum Output the size of the result array.
238 * @return Returns the status code of the execution.
239 *         {@link E_PARAMS} 401 - Invalid input parameter.
240 *         {@link E_DEVICE_NOT_SUPPORT} 801 - Device not supported.
241 *         {@link E_PERMISSION} 201 - No permission to perform this operation.
242 *         {@link E_EPERM} 13900001 - operation not permitted.
243 *         {@link E_ENOMEM} 13900011 - Failed to apply for memory or failed to copy memory.
244 *         {@link E_NO_ERROR} 0 - This operation was successfully executed.
245 * @since 12
246 */
247FileManagement_ErrCode OH_FileShare_CheckPersistentPermission(const FileShare_PolicyInfo *policies,
248                                                              unsigned int policyNum,
249                                                              bool **result,
250                                                              unsigned int *resultNum);
251
252/**
253 * @brief Free FileShare_PolicyErrorResult pointer points to address memory.
254 *
255 * @param errorResult Input a pointer to an {@link FileShare_PolicyErrorResult} instance.
256 * @param resultNum Indicates the size of the errorResult array.
257 * @since 12
258 */
259void OH_FileShare_ReleasePolicyErrorResult(FileShare_PolicyErrorResult *errorResult, unsigned int resultNum);
260#ifdef __cplusplus
261};
262#endif
263/** @} */
264#endif // FILE_MANAGEMENT_OH_FILE_SHARE_H
265