@ohos.fileshare (File Sharing)

The fileShare module provides APIs for granting permissions on a user file to another application based on the file Uniform Resource Identifier (URI). Then, the authorized application can call @ohos.file.fs APIs to access the file.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import fileShare from '@ohos.fileshare';

OperationMode¹¹⁺

Enumerates the permissions on a URI.

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

PolicyErrorCode¹¹⁺

Enumerates the error codes for a permission policy.

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

PolicyErrorResult¹¹⁺

Represents the detailed permission policy error information, which can be used when persistPermission, revokePermission, activatePermission, or deactivatePermission throws an error.

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

PolicyInfo¹¹⁺

Represents a permission policy, that is, a policy for granting or activating the permission on a file.

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

fileShare.persistPermission¹¹⁺

persistPermission(policies: Array<PolicyInfo>): Promise<void>

Persists the permissions granted to multiple files or folders. This API uses a promise to return the result.
This API is available only to certain devices.

Required permissions: ohos.permission.FILE_ACCESS_PERSIST

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes. If the permission persistence of some URIs fails, error code 13900001 will be returned and the data field provides error information of these URIs in the Array<PolicyErrorResult> format.

Example

import { BusinessError } from '@ohos.base';
import picker from '@ohos.file.picker';

async function persistPermissionExample() {
  try {
    let DocumentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker();
    let uris = await documentPicker.select(DocumentSelectOptions);
    let policyInfo: fileShare.PolicyInfo = {
      uri: uris[0], 
      operationMode: fileShare.OperationMode.READ_MODE,
    };
    let policies: Array<fileShare.PolicyInfo> = [policyInfo];
    fileShare.persistPermission(policies).then(() => {
      console.info("persistPermission successfully");
    }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
      console.info("persistPermission failed with error message: " + err.message + ", error code: " + err.code);
      if (err.code == 13900001 && err.data) {
        for (let i = 0; i < err.data.length; i++) {
          console.log("error code : " + JSON.stringify(err.data[i].code));
          console.log("error uri : " + JSON.stringify(err.data[i].uri));
          console.log("error reason : " + JSON.stringify(err.data[i].message));
        }
      }
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('persistPermission failed with err: ' + JSON.stringify(err));
  }
}

fileShare.revokePermission¹¹⁺

revokePermission(policies: Array<PolicyInfo>): Promise<void>

Revokes permissions from multiple files or folders. This API uses a promise to return the result.
This API is available only to certain devices.

Required permissions: ohos.permission.FILE_ACCESS_PERSIST

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes. If the permission revocation of some URIs fails, error code 13900001 will be returned and the data field provides error information of these URIs in the Array<PolicyErrorResult> format.

Example

import { BusinessError } from '@ohos.base';
import picker from '@ohos.file.picker';

async function revokePermissionExample() {
  try {
    let DocumentSelectOptions = new picker.DocumentSelectOptions();
    let documentPicker = new picker.DocumentViewPicker();
    let uris = await documentPicker.select(DocumentSelectOptions);
    let policyInfo: fileShare.PolicyInfo = {
      uri: uris[0], 
      operationMode: fileShare.OperationMode.READ_MODE,
    };
    let policies: Array<fileShare.PolicyInfo> = [policyInfo];
    fileShare.revokePermission(policies).then(() => {
      console.info("revokePermission successfully");
    }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
      console.info("revokePermission failed with error message: " + err.message + ", error code: " + err.code);
        if (err.code == 13900001 && err.data) {
          for (let i = 0; i < err.data.length; i++) {
            console.log("error code : " + JSON.stringify(err.data[i].code));
            console.log("error uri : " + JSON.stringify(err.data[i].uri));
            console.log("error reason : " + JSON.stringify(err.data[i].message));
          }
        }
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('revokePermission failed with err: ' + JSON.stringify(err));
  }
}

fileShare.activatePermission¹¹⁺

activatePermission(policies: Array<PolicyInfo>): Promise<void>

Activates the permissions that have been persisted on multiple files or folders. This API uses a promise to return the result.
This API is available only to certain devices.

Required permissions: ohos.permission.FILE_ACCESS_PERSIST

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes. If the permission activation of some URIs fails, error code 13900001 will be returned and the data field provides error information of these URIs in the Array<PolicyErrorResult> format.

Example

import { BusinessError } from '@ohos.base';
import picker from '@ohos.file.picker';

async function activatePermissionExample() {
  try {
    let uri = "file://docs/storage/Users/username/tmp.txt";
    let policyInfo: fileShare.PolicyInfo = {
      uri: uri,
      operationMode: fileShare.OperationMode.READ_MODE,
    };
    let policies: Array<fileShare.PolicyInfo> = [policyInfo];
    fileShare.activatePermission(policies).then(() => {
      console.info("activatePermission successfully");
    }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
      console.info("activatePermission failed with error message: " + err.message + ", error code: " + err.code);
        if (err.code == 13900001 && err.data) {
          for (let i = 0; i < err.data.length; i++) {
            console.log("error code : " + JSON.stringify(err.data[i].code));
            console.log("error uri : " + JSON.stringify(err.data[i].uri));
            console.log("error reason : " + JSON.stringify(err.data[i].message));
          }
        }
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('activatePermission failed with err: ' + JSON.stringify(err));
  }
}

fileShare.deactivatePermission¹¹⁺

deactivatePermission(policies: Array<PolicyInfo>): Promise<void>

Deactivates the permissions on multiple files or folders. This API uses a promise to return the result.
This API is available only to certain devices.

Required permissions: ohos.permission.FILE_ACCESS_PERSIST

System capability: SystemCapability.FileManagement.AppFileService.FolderAuthorization

Parameters

Return value

Error codes

For details about the error codes, see File Management Error Codes. If the permission deactivation of some URIs fails, error code 13900001 will be returned and the data field provides error information of these URIs in the Array<PolicyErrorResult> format.

Example

import { BusinessError } from '@ohos.base';
import picker from '@ohos.file.picker';

async function deactivatePermissionExample() {
  try {
    let uri = "file://docs/storage/Users/username/tmp.txt";
    let policyInfo: fileShare.PolicyInfo = {
      uri: uri,
      operationMode: fileShare.OperationMode.READ_MODE,
    };
    let policies: Array<fileShare.PolicyInfo> = [policyInfo];
    fileShare.deactivatePermission(policies).then(() => {
      console.info("deactivatePermission successfully");
    }).catch((err: BusinessError<Array<fileShare.PolicyErrorResult>>) => {
      console.info("deactivatePermission failed with error message: " + err.message + ", error code: " + err.code);
        if (err.code == 13900001 && err.data) {
          for (let i = 0; i < err.data.length; i++) {
            console.log("error code : " + JSON.stringify(err.data[i].code));
            console.log("error uri : " + JSON.stringify(err.data[i].uri));
            console.log("error reason : " + JSON.stringify(err.data[i].message));
          }
        }
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error('deactivatePermission failed with err: ' + JSON.stringify(err));
  }
}