文件访问接口

• 简介

  • 系统架构

• 目录

• 约束

• 说明

  • 接口说明
  • 使用说明

• 相关仓

简介

文件访问接口提供基础文件IO操作能力，其具体包括用于管理文件的基本文件接口，管理目录的基本目录接口，获取文件信息的统计接口，流式读写文件的流式接口，以及文件锁接口。

系统架构

文件访问接口仅面向应用程序提供应用文件访问能力，其由ohos.file.fs模块、ohos.file.statvfs模块、ohos.file.hash模块、ohos.file.securityLabel模块和ohos.file.environment模块组成。架构上，文件访问接口实现了自研的 LibN，其抽象了 NAPI 层接口，向文件访问接口提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。

图 1 文件访问接口架构图

目录

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

约束

本地 IO 接口

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

说明

接口说明

当前文件访问接口开放本地文件目录访问接口，按照功能，其可划分为如下几种类型：

表 1 接口类型表

接口类型	接口用途	相关模块	接口示例（类名.方法名）
基本文件接口	需要用户提供沙箱路径或文件描述符（fd），提供创建、修改及访问文件的能力	@ohos.file.fs	accessSync access openSync open moveFileSync moveFile
获取目录项	需要用户提供沙箱路径，提供读取目录及过滤目录文件的能力	@ohos.file.fs	listFileSync listFile
获取文件信息接口	需要用户提供沙箱路径，提供包括文件大小、访问权限、修改时间在内的基本统计信息	@ohos.file.fs	statSync stat
流接口	需要用户提供沙箱路径或文件描述符，提供流式读写文件的能力	@ohos.file.fs	createStreamSync createStream fdopenStreamSync fdopenStream
文件锁接口	提供文件阻塞式、非阻塞式施加共享锁或独占锁，及解锁的能力	@ohos.file.fs	lock tryLock unlock

open接口可以指定mode参数以打开相应功能权限，说明如下：

表 2 OpenMode类型表

名称	类型	值	说明
READ_ONLY	number	0o0	只读打开。
WRITE_ONLY	number	0o1	只写打开。
READ_WRITE	number	0o2	读写打开。
CREATE	number	0o100	若文件不存在，则创建文件。
TRUNC	number	0o1000	如果文件存在且以只写或读写的方式打开文件，则将其长度裁剪为零。
APPEND	number	0o2000	以追加方式打开，后续写将追加到文件末尾。
NONBLOCK	number	0o4000	如果path指向FIFO、块特殊文件或字符特殊文件，则本次打开及后续 IO 进行非阻塞操作。
DIR	number	0o200000	如果path不指向目录，则出错。
NOFOLLOW	number	0o400000	如果path指向符号链接，则出错。
SYNC	number	0o4010000	以同步IO的方式打开文件。

文件过滤配置项类型，支持listFile接口使用，说明如下：

表 3 Filter

名称	类型	说明
suffix	Array<string>	文件后缀名完全匹配，各个关键词OR关系。
displayName	Array<string>	文件名模糊匹配，各个关键词OR关系。
mimeType	Array<string>	mime类型完全匹配，各个关键词OR关系。
fileSizeOver	number	文件大小匹配，大于等于指定大小的文件。
lastModifiedAfter	number	文件最近修改时间匹配，在指定时间点及之后的文件。
excludeMedia	boolean	是否排除Media中已有的文件。

使用说明

当前文件访问接口所提供的 IO 接口，按照编程模型，可划分为如下几种类型：

• 同步编程模型

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

  下例以只读的方式打开一个文件，接着试图读取其中前 4096 个字节，最后关闭该文件。

  import fs from '@ohos.file.fs';
  
  try {
      let file = fs.openSync("test.txt", fs.OpenMode.READ_ONLY);
      let readlen = fs.readSync(file.fd, new ArrayBuffer(4096));
      fs.closeSync(file);
  } catch (e) {
      console.log(e);
  }
  

• 异步编程模型：Promise

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

  下例通过 Promise 链依次完成：以只读方式打开文件，尝试读取文件前 4096 个字节，最后关闭文件。

  import fs from '@ohos.file.fs';
  
  try {
      let file = await fs.open("test.txt", fs.OpenMode.READ_ONLY);
      fs.read(file.fd, new ArrayBuffer(4096))
          .then((readLen) => {
              fs.closeSync(file);
          });
  } catch (e) {
      console.log(e);
  }
  

• 异步编程模型：Callback

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

  下例以只读方式打开文件，并在文件的回调函数中异步读取文件的前 4096 字节，最后关闭文件。

  import fs from '@ohos.file.fs';
  
  try {
      fs.open("test.txt", fs.OpenMode.READ_ONLY, (err, file) => {
          if(err) {
              console.log('file is not open');
          }
          fs.read(file.fd, new ArrayBuffer(4096))
              .then((readLen) => {
                  fs.closeSync(file);
              });
      });
  } catch (e) {
      console.log(e);
  }
  

相关仓

• 文件访问接口
• 分布式文件服务
• 公共文件访问框架
• 存储管理服务
• 应用文件服务