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