4 Star 8 Fork 20

OpenHarmony / distributeddatamgr_file

Create your Gitee Account
Explore and code with more than 6 million developers,Free private repositories !:)
Sign up
Clone or Download
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README.md

Distributed File

Introduction

Currently, the Distributed File subsystem provides apps with JavaScript APIs for I/O capabilities, including APIs for managing files and directories, obtaining file information, reading and writing data streams of files, and receiving URIs rather than absolute paths.

Architecture

Currently, the Distributed File subsystem provides only local JavaScript file APIs for apps through the FileIO and File modules. The Distributed File subsystem uses LibN to abstract APIs at the NAPI layer, providing basic capabilities such as the basic type system, memory management, and general programming models for the subsystem. This subsystem depends on the engine layer of the JS application development framework to provide the capability of converting JavaScript APIs into C++ code, depends on the application framework to provide app-related directories, and depends on the GLIBC runtimes to provide I/O capabilities.

Figure 1 Distributed File subsystem architecture

Directory Structure

foundation/distributeddatamgr/distributedfile
└── interfaces                  # APIs
    └── kits                    # APIs exposed externally

Constraints

Constraints on local I/O APIs:

  • Only UTF-8/16 encoding is supported.
  • The URIs cannot include external storage directories.

Usage

Available APIs

Currently, the Distributed File subsystem provides APIs for accessing local files and directories. The following table describes the API types classified by function.

Table 1 API types

API Type

Function

Related Module

Example API (Class Name.Method Name)

Basic file API

Creates, modifies, and accesses files, and changes file permissions based on the specified absolute paths or file descriptors.

@OHOS.distributedfile.fileio

accessSync

chownSync

chmodSync

Basic directory API

Reads directories and determines file types based on the specified absolute paths.

@OHOS.distributedfile.fileio

Dir.openDirSync

Basic statistical API

Collects basic statistics including the file size, access permission, and modification time based on the specified absolute paths.

@OHOS.distributedfile.fileio

Stat.statSync

Streaming file API

Reads and writes data streams of files based on the specified absolute paths or file descriptors.

@OHOS.distributedfile.fileio

Stream.createStreamSync

Stream.fdopenStreamSync

Sandbox file API

Provides a subset or a combination of the capabilities provided by the basic file, directory, and statistical APIs based on the specified URIs.

@system.file

move

copy

list

The URIs used in sandbox file APIs are classified into three types, as described in the following table.

Table 2 URI types

Directory Type

Prefix

Access Visibility

Description

Temporary directory

internal://cache/

Current app only

Readable and writable, and can be cleared at any time. This directory is usually used for temporary downloads or caches.

Private directory of an app

internal://app/

Current app only

Deleted when the app is uninstalled.

External storage

internal://share/

All apps

Deleted when the app is uninstalled. Other apps with granted permissions can read and write files in this directory.

Usage Guidelines

The I/O APIs provided by the Distributed File subsystem can be classified into the following types based on the programming model:

  • Synchronous programming model

    APIs whose names contain Sync are implemented as a synchronous model. When a synchronous API is called, the calling process waits until a value is returned.

    The following example opens a file stream in read-only mode, attempts to read the first 4096 bytes, converts them into a UTF-8-encoded string, and then closes the file stream:

    import fileio from '@OHOS.distributedfile.fileio';
    
    try {
        var ss = fileio.Stream.createStreamSync("tmp", "r")
        buf = new ArrayBuffer(4096)
        ss.readSync(buf)
        console.log(String.fromCharCode.apply(null, new Uint8Array(buf)))
        ss.closeSync()
    }
    catch (e) {
        console.log(e);
    }
  • Asynchronous programming model: Promise

    In the @OHOS.distributedfile.fileio module, the APIs whose names do not contain Sync and to which a callback is not passed as their input parameter are implemented as the Promise asynchronous model. The Promise asynchronous model is one of the OHOS standard asynchronous models. When an asynchronous API using the Promise model is called, the API returns a Promise object while executing the concerned task asynchronously. The Promise object represents the asynchronous operation result. When there is more than one result, the results are returned as properties of the Promise object.

    In the following example, a Promise chain is used to open a file stream in read-only mode, attempt to read the first 4096 bytes of the file, display the length of the content read, and then close the file:

    import fileio from '@OHOS.distributedfile.fileio';
    
    try {
        let openedStream
        fileio.Stream.createStream("test.txt", "r")
            .then(function (ss) {
                openedStream = ss;
                return ss.read(new ArrayBuffer(4096))
            })
            .then(function (res) {
                console.log(res.bytesRead);
                console.log(String.fromCharCode.apply(null, new Uint8Array(res.buffer)))
                return openedStream.close()
            })
            .then(function (undefined) {
                console.log("Stream is closed")
            })
            .catch(function (e) {
                console.log(e)
            })
    } catch (e) {
        console.log(e)
    }
  • Asynchronous programming model: Callback

    In the @OHOS.distributedfile.fileio module, the APIs whose names do not contain Sync and to which a callback is directly passed as their input parameter are implemented as the callback asynchronous model. The callback asynchronous model is also one of the OHOS standard asynchronous models. When an asynchronous API with a callback passed is called, the API executes the concerned task asynchronously and returns the execution result as the input parameters of the registered callback. The first parameter is of the undefined or Error type, indicating that the execution succeeds or fails, respectively.

    The following example creates a file stream asynchronously, reads the first 4096 bytes of the file asynchronously in the callback invoked when the file stream is created, and then closes the file asynchronously in the callback invoked when the file is read:

    import fileio from '@OHOS.distributedfile.fileio';
    
    try {
        fileio.Stream.createStream("./testdir/test_stream.txt", "r", function (err, ss) {
            if (!err) {
                ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) {
                    if (!err) {
                        console.log('readLen: ' + readLen)
                        console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf)))
                    } else {
                        console.log('Cannot read from the stream ' + err)
                    }
                    ss.close(function (err) {
                        console.log(`Stream is ${err ? 'not' : ''}closed`)
                    });
                })
            } else {
                console.log('Cannot open the stream ' + err)
            }
        })
    } catch (e) {
        console.log(e)
    }
  • Asynchronous programming model: Legacy

    All APIs in the @system.file module are implemented as the legacy asynchronous model. When calling such an API, you need to implement three callbacks (including success, fail, and complete) to be invoked when the execution is successful, fails, or is complete, respectively. If the input parameters are correct, the API calls the success or fail callback based on whether the asynchronous task is successful after the task execution is complete, and finally calls the complete callback.

    The following example asynchronously checks whether the file pointed to by the specified URI exists and provides three callbacks to print the check result:

    import file from '@system.file'
    
    file.access({
        uri: 'internal://app/test.txt',
        success: function() {
            console.log('call access success.');
        },
        fail: function(data, code) {
            console.error('call fail callback fail, code: ' + code + ', data: ' + data);
        },
        complete: function () {
            console.log('call access finally.');
        }
    });
    
    console.log("file access tested done")

Repositories Involved

Distributed File subsystem

distributeddatamgr_distributedfile

Repository Comments ( 0 )

Sign in to post a comment

About

Providing JavaScript APIs for file management | 提供适用于文件管理的 JS 接口 expand collapse
C++ and 2 more languages
Apache-2.0
Cancel

Releases

No release

OpenHarmony

Contributors

All

Activities

Load More
can not load any more
1
https://git.oschina.net/openharmony/distributeddatamgr_file.git
git@git.oschina.net:openharmony/distributeddatamgr_file.git
openharmony
distributeddatamgr_file
distributeddatamgr_file
master

Search

161121 f78d6d6f 1850385 154831 86f8c370 1850385