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