# @ohos.file.fileAccess (User File Access and Management)
The **fileAccess** module is a framework for accessing and operating user files based on the ExtensionAbility mechanism. This module interacts with diverse file management services, such as the media library and external storage management service, and provides a set of file access and management APIs for system applications. The media library service allows access to user files on local devices and distributed devices. The external storage management service allows access to the user files stored on devices such as shared disks, USB flash drives, and SD cards.
The **fileAccess** module provides a framework for accessing and operating user files based on the ExtensionAbility mechanism. This module interacts with file management services, such as the media library and external storage management service, and provides a set of unified interfaces for system applications to access and manage files. The media library service allows access to user files on local and distributed devices. The external storage management service allows access to the user files stored on 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 **picker** and **fs**.
>- The APIs of this module support processing of error codes. For details, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
> - 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
...
...
@@ -16,9 +15,11 @@ import fileAccess from '@ohos.file.fileAccess';
Obtains information about all wants with **extension** set to **fileAccess** in the system. A want is a basic communication component used to start services. This API uses a promise to return the result.
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.
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.
Obtains information about all wants with **extension** set to **fileAccess** in the system. A want is a basic communication component used to start services. This API uses an asynchronous callback to return the result.
**Model restriction**: This API can be used only in the stage model.
Obtains information about the device root nodes of the file management service type connected to the **Helper** object. This API uses a promise to return a **RootIterator** object, which returns [RootInfo](#rootinfo) by using [next()](#rootiteratornext).
| uri | string | Yes| No| URI of the file or directory.|
| relativePath<sup>10+</sup> | 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](#fileinfo) using [next()](#next). Currently, only built-in storage devices support the file filter.
**Model restriction**: This API can be used only in the stage model.
Synchronously obtains a **FileIterator** object that recursively retrieves the files matching the conditions of the filter from a directory and returns [FileInfo](#fileinfo) using [next()](#next). Currently, this API supports only built-in storage devices.
Obtains information about the device root nodes of the file management service type connected to the **Helper** object. This API uses an asynchronous callback to return the result.
The callback has a **RootIterator** object, which returns [RootInfo](#rootinfo) through [next()](#rootiteratornext).
**Model restriction**: This API can be used only in the stage model.
Synchronously obtains the **FileIterator** object of the first-level files (directory) matching the conditions of the filter from the device root node. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext).
**Model restriction**: This API can be used only in the stage model.
| {value: [FileInfo](#fileinfo), done: boolean} | File or directory information obtained. This method traverses the specified directory until **true** is returned. The **value** field contains the file or directory information obtained.|
**Error codes**
For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
## RootInfo
Provides the device's root attribute information and APIs.
**Model restriction**: This API can be used only in the stage model.
| deviceType | number | Yes| No|Type of the device.|
| uri | string | Yes| No| Root directory URI of the device.|
| relativePath<sup>10+</sup> | 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](#fileinfo) using [next()](#next). Currently, only built-in storage devices support the file filter.
**Model restriction**: This API can be used only in the stage model.
For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
**Example**
...
...
@@ -284,7 +411,7 @@ Synchronously obtains the **FileIterator** object of the first-level files (dire
letisDone=false;
try{
letfileIterator=rootInfo.listFile();
// listFile contains the filter implementation.
// listFile() with the filter implementation.
// let fileIterator = rootInfo.listFile(filter);
if(!fileIterator){
console.error("listFile interface returns an undefined object");
...
...
@@ -302,11 +429,13 @@ Synchronously obtains the **FileIterator** object of the first-level files (dire
}
```
## RootInfo.scanFile
### scanFile
scanFile(filter?: Filter) : FileIterator
Recursively obtains the **FileIterator** object of the files matching the conditions of the filter from the device root node synchronously. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext).
Synchronously obtains a **FileIterator** object that recursively retrieves the files matching the conditions of the filter from the device root directory and returns [FileInfo](#fileinfo)using [next()](#next). Currently, this API supports only built-in storage devices.
**Model restriction**: This API can be used only in the stage model.
@@ -352,61 +485,100 @@ Recursively obtains the **FileIterator** object of the files matching the condit
}
```
## FileInfo.listfile
## RootIterator
listFile(filter?: Filter) : FileIterator
Provides an iterator object of the device root directory.
Synchronously obtains the **FileIterator** object of the next-level files (directories) matching the conditions of the filter from a directory. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext).
**Model restriction**: This API can be used only in the stage model.
| {value: [RootInfo](#rootinfo), done: boolean} | Root directory information obtained. This method traverses the directory until **true** is returned. The **value** field contains the root directory information.|
**Error codes**
For details about error codes, see [File Management Error Codes](../errorcodes/errorcode-filemanagement.md).
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](#rootinfo) by using [next](#next-1).
Recursively obtains the **FileIterator** object of the files matching the conditions of the filter from a directory synchronously. The **FileIterator** object then returns [FileInfo](#fileinfo) by using [next()](#fileiteratornext).
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](#rootinfo) by using [next](#next-1).
Moves a file or directory. This API uses a promise to return the result.
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.
Moves a file or directory. This API uses an asynchronous callback to return the result.
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.
| {value: RootInfo, done: boolean} | Root directory information obtained. This API traverses the directory until **done** returns **true**. The **value** field contains the root directory information.|
| sourceUri | string | Yes | URI of the file or directory to copy, for example, **datashare:///media/file/102**. |
| destUri | string | Yes | URI of the destination directory, for example, **datashare:///media/file/101**. |
| force | boolean | No | Whether to forcibly overwrite the file with the same name. <br>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|
| --- | -- |
| {value: FileInfo, done: boolean} | File or directory information obtained. This API traverses the specified directory until **done** returns **true**. The **value** field contains the file or directory information obtained.|
| Promise<Array<[CopyResult](#copyresult10)>> | 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.|
## RootInfo
Example 1: Copy a file with **force** unspecified.
Represents the root attribute information and interface capabilities of a device.
```js
// The media library URI 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.
letsourceFile="datashare:///media/file/102";
letdestFile="datashare:///media/file/101";
try{
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
Example 2: Copy a file or directory when **force** set to **true**.
```js
// The media library URI 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.
letsourceFile="datashare:///media/file/102";
letdestFile="datashare:///media/file/101";
try{
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
| sourceUri | string | Yes | URI of the file or directory to copy, for example, **datashare:///media/file/102**. |
| destUri | string | Yes | URI of the destination directory, for example, **datashare:///media/file/101**. |
| callback | AsyncCallback<Array<[CopyResult](#copyresult10)>> | 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.|
## FileInfo
**Example**
Represents the file or directory attribute information and interface capabilities.
```js
// The media library URI 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.
letsourceFile="datashare:///media/file/102";
letdestFile="datashare:///media/file/101";
try{
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
| sourceUri | string | Yes | URI of the file or directory to copy, for example, **datashare:///media/file/102**. |
| destUri | string | Yes | URI of the destination directory, for example, **datashare:///media/file/101**. |
| force | boolean | Yes | Whether to forcibly overwrite the file with the same name. <br>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](#copyresult10)>> | 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**
```js
// The media library URI 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.
letsourceFile="datashare:///media/file/102";
letdestFile="datashare:///media/file/101";
try{
// Obtain fileAccessHelper by referring to the sample code of fileAccess.createFileAccessHelper.
