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