* Copyright (C) 2022-2025 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
* @file
* @kit CoreFileKit
*/
import type { AsyncCallback, Callback } from './@ohos.base';
import type wantConstant from './@ohos.ability.wantConstant';
import { AsyncCallback, Callback } from './@ohos.base';
import type wantConstant from './@ohos.app.ability.wantConstant';
* Provides fileshare APIS
*
* @namespace fileShare
* @syscap SystemCapability.FileManagement.AppFileService
* @since 9 dynamic
* @since 23 static
*/
declare namespace fileShare {
* Enumerates the uri operate mode types.
*
* @enum { int } OperationMode
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
export enum OperationMode {
* Indicates read permissions.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
READ_MODE = 0b1,
* Indicates write permissions.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
WRITE_MODE = 0b10,
* Indicates creating permissions.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 20 dynamic
* @since 23 static
*/
CREATE_MODE = 0b100,
* Indicates deleting permissions.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 20 dynamic
* @since 23 static
*/
DELETE_MODE = 0b1000,
* Indicates renaming permissions.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 20 dynamic
* @since 23 static
*/
RENAME_MODE = 0b10000,
}
* Enumerates the error code of the permission policy for the URI operation.
*
* @enum { int } PolicyErrorCode
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
export enum PolicyErrorCode {
* Indicates that the policy is not allowed to be persisted.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
PERSISTENCE_FORBIDDEN = 1,
* Indicates that the mode of this policy is invalid.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
INVALID_MODE = 2,
* Indicates that the path of this policy is invalid.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
INVALID_PATH = 3,
* Indicates that the permission is not persistent.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 12 dynamic
* @since 23 static
*/
PERMISSION_NOT_PERSISTED = 4,
}
* Failed policy result on URI.
*
* @interface { object }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
export interface PolicyErrorResult {
* Indicates the failed uri of the policy information.
*
* @type { string }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
uri: string;
* Indicates the error code of the failure in the policy information.
*
* @type { PolicyErrorCode }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
code: PolicyErrorCode;
* Indicates the reason of the failure in the policy information.
*
* @type { string }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
message: string;
}
* Policy information to manager permissions on a URI.
*
* @interface PolicyInfo
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
export interface PolicyInfo {
* Indicates the uri of the policy information.
*
* @type { string }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
uri: string;
* Indicates the mode of operation for the URI, example { OperationMode.READ_MODE } or { OperationMode.READ_MODE | OperationMode.WRITE_MODE }
*
* @type { int }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
operationMode: int;
}
* The directory information shared with the system by the application.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
export interface SharedDirectoryInfo {
* Indicates the bundle name of the application.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
bundleName: string;
* Indicates the path of the application's shared directory.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
path: string;
* Indicates the permission for the application's shared directory, e.g., { OperationMode.READ_MODE }
* or { OperationMode.READ_MODE | OperationMode.WRITE_MODE }
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
permissionMode: int;
}
* Policy information to manager permissions on a path.
*
* @interface PathPolicyInfo
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
export interface PathPolicyInfo {
* Indicates the path of the policy information.
*
* @type { string }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
path: string;
* Indicates the mode of operation for the path.
*
* @type { OperationMode }
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
operationMode: OperationMode;
}
* Indicates the policy type of the path.
*
* @enum { int } policyType
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
export enum PolicyType {
* Indicates that the policy is temporary.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
TEMPORARY_TYPE = 0,
* Indicates that the policy is persistent.
*
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 15 dynamic
* @since 23 static
*/
PERSISTENT_TYPE = 1,
}
* Provides grant uri permission for app
*
* @permission ohos.permission.WRITE_MEDIA
* @param { string } uri uri
* @param { string } bundleName bundleName
* @param { wantConstant.Flags } flag wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION or wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION
* @param { AsyncCallback<void> } callback
* @throws { BusinessError } 201 - Permission verification failed
* @throws { BusinessError } 202 - The caller is not a system application
* @throws { BusinessError } 401 - The input parameter is invalid.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 14300001 - IPC error
* @syscap SystemCapability.FileManagement.AppFileService
* @systemapi
* @since 9 dynamic
* @since 23 static
*/
function grantUriPermission(
uri: string,
bundleName: string,
flag: wantConstant.Flags,
callback: AsyncCallback<void>
): void;
* Provides grant uri permission for app
*
* @permission ohos.permission.WRITE_MEDIA
* @param { string } uri uri
* @param { string } bundleName bundleName
* @param { wantConstant.Flags } flag wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION or wantConstant.Flags.FLAG_AUTH_WRITE_URI_PERMISSION
* @returns { Promise<void> } no callback return Promise otherwise return void
* @throws { BusinessError } 201 - Permission verification failed
* @throws { BusinessError } 202 - The caller is not a system application
* @throws { BusinessError } 401 - The input parameter is invalid.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 14300001 - IPC error
* @syscap SystemCapability.FileManagement.AppFileService
* @systemapi
* @since 9 dynamic
* @since 23 static
*/
function grantUriPermission(uri: string, bundleName: string, flag: wantConstant.Flags): Promise<void>;
* Grant URI permissions for an application.
*
* @permission ohos.permission.FILE_ACCESS_MANAGER
* @param { Array<PolicyInfo> } policies - Policy information for the user to grant permissions on URIs.
* @param { string } targetBundleName - Name of the target bundle to authorize.
* @param { int } appCloneIndex - Clone index of the target application.
* @returns { Promise<void> } Returns void.
* @throws { BusinessError } 201 - Permission verification failed.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900011 - Out of memory.
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @since 20 dynamic
* @since 23 static
*/
function grantUriPermission(policies: Array<PolicyInfo>, targetBundleName: string, appCloneIndex: int): Promise<void>;
* Set persistence permissions for the URI
*
* @permission ohos.permission.FILE_ACCESS_PERSIST
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
function persistPermission(policies: Array<PolicyInfo>): Promise<void>;
* Revoke persistence permissions for the URI
*
* @permission ohos.permission.FILE_ACCESS_PERSIST
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
function revokePermission(policies: Array<PolicyInfo>): Promise<void>;
* Revoke all persistence permissions for the application.
*
* @permission ohos.permission.REVOKE_FILE_ACCESS_PERSIST
* @param { int } tokenID - Token ID of the application.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900020 - Invalid tokenID
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function revokePermission(tokenID: int): Promise<void>;
* Revoke persistence permissions for the URI.
*
* @permission ohos.permission.REVOKE_FILE_ACCESS_PERSIST
* @param { int } tokenID - Token ID of the application.
* @param { Array<PolicyInfo> } policies - Policy information to revoke permission on URIs.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types; 3.Invalid policy size.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900011 - Out of memory
* @throws { BusinessError } 13900020 - Invalid tokenID
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function revokePermission(tokenID: int, policies: Array<PolicyInfo>): Promise<void>;
* Get all persistence permissions for the application.
*
* @permission ohos.permission.GET_FILE_ACCESS_PERSIST
* @param { int } tokenID - Token ID of the application.
* @returns { Promise<Array<PolicyInfo>> } Returns all persistence policy information.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900011 - Out of memory
* @throws { BusinessError } 13900020 - Invalid tokenID
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function getPersistentPolicy(tokenID: int): Promise<Array<PolicyInfo>>;
* Enable the URI that have been permanently authorized
*
* @permission ohos.permission.FILE_ACCESS_PERSIST
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
function activatePermission(policies: Array<PolicyInfo>): Promise<void>;
* Stop the authorized URI that has been enabled
*
* @permission ohos.permission.FILE_ACCESS_PERSIST
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 11 dynamic
* @since 23 static
*/
function deactivatePermission(policies: Array<PolicyInfo>): Promise<void>;
* Check persistent permissions for the URI.
*
* @permission ohos.permission.FILE_ACCESS_PERSIST
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<Array<boolean>> } Returns the persistent state of uri permissions.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 12
*/
* Check persistent permissions for the URI.
*
* @param { Array<PolicyInfo> } policies - Policy information to grant permission on URIs.
* @returns { Promise<Array<boolean>> } Returns the persistent state of uri permissions.
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900042 - Out of memory
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @since 17 dynamic
* @since 23 static
*/
function checkPersistentPermission(policies: Array<PolicyInfo>): Promise<Array<boolean>>;
* Check permissions for the path.
*
* @permission ohos.permission.CHECK_SANDBOX_POLICY
* @param { int } tokenID - Token ID of the application.
* @param { Array<PathPolicyInfo> } policies - Policy information to check on paths.
* @param { PolicyType } policyType - Persistent or temporary type.
* @returns { Promise<Array<boolean>> } Returns the permission state of paths.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application
* @throws { BusinessError } 401 - Parameter error.Possible causes:1.Mandatory parameters are left unspecified;
* <br>2.Incorrect parameter types.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900042 - Out of memory.
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @since 15 dynamic
* @since 23 static
*/
function checkPathPermission(tokenID: int, policies: Array<PathPolicyInfo>, policyType: PolicyType): Promise<Array<boolean>>;
* Gets the shared sandbox directories of applications
*
* @permission ohos.permission.ACCESS_SHARED_FILE
* @returns { Promise<Array<SharedDirectoryInfo>> } Returns the shared sandbox directories on paths.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @throws { BusinessError } 13900011 - Out of memory.
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function getSharedDirectoryInfo(): Promise<Array<SharedDirectoryInfo>>;
* Provides a permission grant for application-shared directories
*
* @permission ohos.permission.ACCESS_SHARED_FILE
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function grantSharedDirectoryPermission(): Promise<void>;
* Revokes permission for application-shared directories
*
* @permission ohos.permission.ACCESS_SHARED_FILE
* @returns { Promise<void> } the promise returned by the function.
* @throws { BusinessError } 201 - Permission verification failed, usually the result returned by VerifyAccessToken.
* @throws { BusinessError } 202 - The caller is not a system application.
* @throws { BusinessError } 801 - Capability not supported.
* @throws { BusinessError } 13900001 - Operation not permitted.
* @syscap SystemCapability.FileManagement.AppFileService.FolderAuthorization
* @systemapi
* @stagemodelonly
* @since 26.0.0 dynamic&static
*/
function revokeSharedDirectoryPermission(): Promise<void>;
}
export default fileShare;
