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 42 extern "C" { 43 #endif 44 /** 45 * @brief Enumerates the uri operate mode types. 46 * 47 * @since 12 48 */ 49 typedef 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 */ 66 typedef 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 */ 95 typedef 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 */ 119 typedef 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 */ 156 FileManagement_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 */ 179 FileManagement_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 */ 202 FileManagement_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 */ 225 FileManagement_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 */ 247 FileManagement_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 */ 259 void 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