harmony 鸿蒙@ohos.file.fileAccess (User File Access and Management)
@ohos.file.fileAccess (User File Access and Management)
The fileAccess module provides a framework for accessing and operating user files based on the ExtensionAbility mechanism. This module interacts with a variety of file management services, such as the storage management service, and provides a set of unified file access and management interfaces for system applications. The storage management service manages both the directories of the built-in storage and resources on external devices, such as shared disks, USB flash drives, and SD cards.
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.
- The APIs provided by this module are system APIs and cannot be called by third-party applications. Currently, the APIs can be called only by FilePicker and FileManager.
Modules to Import
import fileAccess from '@ohos.file.fileAccess';
fileAccess.getFileAccessAbilityInfo
getFileAccessAbilityInfo() : Promise<Array<Want>>
Obtains information about all Wants with extension set to fileAccess in the system. A Want contains information for starting an ability. This API uses a promise to return the result.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
Return value
|Type|Description| |—|–| |Promise<Array<Want>>|Promise used to return the Want information obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
import Want from '@ohos.app.ability.Want';
async function getFileAccessAbilityInfo() {
let wantInfos: Array<Want> = [];
try {
wantInfos = await fileAccess.getFileAccessAbilityInfo();
console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos));
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
fileAccess.getFileAccessAbilityInfo
getFileAccessAbilityInfo(callback: AsyncCallback<Array<Want>>): void
Obtains information about all Wants with extension set to fileAccess in the system. A Want contains information for starting an ability. This API uses an asynchronous callback to return the result.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |callback|AsyncCallback<Array<Want>>|Yes|Callback invoked to return the Want information obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
import Want from '@ohos.app.ability.Want';
async function getFileAccessAbilityInfo() {
try {
fileAccess.getFileAccessAbilityInfo((err: BusinessError, wantInfos: Array<Want>) => {
if (err) {
console.error("Failed to getFileAccessAbilityInfo in async, errCode:" + err.code + ", errMessage:" + err.message);
return;
}
console.log("getFileAccessAbilityInfo data " + JSON.stringify(wantInfos));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileAccessAbilityInfo failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
fileAccess.createFileAccessHelper
createFileAccessHelper(context: Context, wants: Array<Want>) : FileAccessHelper
Synchronously creates a Helper object to connect to the specified Wants. The Helper object provides file access and management capabilities.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |context|Context|Yes|Context of the ability.| |wants|Array<Want>|Yes|Wants to connect.|
Return value
|Type|Description| |—|–| |FileAccessHelper|Helper object created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
import Want from '@ohos.app.ability.Want';
import common from '@ohos.app.ability.common';
let context = getContext(this) as common.UIAbilityContext;
function createFileAccessHelper01() {
let fileAccessHelper: fileAccess.FileAccessHelper;
// Obtain wantInfos by using getFileAccessAbilityInfo().
let wantInfos: Array<Want> = [
{
bundleName: "com.ohos.UserFile.ExternalFileManager",
abilityName: "FileExtensionAbility",
},
]
try {
// context is passed by EntryAbility.
fileAccessHelper = fileAccess.createFileAccessHelper(context, wantInfos);
if (!fileAccessHelper) {
console.error("createFileAccessHelper interface returns an undefined object");
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
fileAccess.createFileAccessHelper
createFileAccessHelper(context: Context) : FileAccessHelper
Synchronously creates a Helper object to connect to all file management services in the system.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |context|Context|Yes|Context of the ability.|
Return value
|Type|Description| |—|–| |FileAccessHelper|Helper object created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
import common from '@ohos.app.ability.common';
let context = getContext(this) as common.UIAbilityContext;
function createFileAccessHelper02() {
let fileAccessHelperAllServer: fileAccess.FileAccessHelper;
// Create a Helper object to interact with all file management services configured with fileAccess in the system.
try {
// context is passed by EntryAbility.
fileAccessHelperAllServer = fileAccess.createFileAccessHelper(context);
if (!fileAccessHelperAllServer) {
console.error("createFileAccessHelper interface returns an undefined object");
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("createFileAccessHelper failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
FileInfo
Provides the file or directory attribute information and APIs.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Attributes
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
uri | string | Yes | No | URI of the file or directory. |
relativePath10+ | string | Yes | No | Relative path of the file or directory. |
fileName | string | Yes | No | Name of the file or directory. |
mode | number | Yes | No | Permissions on the file or directory. |
size | number | Yes | No | Size of the file or directory. |
mtime | number | Yes | No | Time when the file or directory was last modified. |
mimeType | string | Yes | No | Multipurpose Internet Mail Extensions (MIME) type of the file or directory. |
listFile
listFile(filter?: Filter) : FileIterator
Synchronously obtains a FileIterator object that lists the next-level files (directories) matching the conditions of the filter from a directory and returns FileInfo using next(). Currently, only built-in storage devices support the file filter.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|–|–| |filter|Filter|No|Filter object.|
Return value
|Type|Description| |—|–| |FileIterator|FileIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// fileInfoDir indicates information about a directory.
// let filter = { suffix : [".txt", ".jpg", ".xlsx"] };
let fileInfoDir: fileAccess.FileInfo; // = fileInfos[0];
let subfileInfos: Array<fileAccess.FileInfo> = [];
let isDone: boolean = false;
try {
let fileIterator = fileInfoDir.listFile();
// listFile() with the filter implementation.
// let fileIterator = fileInfoDir.listFile(filter);
if (!fileIterator) {
console.error("listFile interface returns an undefined object");
}
while (!isDone) {
let result = fileIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
subfileInfos.push(result.value);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
scanFile
scanFile(filter?: Filter) : FileIterator;
Synchronously obtains a FileIterator object that recursively retrieves the files matching the conditions of the filter from a directory and returns FileInfo using next(). Currently, this API supports only built-in storage devices.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|–|–| |filter|Filter|No|Filter object.|
Return value
|Type|Description| |—|–| |FileIterator|FileIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// fileInfoDir indicates information about a directory.
// let filter = {suffix : [".txt", ".jpg", ".xlsx"]};
let fileInfoDir: fileAccess.FileInfo; // = fileInfos[0];
let subfileInfos: Array<fileAccess.FileInfo> = [];
let isDone: boolean = false;
try {
let fileIterator = fileInfoDir.scanFile();
// scanFile() with the filter implementation.
// let fileIterator = fileInfoDir.scanFile(filter);
if (!fileIterator) {
console.error("scanFile interface returns an undefined object");
}
while (!isDone) {
let result = fileIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
subfileInfos.push(result.value);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
FileIterator
Provides a FileIterator object.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
next
next() : { value: FileInfo, done: boolean }
Obtains information about the next-level files or directories.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Return value
|Type|Description| |—|–| |{value: FileInfo, done: boolean}|File or directory information obtained. This API traverses the specified directory until true is returned. The value field contains the file or directory information obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
RootInfo
Provides the device’s root attribute information and APIs.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Attributes
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
deviceType | number | Yes | No | Type of the device. |
uri | string | Yes | No | Root directory URI of the device. |
relativePath10+ | string | Yes | No | Relative path of the root directory. |
displayName | string | Yes | No | Device name. |
deviceFlags | number | Yes | No | Capabilities supported by the device. |
listFile
listFile(filter?: Filter) : FileIterator
Synchronously obtains a FileIterator object that lists the first-level files (directories) matching the conditions of the filter from the device root directory and returns FileInfo using next(). Currently, only built-in storage devices support the file filter.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|–|–| |filter|Filter|No|Filter object.|
Return value
|Type|Description| |—|–| |FileIterator|FileIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// Obtain rootInfos by using getRoots().
// let filter = {suffix : [".txt", ".jpg", ".xlsx"]};
let rootInfo: fileAccess.RootInfo; // = rootinfos[0];
let fileInfos: Array<fileAccess.FileInfo> = [];
let isDone: boolean = false;
try {
let fileIterator = rootInfo.listFile();
// listFile() with the filter implementation.
// let fileIterator = rootInfo.listFile(filter);
if (!fileIterator) {
console.error("listFile interface returns an undefined object");
}
while (!isDone) {
let result = fileIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
fileInfos.push(result.value);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("listFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
scanFile
scanFile(filter?: Filter) : FileIterator
Synchronously obtains a FileIterator object that recursively retrieves the files matching the conditions of the filter from the device root directory and returns FileInfousing next(). Currently, this API supports only built-in storage devices.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|–|–| |filter|Filter|No|Filter object.|
Return value
|Type|Description| |—|–| |FileIterator|FileIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// Obtain rootInfos by using getRoots().
// let filter = {suffix : [".txt", ".jpg", ".xlsx"]};
let rootInfo: fileAccess.RootInfo; // = rootinfos[0];
let fileInfos: Array<fileAccess.FileInfo> = [];
let isDone: boolean = false;
try {
let fileIterator = rootInfo.scanFile();
// scanFile with the filter implementation.
// let fileIterator = rootInfo.scanFile(filter);
if (!fileIterator) {
console.error("scanFile interface returns undefined object");
}
while (!isDone) {
let result = fileIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
fileInfos.push(result.value);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("scanFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
RootIterator
Provides an iterator object of the device root directory.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
next
next() : { value: RootInfo, done: boolean }
Obtains the root directory of the next-level device.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Return value
|Type|Description| |—|–| |{value: RootInfo, done: boolean}|Root directory information obtained. This API traverses the directory until true is returned. The value field contains the root directory information.|
Error codes
For details about the error codes, see File Management Error Codes.
FileAccessHelper
Provides a FileAccessHelper object.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
getRoots
getRoots() : Promise<RootIterator>
Obtains information about the device root nodes of the file management service connected to the Helper object. This API uses a promise to return a RootIterator object, which returns RootInfo by using next.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Return value
|Type|Description| |—|–| |Promise<RootIterator>|Promise used to return the RootIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
async function getRoots() {
let rootIterator: fileAccess.RootIterator;
let rootinfos: Array<fileAccess.RootInfo> = [];
let isDone: boolean = false;
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
rootIterator = await fileAccessHelper.getRoots();
if (!rootIterator) {
console.error("getRoots interface returns an undefined object");
}
while (!isDone) {
let result = rootIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
rootinfos.push(result.value);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
getRoots
getRoots(callback:AsyncCallback<RootIterator>) : void
Obtains information about the device root nodes of the file management service connected to the Helper object. This API uses an asynchronous callback to return a RootIterator object, which returns RootInfo by using next.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |callback|AsyncCallback<RootIterator>|Yes|Callback invoked to return the RootIterator object obtained.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
async function getRoots() {
let rootinfos: Array<fileAccess.RootInfo> = [];
let isDone: boolean = false;
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.getRoots((err: BusinessError, rootIterator: fileAccess.RootIterator) => {
if (err) {
console.error("Failed to getRoots in async, errCode:" + err.code + ", errMessage:" + err.message);
}
while (!isDone) {
let result = rootIterator.next();
console.log("next result = " + JSON.stringify(result));
isDone = result.done;
if (!isDone) {
rootinfos.push(result.value);
}
}
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getRoots failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
createFile
createFile(uri: string, displayName: string) : Promise<string>
Creates a file in a directory. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the destination directory for the file to create.| |displayName|string|Yes|Name of the file to create. By default, the name of a local file must contain the file name extension.|
Return value
|Type|Description| |—|–| |Promise<string>|Promise used to return the URI of the file created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
let displayName: string = "file1";
let fileUri: string;
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileUri = await fileAccessHelper.createFile(sourceUri, displayName);
if (!fileUri) {
console.error("createFile return undefined object");
}
console.log("createFile sucess, fileUri: " + JSON.stringify(fileUri));
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
createFile
createFile(uri: string, displayName: string, callback: AsyncCallback<string>) : void
Creates a file in a directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the destination directory for the file to create.| |displayName|string|Yes|Name of the file to create. By default, the name of a local file must contain the file name extension.| |callback|AsyncCallback<string>|Yes|Callback invoked to return the URI of the file created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
let displayName: string = "file1";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.createFile(sourceUri, displayName, (err: BusinessError, fileUri: string) => {
if (err) {
console.error("Failed to createFile in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("createFile sucess, fileUri: " + JSON.stringify(fileUri));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("createFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
mkDir
mkDir(parentUri: string, displayName: string) : Promise<string>
Creates a directory. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |parentUri|string|Yes|URI of the destination directory for the directory to create.| |displayName|string|Yes|Name of the directory to create.|
Return value
|Type|Description| |—|–| |Promise<string>|Promise used to return the URI of the directory created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
let dirName: string = "dirTest";
let dirUri: string;
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
dirUri = await fileAccessHelper.mkDir(sourceUri, dirName);
if (!dirUri) {
console.error("mkDir return undefined object");
}
console.log("mkDir sucess, dirUri: " + JSON.stringify(dirUri));
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message);
}
mkDir
mkDir(parentUri: string, displayName: string, callback: AsyncCallback<string>) : void
Creates a directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |parentUri|string|Yes|URI of the destination directory for the directory to create.| |displayName|string|Yes|Name of the directory to create.| |callback|AsyncCallback<string>|Yes|Callback invoked to return the URI of the directory created.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
let dirName: string = "dirTest";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.mkDir(sourceUri, dirName, (err: BusinessError, dirUri: string) => {
if (err) {
console.error("Failed to mkDir in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("mkDir sucess, dirUri: " + JSON.stringify(dirUri));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("mkDir failed, errCode:" + error.code + ", errMessage:" + error.message);
}
openFile
openFile(uri: string, flags: OPENFLAGS) : Promise<number>
Opens a file. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file to open.| |flags|OPENFLAGS|Yes|File open mode.|
Return value
|Type|Description| |—|–| |Promise<number>|Promise used to return the file descriptor (FD) of the file opened.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
async function openFile01() {
// A built-in storage directory is used as an example.
// In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fd = await fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
openFile
openFile(uri: string, flags: OPENFLAGS, callback: AsyncCallback<number>) : void
Opens a file. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file to open.| |flags|OPENFLAGS|Yes|File open mode.| |callback|AsyncCallback<number>|Yes|Callback invoked to return the FD of the file opened.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.openFile(targetUri, fileAccess.OPENFLAGS.READ, (err: BusinessError, fd: number) => {
if (err) {
console.error("Failed to openFile in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("openFile sucess, fd: " + fd);
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("openFile failed, errCode:" + error.code + ", errMessage:" + error.message);
}
delete
delete(uri: string) : Promise<number>
Deletes a file or directory. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory to delete.|
Return value
|Type|Description| |—|–| |Promise<number>|Promise used to return the result.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
async function deleteFile01() {
// A built-in storage directory is used as an example.
// In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let code = await fileAccessHelper.delete(targetUri);
if (code != 0)
console.error("delete failed, code " + code);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
delete
delete(uri: string, callback: AsyncCallback<number>) : void
Deletes a file or directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory to delete.| |callback|AsyncCallback<number>|Yes|Callback invoked to return the result.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, targetUri indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let targetUri: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.delete(targetUri, (err: BusinessError, code: number) => {
if (err) {
console.error("Failed to delete in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("delete sucess, code: " + code);
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("delete failed, errCode:" + error.code + ", errMessage:" + error.message);
}
move
move(sourceFile: string, destFile: string) : Promise<string>
Moves a file or directory. This API uses a promise to return the result. Currently, this API does not support move of files or directories across devices.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |sourceFile|string|Yes|URI of the file or directory to move.| |destFile|string|Yes|URI of the destination directory, to which the file or directory will be moved.|
Return value
Type | Description |
---|---|
Promise<string> | Promise used to return the URI of the file or directory in the destination directory. |
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
async function moveFile01() {
// A built-in storage directory is used as an example.
// In the sample code, sourceFile and destFile indicate the files or directories in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fileUri = await fileAccessHelper.move(sourceFile, destFile);
console.log("move sucess, fileUri: " + JSON.stringify(fileUri));
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
move
move(sourceFile: string, destFile: string, callback: AsyncCallback<string>) : void
Moves a file or directory. This API uses an asynchronous callback to return the result. Currently, this API does not support move of files or directories across devices.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |sourceFile|string|Yes|URI of the file or directory to move.| |destFile|string|Yes|URI of the destination directory, to which the file or directory will be moved.| |callback|AsyncCallback<string>|Yes|Callback invoked to return the URI of the file or directory in the destination directory.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceFile and destFile indicate the files or directories in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.move(sourceFile, destFile, (err: BusinessError, fileUri: string) => {
if (err) {
console.error("Failed to move in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("move sucess, fileUri: " + JSON.stringify(fileUri));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("move failed, errCode:" + error.code + ", errMessage:" + error.message);
}
rename
rename(uri: string, displayName: string) : Promise<string>
Renames a file or directory. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory to rename.| |displayName|string|Yes|New name of the file or directory, which can contain the file name extension.|
Return value
|Type|Description| |—|–| |Promise<string>|Promise used to return the URI of the renamed file or directory.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
async function renameFile01() {
// A built-in storage directory is used as an example.
// In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let DestDir = await fileAccessHelper.rename(sourceDir, "testDir");
console.log("rename sucess, DestDir: " + JSON.stringify(DestDir));
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
rename
rename(uri: string, displayName: string, callback: AsyncCallback<string>) : void
Renames a file or directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory to rename.| |displayName|string|Yes|New name of the file or directory, which can contain the file name extension.| |callback|AsyncCallback<string>|Yes|Callback invoked to return the URI of the renamed file or directory.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.rename(sourceDir, "testDir", (err: BusinessError, DestDir: string) => {
if (err) {
console.error("Failed to rename in async, errCode:" + err.code + ", errMessage:" + err.message);
}
console.log("rename sucess, DestDir: " + JSON.stringify(DestDir));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("rename failed, errCode:" + error.code + ", errMessage:" + error.message);
}
access
access(sourceFileUri: string) : Promise<boolean>
Checks whether a file or directory exists. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |sourceFileUri|string|Yes|URI of the file or directory to check.|
Return value
|Type|Description| |—|–| |Promise<boolean>|Promise used to return the result.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceDir indicates a file in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
async function accessFunc() {
let sourceDir: string = "file://docs/storage/Users/currentUser/Download/1.txt";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let existJudgment = await fileAccessHelper.access(sourceDir);
if (existJudgment) {
console.log("sourceDir exists");
} else {
console.log("sourceDir does not exist");
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
access
access(sourceFileUri: string, callback: AsyncCallback<boolean>) : void
Checks whether a file or directory exists. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |sourceFileUri|string|Yes|URI of the file or directory to check.| |callback|AsyncCallback<boolean>|Yes|Callback invoked to return the result.|
Error codes
For details about the error codes, see File Management Error Codes.
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceDir indicates a folder in the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceDir: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.access(sourceDir, (err: BusinessError, existJudgment: boolean) => {
if (err) {
console.error("Failed to access in async, errCode:" + err.code + ", errMessage:" + err.message);
return;
}
if (existJudgment)
console.log("sourceDir exists");
else
console.log("sourceDir does not exist");
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("access failed, errCode:" + error.code + ", errMessage:" + error.message);
}
getFileInfoFromUri10+
getFileInfoFromUri(uri: string) : Promise<FileInfo>
Obtains a FileInfo object based on the specified URI. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory.|
Return value
|Type|Description| |—|–| |Promise<FileInfo>|Promise used to return the FileInfo object obtained.|
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
async function getUri() {
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fileInfo = await fileAccessHelper.getFileInfoFromUri(sourceUri);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileInfoFromUri failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
getFileInfoFromUri10+
getFileInfoFromUri(uri: string, callback: AsyncCallback<FileInfo>) : void
Obtains a FileInfo object based on the specified URI. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |uri|string|Yes|URI of the file or directory.| |callback|AsyncCallback<FileInfo>|Yes|Callback invoked to return the FileInfo object obtained.|
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceUri indicates the Download directory. The URI is the URI in fileInfo.
// You can use the URI obtained.
let sourceUri: string = "file://docs/storage/Users/currentUser/Download";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.getFileInfoFromUri(sourceUri, (err: BusinessError, fileInfo: fileAccess.FileInfo) => {
if (err) {
console.error("Failed to getFileInfoFromUri in async, errCode:" + err.code + ", errMessage:" + err.message);
return;
}
console.log("getFileInfoFromUri success, fileInfo: " + JSON.stringify(fileInfo));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileInfoFromUri failed, errCode:" + error.code + ", errMessage:" + error.message);
}
getFileInfoFromRelativePath10+
getFileInfoFromRelativePath(relativePath: string) : Promise<FileInfo>
Obtains a FileInfo object based on the relativePath. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |relativePath|string|Yes|Relative path of the file or directory.|
Return value
|Type|Description| |—|–| |Promise<FileInfo>|Promise used to return the FileInfo object obtained.|
Example
import { BusinessError } from '@ohos.base';
// In the sample code, relativePath indicates the Download directory, which is the relativePath in fileInfo.
// You can use the relativePath obtained.
async function getRelativePath() {
let relativePath: string = "Download/";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(relativePath);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileInfoFromRelativePath failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
getFileInfoFromRelativePath10+
getFileInfoFromRelativePath(relativePath: string, callback: AsyncCallback<FileInfo>) : void
Obtains a FileInfo object based on the relativePath. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
|Name|Type|Mandatory|Description| |—|—|—|–| |relativePath|string|Yes|Relative path of the file or directory.| |callback|AsyncCallback<FileInfo>|Yes|Callback invoked to return the FileInfo object obtained.|
Example
import { BusinessError } from '@ohos.base';
// In the sample code, relativePath indicates the Download directory, which is the relativePath in fileInfo.
// You can use the relativePath obtained.
let relativePath: string = "Download/";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.getFileInfoFromRelativePath(relativePath, (err: BusinessError, fileInfo: fileAccess.FileInfo) => {
if (err) {
console.error("Failed to getFileInfoFromRelativePath in async, errCode:" + err.code + ", errMessage:" + err.message);
return;
}
console.log("getFileInfoFromRelativePath success, fileInfo: " + JSON.stringify(fileInfo));
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("getFileInfoFromRelativePath failed, errCode:" + error.code + ", errMessage:" + error.message);
}
query10+
query(uri:string, metaJson: string) : Promise<string>
Queries the attribute information about a file or directory based on the URI. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
uri | string | Yes | URI of the file or directory (obtained from FileInfo). |
metaJson | string | Yes | Attribute FILEKEY to query. |
Return value
Type | Description |
---|---|
Promise<string> | Promised used to return the attribute queried and the value obtained. |
Example
import { BusinessError } from '@ohos.base';
async function getQuery01() {
let imageFileRelativePath: string = "/storage/Users/currentUser/Download/queryTest/image/01.jpg";
let jsonStrSingleRelativepath: string = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" });
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath);
let queryResult = await fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath);
console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message);
}
}
query10+
query(uri:string, metaJson: string, callback: AsyncCallback<string>) : void
Queries the attribute information about a file or directory based on the URI. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
uri | string | Yes | URI of the file or directory (obtained from FileInfo). |
metaJson | string | Yes | Attribute FILEKEY to query. |
callback | AsyncCallback<string> | Yes | Callback invoked to return the attribute queried and the value obtained. |
Example
import { BusinessError } from '@ohos.base';
async function getQuery02() {
let imageFileRelativePath: string = "/storage/Users/currentUser/Download/queryTest/image/01.jpg";
let jsonStrSingleRelativepath: string = JSON.stringify({ [fileAccess.FileKey.RELATIVE_PATH]: "" });
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let fileInfo = await fileAccessHelper.getFileInfoFromRelativePath(imageFileRelativePath);
fileAccessHelper.query(fileInfo.uri, jsonStrSingleRelativepath, (err: BusinessError, queryResult: string) => {
if (err) {
console.log("query_file_single faf query Failed, errCode:" + err.code + ", errMessage:" + err.message);
return;
}
console.log("query_file_single faf query, queryResult.relative_path: " + JSON.parse(queryResult).relative_path);
})
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("query_file_single faf query failed, error.code :" + error.code + ", errorMessage :" + error.message);
}
}
copy10+
copy(sourceUri: string, destUri: string, force?: boolean) : Promise<Array<CopyResult>>
Copies a file or directory. This API uses a promise to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
sourceUri | string | Yes | URI of the file or folder to copy, for example, file://docs/storage/Users/currentUser/Download/1.txt. |
destUri | string | Yes | URI of the file or folder created, for example, file://docs/storage/Users/currentUser/Download/test. |
force | boolean | No | Whether to forcibly overwrite the file with the same name. If force is true, the file with the same name will be overwritten. If force is false or not specified, the file with the same name will not be overwritten. |
Return value
Type | Description |
---|---|
Promise<Array<CopyResult>> | Promise used to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, copyResult is returned. |
Example 1: Copy a file with force unspecified.
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo.
// You can use the URI obtained.
async function copyFunc01() {
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let copyResult = await fileAccessHelper.copy(sourceFile, destFile);
if (copyResult.length === 0) {
console.log("copy success");
} else {
for (let i = 0; i < copyResult.length; i++) {
console.error("errCode" + copyResult[i].errCode);
console.error("errMsg" + copyResult[i].errMsg);
console.error("sourceUri" + copyResult[i].sourceUri);
console.error("destUri" + copyResult[i].destUri);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
Example 2: Copy a file or directory when force set to true.
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo.
// You can use the URI obtained.
async function copyFunc02() {
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let copyResult = await fileAccessHelper.copy(sourceFile, destFile, true);
if (copyResult.length === 0) {
console.log("copy success");
} else {
for (let i = 0; i < copyResult.length; i++) {
console.error("errCode" + copyResult[i].errCode);
console.error("errMsg" + copyResult[i].errMsg);
console.error("sourceUri" + copyResult[i].sourceUri);
console.error("destUri" + copyResult[i].destUri);
}
}
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
copy10+
copy(sourceUri: string, destUri: string, callback: AsyncCallback<Array<CopyResult>>) : void
Copies a file or directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
sourceUri | string | Yes | URI of the file or folder to copy, for example, file://docs/storage/Users/currentUser/Download/1.txt. |
destUri | string | Yes | URI of the file or folder created, for example, file://docs/storage/Users/currentUser/Download/test. |
callback | AsyncCallback<Array<CopyResult>> | Yes | Callback invoked to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, copyResult is returned. |
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo.
// You can use the URI obtained.
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.copy(sourceFile, destFile, async (err: BusinessError, copyResult: Array<fileAccess.CopyResult>) => {
if (err) {
console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message);
}
if (copyResult.length === 0) {
console.log("copy success");
} else {
for (let i = 0; i < copyResult.length; i++) {
console.error("errCode" + copyResult[i].errCode);
console.error("errMsg" + copyResult[i].errMsg);
console.error("sourceUri" + copyResult[i].sourceUri);
console.error("destUri" + copyResult[i].destUri);
}
}
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message);
}
copy10+
copy(sourceUri: string, destUri: string, force: boolean, callback: AsyncCallback<Array<CopyResult>>) : void
Copies a file or directory. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
sourceUri | string | Yes | URI of the file or folder to copy, for example, file://docs/storage/Users/currentUser/Download/1.txt. |
destUri | string | Yes | URI of the file or folder created, for example, file://docs/storage/Users/currentUser/Download/test. |
force | boolean | Yes | Whether to forcibly overwrite the file with the same name. If force is true, the file with the same name will be overwritten. If force is false or not specified, the file with the same name will not be overwritten. |
callback | AsyncCallback<Array<CopyResult>> | Yes | Callback invoked to return the result. If the file or directory is copied successfully, no information is returned. If the file copy fails, copyResult is returned. |
Example
import { BusinessError } from '@ohos.base';
// A built-in storage directory is used as an example.
// In the sample code, sourceFile indicates the file (directory) in the Download directory to copy, destFile indicates the destination directory in the Download directory, and uri is to URI in fileInfo.
// You can use the URI obtained.
let sourceFile: string = "file://docs/storage/Users/currentUser/Download/1.txt";
let destFile: string = "file://docs/storage/Users/currentUser/Download/test";
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
fileAccessHelper.copy(sourceFile, destFile, true, async (err: BusinessError, copyResult: Array<fileAccess.CopyResult>) => {
if (err) {
console.error("copy failed, errCode:" + err.code + ", errMessage:" + err.message);
}
if (copyResult.length === 0) {
console.log("copy success");
} else {
for (let i = 0; i < copyResult.length; i++) {
console.error("errCode" + copyResult[i].errCode);
console.error("errMsg" + copyResult[i].errMsg);
console.error("sourceUri" + copyResult[i].sourceUri);
console.error("destUri" + copyResult[i].destUri);
}
}
});
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("copy failed, errCode:" + error.code + ", errMessage:" + error.message);
}
registerObserver10+
registerObserver(uri: string, notifyForDescendants: boolean, callback: Callback<NotifyMessage>): void
Registers a callback to listen for the specified URI. URIs and callbacks can be in many-to-many relationships. You are advised to use one callback to observe one URI.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
uri | string | Yes | URI of the file or directory to observe. |
notifyForDescendants | boolean | Yes | Whether to observe changes of the files in the directory. |
callback | Callback<NotifyMessage> | Yes | Callback invoked to return the notification. |
Example 1: Register a callback to listen for a URI.
import { BusinessError } from '@ohos.base';
async function registerObserver01() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri1 = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR1');
let dirUri2 = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR2');
// Two notifications are expected to receive because notifyForDescendants is set to true during registration.
// The URI is 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE', and the event type is NOTIFY_MOVED_FROM.
// The URI is 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE', and the event type is NOTIFY_MOVE_SELF.
const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
// The notification expected to receive is about the NOTIFY_MOVED_TO event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR2/SUB_FILE'.
const callbackDir2 = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
// The notification expected to receive is about the NOTIFY_MOVE_SELF event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'.
// The notification expected to receive is about the NOTIFY_MOVED_FROM event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR1/SUB_FILE'.
const callbackFile = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
let fileUri = await fileAccessHelper.createFile(dirUri1, 'SUB_FILE');
fileAccessHelper.registerObserver(dirUri1, true, callbackDir1);
fileAccessHelper.registerObserver(dirUri2, true, callbackDir2);
// If the moved file itself is not listened for, the NOTIFY_MOVE_SELF event will not be triggered.
fileAccessHelper.registerObserver(fileUri, true, callbackFile);
let moveFileUri = await fileAccessHelper.move(fileUri, dirUri2);
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri1, callbackDir1);
fileAccessHelper.unregisterObserver(dirUri2, callbackDir2);
fileAccessHelper.unregisterObserver(fileUri, callbackFile);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
Example 2: Use the same uri, notifyForDescendants, and callback to register repeatedly.
import { BusinessError } from '@ohos.base';
async function registerObserver02() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR');
// The notification expected to receive is about the NOTIFY_ADD event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_DIR'.
const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
fileAccessHelper.registerObserver(dirUri, true, callbackDir);
// A message is returned indicating that the registration is successful. Repeated registration is reported only in the log.
fileAccessHelper.registerObserver(dirUri, true, callbackDir);
let subDirUri = await fileAccessHelper.mkDir(dirUri, 'SUB_DIR');
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri, callbackDir);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
Example 3: Use the same uri and callback but different notifyForDescendants for registration. In this case, notifyForDescendants will be reset.
import { BusinessError } from '@ohos.base';
async function registerObserver03() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR');
// The first notification expected to receive is about the NOTIFY_ADD event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_FILE_1'.
// No second return is expected.
const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
fileAccessHelper.registerObserver(dirUri, true, callbackDir);
let subFile1 = await fileAccessHelper.createFile(dirUri, 'SUB_FILE_1');
// After the registration is successful, change notifyForDescendants to false.
fileAccessHelper.registerObserver(dirUri, false, callbackDir);
let subFile2 = await fileAccessHelper.createFile(dirUri, 'SUB_FILE_2');
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri, callbackDir);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("registerObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
unregisterObserver10+
unregisterObserver(uri: string, callback?: Callback<NotifyMessage>): void
Unregisters a callback that is used to listen for the specified URI.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
uri | string | Yes | URI of the target file or directory. |
callback | Callback<NotifyMessage> | No | Callback to unregister. If this parameter is not specified, all callbacks of the specified URI will be unregistered. |
Example 1: Deregister a callback of the specified URI.
import { BusinessError } from '@ohos.base';
async function UnregisterObserver01() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR');
// The notification expected to receive is about the NOTIFY_DELETE event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR'.
const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
fileAccessHelper.registerObserver(dirUri, true, callbackDir);
await fileAccessHelper.delete(dirUri);
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri, callbackDir);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
Example 2: Repeatedly unregister a callback of the specified URI.
import { BusinessError } from '@ohos.base';
async function UnregisterObserver02() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR');
// The notification expected to receive is about the NOTIFY_DELETE event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR'.
const callbackDir = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
fileAccessHelper.registerObserver(dirUri, true, callbackDir);
await fileAccessHelper.delete(dirUri);
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri, callbackDir);
// If the unregistration fails, throw the error code E_CAN_NOT_FIND_URI.
fileAccessHelper.unregisterObserver(dirUri, callbackDir);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
Example 3: Unregister all callbacks of the specified URI.
import { BusinessError } from '@ohos.base';
async function UnregisterObserver03() {
let DirUri: string = 'file://docs/storage/Users/currentUser/Documents';
try {
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
let dirUri = await fileAccessHelper.mkDir(DirUri, 'NOTIFY_DIR');
// The notification expected to receive is about the NOTIFY_MOVED_FROM event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/SUB_FILE'.
// The notification expected to receive is about the NOTIFY_MOVED_TO event of the URI 'file://docs/storage/Users/currentUser/Documents/NOTIFY_DIR/RENAME_FILE'.
const callbackDir1 = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
// No notification is expected to receive.
const callbackDir2 = (NotifyMessageDir: fileAccess.NotifyMessage) => {
if (NotifyMessageDir != undefined) {
console.log('NotifyType: ' + NotifyMessageDir.NotifyType + 'NotifyUri:' + NotifyMessageDir.uri[0]);
} else {
console.error("NotifyMessageDir is undefined");
}
}
let fileUri = await fileAccessHelper.createFile(dirUri, 'SUB_FILE');
fileAccessHelper.registerObserver(dirUri, true, callbackDir1);
// The registration does not include the events about the next-level directory.
fileAccessHelper.registerObserver(dirUri, false, callbackDir2);
let renameUri = await fileAccessHelper.rename(fileUri, 'RENAME_FILE');
// Unregister all callbacks (callbackDir1 and callbackDir2) of dirUri.
// Do not unregister the callback immediately after the registration is complete, because the unregistration result may be returned before the notification is returned. If this occurs, the notification wll not be received.
fileAccessHelper.unregisterObserver(dirUri);
await fileAccessHelper.delete(dirUri);
} catch (err) {
let error: BusinessError = err as BusinessError;
console.error("unregisterObserver failed, errCode:" + error.code + ", errMessage:" + error.message);
}
}
CopyResult10+
Defines the information returned when the file copy operation fails. If the copy operation is successful, no information is returned.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
sourceUri | string | Yes | No | URI of the source file or directory. |
destUri | string | Yes | No | URI of the conflict file. If the error is not caused by a conflict, destUri is empty. |
errCode | number | Yes | No | Error code. |
errMsg | string | Yes | No | Error information. |
OPENFLAGS
Enumerates the file open modes.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Name | Value | Description |
---|---|---|
READ | 0o0 | Read mode. |
WRITE | 0o1 | Write mode. |
WRITE_READ | 0o2 | Read/Write mode. |
FILEKEY10+
Enumerates the keys of the file attributes to query.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Name | Value | Description |
---|---|---|
DISPLAY_NAME | ‘display_name’ | Name of the file. |
DATE_ADDED | ‘date_added’ | Date when the file was created, for example, 1501925454. |
DATE_MODIFIED | ‘date_modified’ | Date when a file was modified, for example, 1665310670. |
RELATIVE_PATH | ‘relative_path’ | Relative path of the file, for example, Pictures/Screenshots/. |
FILE_SIZE | ‘size’ | Size of a file, in bytes. |
NotifyType10+
Enumerates the notification types.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Name | Value | Description |
---|---|---|
NOTIFY_ADD | 0 | File added. See examples 2 and 3 of registerObserver. |
NOTIFY_DELETE | 1 | File deleted. See examples 1 and 2 of unregisterObserver(uri: string, callback: Callback<NotifyMessage>). |
NOTIFY_MOVED_TO | 2 | File or folder moved in (for example, a file or folder in the target directory is renamed, or a file or folder is moved to the target directory). See example 1 of registerObserver and example 1 of unregisterObserver(uri: string). |
NOTIFY_MOVED_FROM | 3 | File or folder moved out (for example, a file or folder in the target directory is renamed and no longer in the target directory, or a file or folder is moved out from the target directory). See example 1 of registerObserver and example 1 of unregisterObserver(uri: string). |
NOTIFY_MOVE_SELF | 4 | File moved (for example, the target file or folder is renamed or moved). See example 1 registerObserver. |
NotifyMessage10+
Represents the notification message.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.FileManagement.UserFileService
Required permissions: ohos.permission.FILE_ACCESS_MANAGER
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
type | NotifyType | Yes | No | Notification type. |
uris | Array<string> | Yes | No | URIs of the changed files. Currently, only one notification is supported. A collection of multiple notifications will be supported in later versions. |
你可能感兴趣的鸿蒙文章
harmony 鸿蒙System Common Events (To Be Deprecated Soon)
harmony 鸿蒙System Common Events
harmony 鸿蒙API Reference Document Description
harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)
harmony 鸿蒙BundleStatusCallback
harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)
harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)
harmony 鸿蒙@ohos.bundle (Bundle)
harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)
- 所属分类: 后端技术
- 本文标签:
热门推荐
-
2、 - 优质文章
-
3、 gate.io
-
8、 golang
-
9、 openharmony
-
10、 Vue中input框自动聚焦