分布式文件子系统

About 10 min

分布式文件子系统

简介

分布式文件子系统当前向应用程序提供用于的 IO 的 JS 接口。其具体包括用于管理文件的基本文件接口,用于管理目录的基本目录接口,用于获取文件信息的统计接口,用于流式读写文件的流式接口,以及接收 URI 而非绝对路径的沙盒接口。

系统架构

当前分布式文件子系统仅面向应用提供本地 JS 文件接口,这些接口分别通过 FileIO 模块以及 File 模块提供。架构上,分布式文件子系统实现了自研的 LibN,其抽象了 NAPI 层接口,向分布式文件子系统提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。本系统对外依赖 JS 开发框架提供将 JS 接口转换为 C++ 代码的能力,依赖用户程序框架提供应用相关目录,依赖 GLIBC Runtimes 提供 IO 能力。

图 1 分布式文件子系统架构图

目录结构

foundation/distributeddatamgr/distributedfile
├── interfaces                  # 接口层代码
│   └── kits                    # 对外接口
1
2
3

约束

本地 IO 接口

  • 目前仅支持 UTF-8/16 编码;
  • 目前 URI 暂不支持外部存储目录;

说明

接口说明

当前分布式文件子系统开放本地文件目录访问接口,按照功能,其可划分为如下几种类型:

表 1 接口类型表

接口类型

接口用途

相关模块

接口示例(类名.方法名)

基本文件接口

需要用户提供绝对路径或文件描述符(fd),提供创建、修改及访问文件,或修改文件权限的能力

@OHOS.distributedfile.fileio

accessSync

chownSync

chmodSync

基本目录接口

需要用户提供绝对路径,提供读取目录及判断文件类型的能力

@OHOS.distributedfile.fileio

Dir.openDirSync

基本Stat接口

需要用户提供绝对路径,提供包括文件大小、访问权限、修改时间在内的基本统计信息

@OHOS.distributedfile.fileio

Stat.statSync

流式文件接口

需要用户提供绝对路径或文件描述符,提供流式读写文件的能力

@OHOS.distributedfile.fileio

Stream.createStreamSync

Stream.fdopenStreamSync

沙盒文件接口

需要用户提供 URI,提供基本文件接口、基本目录接口及基本统计接口能力的子集能力,或这些能力的组合能力

@system.file

move

copy

list

其中,沙盒文件接口所使用的 URI 具体可划分为三种类型:

表 2 URI类型表

目录类型

路径前缀

访问可见性

说明

临时目录

internal://cache/

仅本应用可见

可读写,随时可能清除,不保证持久性。一般用作下载临时目录或缓存目录。

应用私有目录

internal://app/

仅本应用可见

随应用卸载删除。

外部存储

internal://share/

所有应用可见

随应用卸载删除。其他应用在有相应权限的情况下可读写此目录下的文件。

使用说明

当前分布式文件子系统所提供的 IO 接口,按照编程模型,可划分为如下几种类型:

  • 同步编程模型

    名称包含 Sync 的接口实现为同步模型。用户在调用这些接口的时候,将同步等待,直至执行完成,执行结果以函数返回值的形式返回。

    下例以只读的方式打开一个文件流,接着试图读取其中前 4096 个字节并将之转换为 UTF-8 编码的字符串,最后关闭该文件流。

    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);
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
  • 异步编程模型:Promise

    @OHOS.distributedfile.fileio 模块中,名称不含 Sync 的接口,在不提供最后一个函数型参数 callback 的时候,即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候,接口实现将异步执行任务,同时返回一个 promise 对象,其代表异步操作的结果。在返回的结果的个数超过一个时,其以对象属性的形式返回。

    下例通过 Promise 链依次完成:以只读方式打开文件流、尝试读取文件前 4096 个字节、显示读取内容的长度,最后关闭文件。

    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)
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
  • 异步编程模型:Callback

    @OHOS.distributedfile.fileio 模块中,名字不含 Sync 的接口,在提供最后一个函数性参数 callback 的时候,即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候,接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型,分别表示执行出错与正常。

    下例异步创建文件流,并在文件流的回调函数中异步读取文件的前 4096 字节,接着在读取文件的回调函数中异步关闭文件。

    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)
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
  • 异步编程模型:Legacy

    @system.file 模块中的所有接口都实现为 Legacy 异步模型。用户在调用这些接口的时候,需要提供 success、fail 及 complete 三个回调。在正确提供参数的情况下,当异步任务完成后,接口会根据是否成功,分别调用 success 回调或 fail 回调,并最终调用 complete 回调。

    下例异步判断 URI 所指向的文件是否存在,并相应提供三个回调用于打印判断结果。

    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")
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16

相关仓

分布式文件

distributeddatamgr_distributedfile