diff --git a/README.md b/README.md index 76562969b350c0a8a0d32232860b134f43e815c8..683dea13961e8d6bf35167258f9ea825b2cd1c9f 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,260 @@ -# storage_app_file_manager +# File Api -#### Description -{**When you're done, you can delete the content in this README and update the file with details for others getting started with your repository**} +- [Introduction](#section104mcpsimp) + - [Architecture](#section110mcpsimp) -#### Software Architecture -Software architecture description +- [Directory](#section113mcpsimp) +- [Constraints](#section117mcpsimp) +- [Usage](#section125mcpsimp) + - [Available APIs](#section127mcpsimp) + - [Usage Guidelines](#section149mcpsimp) -#### Installation +- [Repositories Involved](#section178mcpsimp) -1. xxxx -2. xxxx -3. xxxx +## Introduction -#### Instructions +Currently, the File Api 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. -1. xxxx -2. xxxx -3. xxxx +### Architecture -#### Contribution +Currently, the File Api provides only local JavaScript file APIs for apps through the FileIO and File modules. The File Api 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. -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request +**Figure 1** File Api architecture +![](figures/file-api-architecture.png "file-api-architecture.png") +## Directory -#### Gitee Feature +``` +foundation/filemanagement/file_api +├── figures # Figures +├── interfaces # APIs +├ └── kits # APIs exposed externally +├── utils # Common Components +├ └── filemgmt_libhilog # Log Components +├ └── filemgmt_libn # Platform related components +``` + +## 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 File Api 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.fileio

+

accessSync

+

chownSync

+

chmodSync

+

Basic directory API

+

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

+

@ohos.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.fileio

+

Stat.statSync

+

Streaming file API

+

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

+

@ohos.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 File Api 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.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); + } + ``` + + +- Asynchronous programming model: Promise + + In the **@ohos.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.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) + } + ``` + + +- Asynchronous programming model: Callback + + In the **@ohos.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.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) + } + ``` + + +## Repositories Involved + +- [**File Api**](https://gitee.com/openharmony/filemanagement_file_api) +- [filemanagement_dfs_service](https://gitee.com/openharmony/filemanagement_dfs_service) +- [filemanagement_user_file_service](https://gitee.com/openharmony/filemanagement_user_file_service) +- [filemanagement_storage_service](https://gitee.com/openharmony/filemanagement_storage_service) +- [filemanagement_app_file_service](https://gitee.com/openharmony/filemanagement_app_file_service) -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) diff --git a/README_zh.md b/README_zh.md index 25fb3eb92931621d20f68452b45c55351b43c2ac..72a398d75de6faffb7e15423cfc3b86122e18647 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,28 +1,260 @@ -# 文件访问接口 +# 文件访问接口 -## 简介 +- [简介](#section104mcpsimp) + - [系统架构](#section110mcpsimp) +- [目录](#section113mcpsimp) +- [约束](#section117mcpsimp) +- [说明](#section125mcpsimp) + - [接口说明](#section127mcpsimp) + - [使用说明](#section149mcpsimp) +- [相关仓](#section178mcpsimp) -提供目录与文件管理能力，即目录和文件的访问操作接口，包括以下内容： +## 简介 -1. 提供基础文件操作的同步和异步接口 -2. 提供目录操作的异步接口 -3. 提供流式相关操作的文件接口 -4. 提供statfs接口能力 -5. 提供目录环境相关配置接口 -6. 提供本地系统扩展接口能力 +文件访问接口当前向应用程序提供用于的 IO 的 JS 接口。其具体包括用于管理文件的基本文件接口，用于管理目录的基本目录接口，用于获取文件信息的统计接口，用于流式读写文件的流式接口，以及接收 URI 而非绝对路径的沙盒接口。 -## 目录 +### 系统架构 + +文件访问接口仅面向应用提供本地 JS 文件接口，这些接口分别通过 FileIO 模块以及 File 模块提供。架构上，文件访问接口实现了自研的 LibN，其抽象了 NAPI 层接口，向文件访问接口提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。本系统对外依赖 JS 开发框架提供将 JS 接口转换为 C++ 代码的能力，依赖用户程序框架提供应用相关目录，依赖 GLIBC Runtimes 提供 IO 能力。 + +**图 1** 文件访问接口架构图 +![](figures/file-api-架构图.png "file-api-架构图") + +## 目录 ``` -interfaces # 接口代码 - └── kits # 对外JS接口代码 -LICENSE # 证书文件 +foundation/filemanagement/file_api +├── figures # 仓库图床 +├── interfaces # 接口代码 +├ └── kits # 对外接口代码 +├── utils # 公共组件 +├ └── filemgmt_libhilog # 日志组件 +├ └── filemgmt_libn # 平台相关组件 ``` -## 说明 +## 约束 + +本地 IO 接口 + +- 目前仅支持 UTF-8/16 编码； +- 目前 URI 暂不支持外部存储目录； + +## 说明 + +### 接口说明 + +当前文件访问接口开放本地文件目录访问接口，按照功能，其可划分为如下几种类型： + +**表 1** 接口类型表 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

接口类型

+

接口用途

+

相关模块

+

接口示例（类名.方法名）

+

基本文件接口

+

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

+

@ohos.fileio

+

accessSync

+

chownSync

+

chmodSync

+

基本目录接口

+

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

+

@ohos.fileio

+

Dir.openDirSync

+

基本Stat接口

+

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

+

@ohos.fileio

+

Stat.statSync

+

流式文件接口

+

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

+

@ohos.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.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.fileio 模块中，名称不含 Sync 的接口，在不提供最后一个函数型参数 callback 的时候，即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务，同时返回一个 promise 对象，其代表异步操作的结果。在返回的结果的个数超过一个时，其以对象属性的形式返回。 + + 下例通过 Promise 链依次完成：以只读方式打开文件流、尝试读取文件前 4096 个字节、显示读取内容的长度，最后关闭文件。 + + ``` + import fileio from '@ohos.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.fileio 模块中，名字不含 Sync 的接口，在提供最后一个函数性参数 callback 的时候，即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。 + + 下例异步创建文件流，并在文件流的回调函数中异步读取文件的前 4096 字节，接着在读取文件的回调函数中异步关闭文件。 + + ``` + import fileio from '@ohos.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) + } + ``` + + +## 相关仓 -### 接口说明 +- [**文件访问接口**](https://gitee.com/openharmony/filemanagement_file_api) +- [分布式文件服务](https://gitee.com/openharmony/filemanagement_dfs_service) +- [公共文件访问框架](https://gitee.com/openharmony/filemanagement_user_file_service) +- [存储管理服务](https://gitee.com/openharmony/filemanagement_storage_service) +- [应用文件服务](https://gitee.com/openharmony/filemanagement_app_file_service) -[statfs接口](https://gitee.com/openharmony/docs/tree/master/zh-cn/application-dev/reference/apis/js-apis-statfs.md)