分布式文件子系统

简介
- 系统架构
目录
约束
说明
- 接口说明
- 使用说明
相关仓

简介

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

系统架构

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

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

foundation/distributeddatamgr/distributedfile
├── figures                     # 仓库图床
├── interfaces                  # 接口代码
├    └── kits                   # 对外接口代码
├── utils                       # 公共组件
├    └── filemgmt_libhilog      # 日志组件
├    └── filemgmt_libn          # 平台相关组件

约束

本地 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.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);
}
```

异步编程模型：Promise

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

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

import fileio from '@OHOS.distributedfile.fileio';

try {
    let openedStream
    fileio.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)
}

异步编程模型：Callback

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

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

import fileio from '@OHOS.distributedfile.fileio';

try {
    fileio.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)
}

异步编程模型：Legacy

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

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

OpenHarmony / distributeddatamgr_file

分布式文件子系统

简介

系统架构

目录

约束

说明

接口说明

使用说明

相关仓

简介

发行版

贡献者

近期动态

OpenHarmony / distributeddatamgr_file .gitee-modal { width: 500px !important; }

分布式文件子系统

简介

系统架构

目录

约束

说明

接口说明

使用说明

相关仓

简介

发行版

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

OpenHarmony / distributeddatamgr_file