User File Access and Management

icon-note.gif NOTE

  • The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
  • The APIs of this module are system APIs and cannot be called by third-party applications. Currently, these APIs can be called only by filepicker.

Modules to Import

import filemanager from '@ohos.fileManager';

filemanager.getRoot

getRoot(options? : {dev? : DevInfo}) : Promise<FileInfo[]>

Obtains information about the root album or directory in asynchronous mode. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
  • Return value
Type Description
Promise<FileInfo[]> Promise used to return the root album or directory information obtained.

  • Example

    filemanager.getRoot().then((fileInfo) => {
    if(Array.isArray(fileInfo)) {
        for (var i = 0; i < fileInfo.length; i++) {
            console.log("file:"+JSON.stringify(fileInfo));
        }
    }
}).catch((err) => {
    console.log(err)
});

filemanager.getRoot

getRoot(options? : {dev? : DevInfo}, callback : AsyncCallback<FileInfo[]>) : void

Obtains information about the root album or directory in asynchronous mode. This API uses a callback to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
callback AsyncCallback<FileInfo[]> Yes Callback invoked to return the root album or directory information obtained.

  • Example

    filemanager.getRoot((err, fileInfo) => {
    if(Array.isArray(fileInfo)) {
        for (var i = 0; i < fileInfo.length; i++) {
            console.log("file:"+JSON.stringify(fileInfo));
        }
    }
});

filemanager.listFile

listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}) : Promise<FileInfo[]>

Obtains information about the second-level album or files in asynchronous mode. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
path string Yes URI of the directory to query.
type string Yes Type of the files to query. The file type can be file, image, audio, or video.
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
-  offset: position to start the query. The value is a number.
-  count: number of files to query.
  • Return value
Type Description
Promise<FileInfo[]> Promise used to return the album or file information obtained.
  • Error
Error Info Error Code Description
No such file or directory 2 The directory or album of the specified URI does not exist.
No such process 3 Failed to obtain the FMS service.
Not a directory 20 The object specified by the URI is not a directory or album.

  • Example

    // Obtain all files in the directory.
// Call listFile() and getRoot() to obtain the file URI.
let media_path = file.uri
filemanager.listFile(media_path, "file")
.then((fileInfo) => {
    if(Array.isArray(fileInfo)) {
        for (var i = 0; i < fileInfo.length; i++) {
            console.log("file:"+JSON.stringify(fileInfo));
        }
    }
}).catch((err) => {
    console.log(err)
});

filemanager.listFile

listFile(path : string, type : string, options? : {dev? : DevInfo, offset? : number, count? : number}, callback : AsyncCallback<FileInfo[]>) : void

Obtains information about the second-level album or files in asynchronous mode. This API uses a callback to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
path string Yes URI of the directory to query.
type string Yes Type of the files to query. The file type can be file, image, audio, or video.
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
-  offset: position to start the query. The value is a number.
-  count: number of files to query.
callback AsyncCallback<FileInfo[]> Yes Callback invoked to return the file information obtained.
  • Error
Error Info Error Code Description
No such file or directory 2 The directory or album of the specified URI does not exist.
No such process 3 Failed to obtain the FMS service.
Not a directory 20 The object specified by the URI is not a directory or album.

  • Example

    // Call listFile() and getRoot() to obtain the file URI.
let media_path = file.uri
filemanager.listFile(media_path, "file", (err, fileInfo) => {
    if(Array.isArray(fileInfo)) {
        for (var i = 0; i < fileInfo.length; i++) {
            console.log("file:"+JSON.stringify(fileInfo));
        }
    }
});

filemanager.createFile

filemanager.createFile(path : string, filename : string, options? : {dev? : DevInfo}) : Promise<string>

Creates a file in the specified path in asynchronous mode. This API uses a promise to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
filename string Yes Name of the file to create.
path string Yes URI of the file to create.
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
  • Return value
Type Description
promise Promise used to return the URI of the file created.
  • Error
Error Info Error Code Description
Operation not permitted 1 A file with the same name already exists.
No such file or directory 2 The directory or album of the specified URI does not exist.
No such process 3 Failed to obtain the FMS service.
Not a directory 20 The object specified by the URI is not a directory or album.

  • Example

    // Create a file.
let media_path = file.uri // Obtain the file URI using listFile() and getRoot().
let name = "xxx.jpg" // File to be saved.
filemanager.createFile(media_path, name).then((uri) => {
    // The URI of the file created is returned.
    console.log("file uri:"+uri);
}).catch((err) => {
    console.log(err);
});

filemanager.createFile

createFile(path : string, filename: string, options? : {dev? : DevInfo}, callback : AsyncCallback<string>) : void

Creates a file in the specified path in asynchronous mode. This API uses a callback to return the result.

System capability: SystemCapability.FileManagement.FileManagerService

  • Parameters
Name Type Mandatory Description
filename string Yes Name of the file to create.
path string Yes URI of the file to create.
options Object No The options are as follows:
-  dev: See DevInfo. It is dev = {name: "local"} by default if not specified. Currently, only 'local' is supported.
callback AsyncCallback<FileInfo[]> Yes Callback invoked to return the file information obtained.
  • Error
Error Info Error Code Description
Operation not permitted 1 A file with the same name already exists.
No such file or directory 2 The directory or album of the specified URI does not exist.
No such process 3 Failed to obtain the FMS service.
Not a directory 20 The object specified by the URI is not a directory or album.

  • Example

    // Create a file.
// Call listFile() and getRoot() to obtain the file URI.
let media_path = file.uri
// File to be saved.
let name = "xxx.jpg"
filemanager.createFile(media_path, name, (err, uri) => {
    // The URI of the file created is returned.
    console.log("file uri:"+uri);
});

FileInfo

Defines the file information returned by getRoot() or listFile().

System capability: SystemCapability.FileManagement.FileManagerService

Attributes

Name Type Readable Writable Description
name string Yes No File name.
path string Yes No URI of the file.
type string Yes No File type.
size number Yes No File size.
addedTime number Yes No Time when the file was scanned to the database.
modifiedTime number Yes No Time when the file was modified.

DevInfo

Defines the device type.

System capability: SystemCapability.FileManagement.FileManagerService

Attributes

Name Type Readable Writable Description
name string Yes Yes Device name.