1/* 2 * Copyright (C) 2022-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 * @file 18 * @kit CoreFileKit 19 */ 20 21import type { AsyncCallback, Callback } from './@ohos.base'; 22import type wantConstant from './@ohos.ability.wantConstant'; 23 24/** 25 * Provides fileshare APIS 26 * 27 * @namespace fileShare 28 * @syscap SystemCapability.FileManagement.AppFileService 29 * @since 9 30 */ 31declare namespace fileShare { 32 /** 33 * Enumerates the uri operate mode types. 34 * 35 * @enum { number } OperationMode 36 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 37 * @since 11 38 */ 39 export enum OperationMode { 40 /** 41 * Indicates read permissions. 42 * 43 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 44 * @since 11 45 */ 46 READ_MODE = 0b1, 47 48 /** 49 * Indicates write permissions. 50 * 51 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 52 * @since 11 53 */ 54 WRITE_MODE = 0b10, 55 } 56 57 /** 58 * Enumerates the error code of the permission policy for the URI operation. 59 * 60 * @enum { number } PolicyErrorCode 61 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 62 * @since 11 63 */ 64 export enum PolicyErrorCode { 65 /** 66 * Indicates that the policy is not allowed to be persisted. 67 * 68 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 69 * @since 11 70 */ 71 PERSISTENCE_FORBIDDEN = 1, 72 73 /** 74 * Indicates that the mode of this policy is invalid. 75 * 76 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 77 * @since 11 78 */ 79 INVALID_MODE = 2, 80 81 /** 82 * Indicates that the path of this policy is invalid. 83 * 84 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 85 * @since 11 86 */ 87 INVALID_PATH = 3, 88 89 /** 90 * Indicates that the permission is not persistent. 91 * 92 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 93 * @since 12 94 */ 95 PERMISSION_NOT_PERSISTED = 4, 96 } 97 98 /** 99 * Failed policy result on URI. 100 * 101 * @typedef { object } 102 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 103 * @since 11 104 */ 105 export type PolicyErrorResult = { 106 /** 107 * Indicates the failed uri of the policy information. 108 * 109 * @type { string } 110 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 111 * @since 11 112 */ 113 uri: string; 114 115 /** 116 * Indicates the error code of the failure in the policy information. 117 * 118 * @type { PolicyErrorCode } 119 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 120 * @since 11 121 */ 122 code: PolicyErrorCode; 123 124 /** 125 * Indicates the reason of the failure in the policy information. 126 * 127 * @type { string } 128 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 129 * @since 11 130 */ 131 message: string; 132 }; 133 134 /** 135 * Policy information to manager permissions on a URI. 136 * 137 * @interface PolicyInfo 138 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 139 * @since 11 140 */ 141 export interface PolicyInfo { 142 /** 143 * Indicates the uri of the policy information. 144 * 145 * @type { string } 146 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 147 * @since 11 148 */ 149 uri: string; 150 151 /** 152 * Indicates the mode of operation for the URI, example { OperationMode.READ_MODE } or { OperationMode.READ_MODE | OperationMode.WRITE_MODE } 153 * 154 * @type { number } 155 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 156 * @since 11 157 */ 158 operationMode: number; 159 } 160 161 /** 162 * Policy information to manager permissions on a path. 163 * 164 * @interface PathPolicyInfo 165 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 166 * @since 15 167 */ 168 export interface PathPolicyInfo { 169 /** 170 * Indicates the path of the policy information. 171 * 172 * @type { string } 173 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 174 * @since 15 175 */ 176 path: string; 177 178 /** 179 * Indicates the mode of operation for the path. 180 * 181 * @type { OperationMode } 182 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 183 * @since 15 184 */ 185 operationMode: OperationMode; 186 } 187 188 /** 189 * Indicates the policy type of the path. 190 * 191 * @enum { number } policyType 192 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 193 * @since 15 194 */ 195 export enum PolicyType { 196 /** 197 * Indicates that the policy is temporary. 198 * 199 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 200 * @since 15 201 */ 202 TEMPORARY_TYPE = 0, 203 204 /** 205 * Indicates that the policy is persistent. 206 * 207 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 208 * @since 15 209 */ 210 PERSISTENT_TYPE = 1, 211 } 212 213 /** 214 * Provides grant uri permission for app 215 * 216 * @permission ohos.permission.WRITE_MEDIA 217 * @param { string } uri uri 218 * @param { string } bundleName bundleName 219 * @param { wantConstant.Flags } flag wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION or wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION 220 * @param { AsyncCallback<void> } callback 221 * @throws { BusinessError } 201 - Permission verification failed 222 * @throws { BusinessError } 202 - The caller is not a system application 223 * @throws { BusinessError } 401 - The input parameter is invalid.Possible causes:1.Mandatory parameters are left unspecified; 224 * <br>2.Incorrect parameter types. 225 * @throws { BusinessError } 143000001 - IPC error 226 * @syscap SystemCapability.FileManagement.AppFileService 227 * @systemapi 228 * @since 9 229 */ 230 function grantUriPermission( 231 uri: string, 232 bundleName: string, 233 flag: wantConstant.Flags, 234 callback: AsyncCallback<void> 235 ): void; 236 237 /** 238 * Provides grant uri permission for app 239 * 240 * @permission ohos.permission.WRITE_MEDIA 241 * @param { string } uri uri 242 * @param { string } bundleName bundleName 243 * @param { wantConstant.Flags } flag wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION or wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION 244 * @returns { Promise<void> } no callback return Promise otherwise return void 245 * @throws { BusinessError } 201 - Permission verification failed 246 * @throws { BusinessError } 202 - The caller is not a system application 247 * @throws { BusinessError } 401 - The input parameter is invalid.Possible causes:1.Mandatory parameters are left unspecified; 248 * <br>2.Incorrect parameter types. 249 * @throws { BusinessError } 143000001 - IPC error 250 * @syscap SystemCapability.FileManagement.AppFileService 251 * @systemapi 252 * @since 9 253 */ 254 function grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags): Promise<void>; 255 256 /** 257 * Set persistence permissions for the URI 258 * 259 * @permission ohos.permission.FILE_ACCESS_PERSIST 260 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 261 * @returns { Promise<void> } the promise returned by the function. 262 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 263 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 264 * <br>2.Incorrect parameter types. 265 * @throws { BusinessError } 801 - Capability not supported. 266 * @throws { BusinessError } 13900001 - Operation not permitted. 267 * @throws { BusinessError } 13900042 - Out of memory 268 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 269 * @since 11 270 */ 271 function persistPermission(policies: Array<PolicyInfo>): Promise<void>; 272 273 /** 274 * Revoke persistence permissions for the URI 275 * 276 * @permission ohos.permission.FILE_ACCESS_PERSIST 277 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 278 * @returns { Promise<void> } the promise returned by the function. 279 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 280 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 281 * <br>2.Incorrect parameter types. 282 * @throws { BusinessError } 801 - Capability not supported. 283 * @throws { BusinessError } 13900001 - Operation not permitted. 284 * @throws { BusinessError } 13900042 - Out of memory 285 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 286 * @since 11 287 */ 288 function revokePermission(policies: Array<PolicyInfo>): Promise<void>; 289 290 /** 291 * Enable the URI that have been permanently authorized 292 * 293 * @permission ohos.permission.FILE_ACCESS_PERSIST 294 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 295 * @returns { Promise<void> } the promise returned by the function. 296 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 297 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 298 * <br>2.Incorrect parameter types. 299 * @throws { BusinessError } 801 - Capability not supported. 300 * @throws { BusinessError } 13900001 - Operation not permitted. 301 * @throws { BusinessError } 13900042 - Out of memory 302 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 303 * @since 11 304 */ 305 function activatePermission(policies: Array<PolicyInfo>): Promise<void>; 306 307 /** 308 * Stop the authorized URI that has been enabled 309 * 310 * @permission ohos.permission.FILE_ACCESS_PERSIST 311 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 312 * @returns { Promise<void> } the promise returned by the function. 313 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 314 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 315 * <br>2.Incorrect parameter types. 316 * @throws { BusinessError } 801 - Capability not supported. 317 * @throws { BusinessError } 13900001 - Operation not permitted. 318 * @throws { BusinessError } 13900042 - Out of memory 319 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 320 * @since 11 321 */ 322 function deactivatePermission(policies: Array<PolicyInfo>): Promise<void>; 323 324 /** 325 * Check persistent permissions for the URI. 326 * 327 * @permission ohos.permission.FILE_ACCESS_PERSIST 328 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 329 * @returns { Promise<Array<boolean>> } Returns the persistent state of uri permissions. 330 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 331 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 332 * <br>2.Incorrect parameter types. 333 * @throws { BusinessError } 801 - Capability not supported. 334 * @throws { BusinessError } 13900042 - Out of memory 335 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 336 * @since 12 337 */ 338 /** 339 * Check persistent permissions for the URI. 340 * 341 * @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs. 342 * @returns { Promise<Array<boolean>> } Returns the persistent state of uri permissions. 343 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 344 * <br>2.Incorrect parameter types. 345 * @throws { BusinessError } 801 - Capability not supported. 346 * @throws { BusinessError } 13900042 - Out of memory 347 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 348 * @since 17 349 */ 350 function checkPersistentPermission(policies: Array<PolicyInfo>): Promise<Array<boolean>>; 351 352 /** 353 * Check permissions for the path. 354 * 355 * @permission ohos.permission.CHECK_SANDBOX_POLICY 356 * @param { number } tokenID - Token ID of the application. 357 * @param { Array<PathPolicyInfo> } policies - Policy information to check on paths. 358 * @param { PolicyType } policyType - Persistent or temporary type. 359 * @returns { Promise<Array<boolean>> } Returns the permission state of paths. 360 * @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken. 361 * @throws { BusinessError } 202 - The caller is not a system application 362 * @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 363 * <br>2.Incorrect parameter types. 364 * @throws { BusinessError } 801 - Capability not supported. 365 * @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization 366 * @systemapi 367 * @since 15 368 */ 369 function checkPathPermission(tokenID: number, policies: Array<PathPolicyInfo>, policyType: PolicyType): Promise<Array<boolean>>; 370} 371 372export default fileShare; 373