• Home
Name Date Size #Lines LOC

..--

figures/12-May-2024-

interfaces/kits/12-May-2024-18,58014,055

utils/12-May-2024-1,6171,097

.gitattributesD12-May-2024631 1615

LICENSED12-May-20249.9 KiB176150

README.mdD12-May-202416.3 KiB256208

README_zh.mdD12-May-202416.1 KiB269219

bundle.jsonD12-May-20241.3 KiB5050

distributedfile_aafwk.gniD12-May-2024722 1614

README.md

1# Distributed File<a name="EN-US_TOPIC_0000001101541814"></a>
2
3-   [Introduction](#section104mcpsimp)
4    -   [Architecture](#section110mcpsimp)
5
6-   [Directory](#section113mcpsimp)
7-   [Constraints](#section117mcpsimp)
8-   [Usage](#section125mcpsimp)
9    -   [Available APIs](#section127mcpsimp)
10    -   [Usage Guidelines](#section149mcpsimp)
11
12-   [Repositories Involved](#section178mcpsimp)
13
14## Introduction<a name="section104mcpsimp"></a>
15
16Currently, 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.
17
18### Architecture<a name="section110mcpsimp"></a>
19
20Currently, 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.
21
22**Figure  1**  Distributed File subsystem architecture<a name="fig174088216114"></a>
23![](figures/distributed-file-subsystem-architecture.png "distributed-file-subsystem-architecture")
24
25## Directory<a name="section113mcpsimp"></a>
26
27```
28foundation/distributeddatamgr/distributedfile
29├── figures                     # Figures
30├── interfaces                  # APIs
31├    └── kits                   # APIs exposed externally
32├── utils                       # Common Components
33├    └── filemgmt_libhilog      # Log Components
34├    └── filemgmt_libn          # Platform related components
35```
36
37## Constraints<a name="section117mcpsimp"></a>
38
39Constraints on local I/O APIs:
40
41-   Only UTF-8/16 encoding is supported.
42-   The URIs cannot include external storage directories.
43
44## Usage<a name="section125mcpsimp"></a>
45
46### Available APIs<a name="section127mcpsimp"></a>
47
48Currently, the Distributed File subsystem provides APIs for accessing local files and directories. The following table describes the API types classified by function.
49
50**Table  1**  API types
51
52<a name="table99228171027"></a>
53<table><thead align="left"><tr id="row2092221715211"><th class="cellrowborder" valign="top" width="15.02%" id="mcps1.2.5.1.1"><p id="p79225171524"><a name="p79225171524"></a><a name="p79225171524"></a>API Type</p>
54</th>
55<th class="cellrowborder" valign="top" width="32.25%" id="mcps1.2.5.1.2"><p id="p992271711216"><a name="p992271711216"></a><a name="p992271711216"></a>Function</p>
56</th>
57<th class="cellrowborder" valign="top" width="25.840000000000003%" id="mcps1.2.5.1.3"><p id="p29225175213"><a name="p29225175213"></a><a name="p29225175213"></a>Related Module</p>
58</th>
59<th class="cellrowborder" valign="top" width="26.889999999999997%" id="mcps1.2.5.1.4"><p id="p129221017720"><a name="p129221017720"></a><a name="p129221017720"></a>Example API (<em id="i15670628145315"><a name="i15670628145315"></a><a name="i15670628145315"></a>Class Name</em>.<em id="i6859230125316"><a name="i6859230125316"></a><a name="i6859230125316"></a>Method Name</em>)</p>
60</th>
61</tr>
62</thead>
63<tbody><tr id="row149231717327"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p3923417629"><a name="p3923417629"></a><a name="p3923417629"></a>Basic file API</p>
64</td>
65<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p89236171124"><a name="p89236171124"></a><a name="p89236171124"></a>Creates, modifies, and accesses files, and changes file permissions based on the specified absolute paths or file descriptors.</p>
66</td>
67<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p22011844349"><a name="p22011844349"></a><a name="p22011844349"></a>@OHOS.distributedfile.fileio</p>
68</td>
69<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p1784383174320"><a name="p1784383174320"></a><a name="p1784383174320"></a>accessSync</p>
70<p id="p184313310437"><a name="p184313310437"></a><a name="p184313310437"></a>chownSync</p>
71<p id="p1684318315436"><a name="p1684318315436"></a><a name="p1684318315436"></a>chmodSync</p>
72</td>
73</tr>
74<tr id="row1692320171825"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p392391710219"><a name="p392391710219"></a><a name="p392391710219"></a>Basic directory API</p>
75</td>
76<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p109232176211"><a name="p109232176211"></a><a name="p109232176211"></a>Reads directories and determines file types based on the specified absolute paths.</p>
77</td>
78<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p271274219410"><a name="p271274219410"></a><a name="p271274219410"></a>@OHOS.distributedfile.fileio</p>
79</td>
80<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p29233177216"><a name="p29233177216"></a><a name="p29233177216"></a>Dir.openDirSync</p>
81</td>
82</tr>
83<tr id="row14923171716217"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p159234176215"><a name="p159234176215"></a><a name="p159234176215"></a>Basic statistical API</p>
84</td>
85<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p1992314179215"><a name="p1992314179215"></a><a name="p1992314179215"></a>Collects basic statistics including the file size, access permission, and modification time based on the specified absolute paths.</p>
86</td>
87<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p325774111413"><a name="p325774111413"></a><a name="p325774111413"></a>@OHOS.distributedfile.fileio</p>
88</td>
89<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p59231317420"><a name="p59231317420"></a><a name="p59231317420"></a>Stat.statSync</p>
90</td>
91</tr>
92<tr id="row692319171228"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p1592318171526"><a name="p1592318171526"></a><a name="p1592318171526"></a>Streaming file API</p>
93</td>
94<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p992311171421"><a name="p992311171421"></a><a name="p992311171421"></a>Reads and writes data streams of files based on the specified absolute paths or file descriptors.</p>
95</td>
96<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p1692321716217"><a name="p1692321716217"></a><a name="p1692321716217"></a>@OHOS.distributedfile.fileio</p>
97</td>
98<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p10923141711215"><a name="p10923141711215"></a><a name="p10923141711215"></a>Stream.createStreamSync</p>
99<p id="p88031126184311"><a name="p88031126184311"></a><a name="p88031126184311"></a>Stream.fdopenStreamSync</p>
100</td>
101</tr>
102<tr id="row82479241516"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p12923111711216"><a name="p12923111711216"></a><a name="p12923111711216"></a>Sandbox file API</p>
103</td>
104<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p49237171020"><a name="p49237171020"></a><a name="p49237171020"></a>Provides a subset or a combination of the capabilities provided by the basic file, directory, and statistical APIs based on the specified URIs.</p>
105</td>
106<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p724852418510"><a name="p724852418510"></a><a name="p724852418510"></a>@system.file</p>
107</td>
108<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p0390135216324"><a name="p0390135216324"></a><a name="p0390135216324"></a>move</p>
109<p id="p202016525456"><a name="p202016525456"></a><a name="p202016525456"></a>copy</p>
110<p id="p8142558194520"><a name="p8142558194520"></a><a name="p8142558194520"></a>list</p>
111</td>
112</tr>
113</tbody>
114</table>
115
116The URIs used in sandbox file APIs are classified into three types, as described in the following table.
117
118**Table  2**  URI types
119
120<a name="table947391523311"></a>
121<table><thead align="left"><tr id="row84733151332"><th class="cellrowborder" valign="top" width="13.969999999999999%" id="mcps1.2.5.1.1"><p id="p32271219113313"><a name="p32271219113313"></a><a name="p32271219113313"></a>Directory Type</p>
122</th>
123<th class="cellrowborder" valign="top" width="16.41%" id="mcps1.2.5.1.2"><p id="p3227191993310"><a name="p3227191993310"></a><a name="p3227191993310"></a>Prefix</p>
124</th>
125<th class="cellrowborder" valign="top" width="22%" id="mcps1.2.5.1.3"><p id="p192277196333"><a name="p192277196333"></a><a name="p192277196333"></a>Access Visibility</p>
126</th>
127<th class="cellrowborder" valign="top" width="47.620000000000005%" id="mcps1.2.5.1.4"><p id="p18227719103313"><a name="p18227719103313"></a><a name="p18227719103313"></a>Description</p>
128</th>
129</tr>
130</thead>
131<tbody><tr id="row1474161514330"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p9896152614335"><a name="p9896152614335"></a><a name="p9896152614335"></a>Temporary directory</p>
132</td>
133<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p389632610335"><a name="p389632610335"></a><a name="p389632610335"></a>internal://cache/</p>
134</td>
135<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p989610267332"><a name="p989610267332"></a><a name="p989610267332"></a>Current app only</p>
136</td>
137<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p16896726173311"><a name="p16896726173311"></a><a name="p16896726173311"></a>Readable and writable, and can be cleared at any time. This directory is usually used for temporary downloads or caches.</p>
138</td>
139</tr>
140<tr id="row194741315193312"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p12896142620339"><a name="p12896142620339"></a><a name="p12896142620339"></a>Private directory of an app</p>
141</td>
142<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p118969269332"><a name="p118969269332"></a><a name="p118969269332"></a>internal://app/</p>
143</td>
144<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p189612263333"><a name="p189612263333"></a><a name="p189612263333"></a>Current app only</p>
145</td>
146<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p1089682623314"><a name="p1089682623314"></a><a name="p1089682623314"></a>Deleted when the app is uninstalled.</p>
147</td>
148</tr>
149<tr id="row204743152331"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p3896152673319"><a name="p3896152673319"></a><a name="p3896152673319"></a>External storage</p>
150</td>
151<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p158961526113310"><a name="p158961526113310"></a><a name="p158961526113310"></a>internal://share/</p>
152</td>
153<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p16896326133310"><a name="p16896326133310"></a><a name="p16896326133310"></a>All apps</p>
154</td>
155<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p5897126113313"><a name="p5897126113313"></a><a name="p5897126113313"></a>Deleted when the app is uninstalled. Other apps with granted permissions can read and write files in this directory.</p>
156</td>
157</tr>
158</tbody>
159</table>
160
161### Usage Guidelines<a name="section149mcpsimp"></a>
162
163The I/O APIs provided by the Distributed File subsystem can be classified into the following types based on the programming model:
164
165-   Synchronous programming model
166
167    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.
168
169    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:
170
171    ```
172    import fileio from '@OHOS.distributedfile.fileio';
173
174    try {
175        var ss = fileio.createStreamSync("tmp", "r")
176        buf = new ArrayBuffer(4096)
177        ss.readSync(buf)
178        console.log(String.fromCharCode.apply(null, new Uint8Array(buf)))
179        ss.closeSync()
180    }
181    catch (e) {
182        console.log(e);
183    }
184    ```
185
186
187
188
189-   Asynchronous programming model: Callback
190
191    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.
192
193    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:
194
195    ```
196    import fileio from '@OHOS.distributedfile.fileio';
197
198    try {
199        fileio.createStream("./testdir/test_stream.txt", "r", function (err, ss) {
200            if (!err) {
201                ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) {
202                    if (!err) {
203                        console.log('readLen: ' + readLen)
204                        console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf)))
205                    } else {
206                        console.log('Cannot read from the stream ' + err)
207                    }
208                    ss.close(function (err) {
209                        console.log(`Stream is ${err ? 'not' : ''}closed`)
210                    });
211                })
212            } else {
213                console.log('Cannot open the stream ' + err)
214            }
215        })
216    } catch (e) {
217        console.log(e)
218    }
219    ```
220
221
222-   Asynchronous programming model: Legacy
223
224    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.
225
226    The following example asynchronously checks whether the file pointed to by the specified URI exists and provides three callbacks to print the check result:
227
228    ```
229    import file from '@system.file'
230
231    file.access({
232        uri: 'internal://app/test.txt',
233        success: function() {
234            console.log('call access success.');
235        },
236        fail: function(data, code) {
237            console.error('call fail callback fail, code: ' + code + ', data: ' + data);
238        },
239        complete: function () {
240            console.log('call access finally.');
241        }
242    });
243
244    console.log("file access tested done")
245    ```
246
247
248## Repositories Involved<a name="section178mcpsimp"></a>
249
250- [**distributeddatamgr_file**](https://gitee.com/openharmony/distributeddatamgr_file)
251- [filemanagement_dfs_service](https://gitee.com/openharmony/filemanagement_dfs_service)
252- [filemanagement_user_file_service](https://gitee.com/openharmony/filemanagement_user_file_service)
253- [filemanagement_storage_service](https://gitee.com/openharmony/filemanagement_storage_service)
254- [filemanagement_app_file_service](https://gitee.com/openharmony/filemanagement_app_file_service)
255
256

README_zh.md

1# 分布式文件子系统<a name="ZH-CN_TOPIC_0000001101541814"></a>
2
3-   [简介](#section104mcpsimp)
4    -   [系统架构](#section110mcpsimp)
5
6-   [目录](#section113mcpsimp)
7-   [约束](#section117mcpsimp)
8-   [说明](#section125mcpsimp)
9    -   [接口说明](#section127mcpsimp)
10    -   [使用说明](#section149mcpsimp)
11
12-   [相关仓](#section178mcpsimp)
13
14## 简介<a name="section104mcpsimp"></a>
15
16分布式文件子系统当前向应用程序提供用于的 IO 的 JS 接口。其具体包括用于管理文件的基本文件接口，用于管理目录的基本目录接口，用于获取文件信息的统计接口，用于流式读写文件的流式接口，以及接收 URI 而非绝对路径的沙盒接口。
17
18### 系统架构<a name="section110mcpsimp"></a>
19
20当前分布式文件子系统仅面向应用提供本地 JS 文件接口，这些接口分别通过 FileIO 模块以及 File 模块提供。架构上，分布式文件子系统实现了自研的 LibN，其抽象了 NAPI 层接口，向分布式文件子系统提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。本系统对外依赖 JS 开发框架提供将 JS 接口转换为 C++ 代码的能力，依赖用户程序框架提供应用相关目录，依赖 GLIBC Runtimes 提供 IO 能力。
21
22**图 1**  分布式文件子系统架构图<a name="fig174088216114"></a>
23![](figures/分布式文件子系统架构图.png "分布式文件子系统架构图")
24
25## 目录<a name="section113mcpsimp"></a>
26
27```
28foundation/distributeddatamgr/distributedfile
29├── figures                     # 仓库图床
30├── interfaces                  # 接口代码
31├    └── kits                   # 对外接口代码
32├── utils                       # 公共组件
33├    └── filemgmt_libhilog      # 日志组件
34├    └── filemgmt_libn          # 平台相关组件
35```
36
37## 约束<a name="section117mcpsimp"></a>
38
39本地 IO 接口
40
41-   目前仅支持 UTF-8/16 编码；
42-   目前 URI 暂不支持外部存储目录；
43
44## 说明<a name="section125mcpsimp"></a>
45
46### 接口说明<a name="section127mcpsimp"></a>
47
48当前分布式文件子系统开放本地文件目录访问接口，按照功能，其可划分为如下几种类型：
49
50**表 1**  接口类型表
51
52<a name="table99228171027"></a>
53<table><thead align="left"><tr id="row2092221715211"><th class="cellrowborder" valign="top" width="15.02%" id="mcps1.2.5.1.1"><p id="p79225171524"><a name="p79225171524"></a><a name="p79225171524"></a>接口类型</p>
54</th>
55<th class="cellrowborder" valign="top" width="32.25%" id="mcps1.2.5.1.2"><p id="p992271711216"><a name="p992271711216"></a><a name="p992271711216"></a>接口用途</p>
56</th>
57<th class="cellrowborder" valign="top" width="25.840000000000003%" id="mcps1.2.5.1.3"><p id="p29225175213"><a name="p29225175213"></a><a name="p29225175213"></a>相关模块</p>
58</th>
59<th class="cellrowborder" valign="top" width="26.889999999999997%" id="mcps1.2.5.1.4"><p id="p129221017720"><a name="p129221017720"></a><a name="p129221017720"></a>接口示例（类名.方法名）</p>
60</th>
61</tr>
62</thead>
63<tbody><tr id="row149231717327"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p3923417629"><a name="p3923417629"></a><a name="p3923417629"></a>基本文件接口</p>
64</td>
65<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p89236171124"><a name="p89236171124"></a><a name="p89236171124"></a>需要用户提供绝对路径或文件描述符（fd），提供创建、修改及访问文件，或修改文件权限的能力</p>
66</td>
67<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p22011844349"><a name="p22011844349"></a><a name="p22011844349"></a>@OHOS.distributedfile.fileio</p>
68</td>
69<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p1784383174320"><a name="p1784383174320"></a><a name="p1784383174320"></a>accessSync</p>
70<p id="p184313310437"><a name="p184313310437"></a><a name="p184313310437"></a>chownSync</p>
71<p id="p1684318315436"><a name="p1684318315436"></a><a name="p1684318315436"></a>chmodSync</p>
72</td>
73</tr>
74<tr id="row1692320171825"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p392391710219"><a name="p392391710219"></a><a name="p392391710219"></a>基本目录接口</p>
75</td>
76<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p109232176211"><a name="p109232176211"></a><a name="p109232176211"></a>需要用户提供绝对路径，提供读取目录及判断文件类型的能力</p>
77</td>
78<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p271274219410"><a name="p271274219410"></a><a name="p271274219410"></a>@OHOS.distributedfile.fileio</p>
79</td>
80<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p29233177216"><a name="p29233177216"></a><a name="p29233177216"></a>Dir.openDirSync</p>
81</td>
82</tr>
83<tr id="row14923171716217"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p159234176215"><a name="p159234176215"></a><a name="p159234176215"></a>基本Stat接口</p>
84</td>
85<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p1992314179215"><a name="p1992314179215"></a><a name="p1992314179215"></a>需要用户提供绝对路径，提供包括文件大小、访问权限、修改时间在内的基本统计信息</p>
86</td>
87<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p325774111413"><a name="p325774111413"></a><a name="p325774111413"></a>@OHOS.distributedfile.fileio</p>
88</td>
89<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p59231317420"><a name="p59231317420"></a><a name="p59231317420"></a>Stat.statSync</p>
90</td>
91</tr>
92<tr id="row692319171228"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p1592318171526"><a name="p1592318171526"></a><a name="p1592318171526"></a>流式文件接口</p>
93</td>
94<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p992311171421"><a name="p992311171421"></a><a name="p992311171421"></a>需要用户提供绝对路径或文件描述符，提供流式读写文件的能力</p>
95</td>
96<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p1692321716217"><a name="p1692321716217"></a><a name="p1692321716217"></a>@OHOS.distributedfile.fileio</p>
97</td>
98<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p10923141711215"><a name="p10923141711215"></a><a name="p10923141711215"></a>Stream.createStreamSync</p>
99<p id="p88031126184311"><a name="p88031126184311"></a><a name="p88031126184311"></a>Stream.fdopenStreamSync</p>
100</td>
101</tr>
102<tr id="row82479241516"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p12923111711216"><a name="p12923111711216"></a><a name="p12923111711216"></a>沙盒文件接口</p>
103</td>
104<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p49237171020"><a name="p49237171020"></a><a name="p49237171020"></a>需要用户提供 URI，提供基本文件接口、基本目录接口及基本统计接口能力的子集能力，或这些能力的组合能力</p>
105</td>
106<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p724852418510"><a name="p724852418510"></a><a name="p724852418510"></a>@system.file</p>
107</td>
108<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p0390135216324"><a name="p0390135216324"></a><a name="p0390135216324"></a>move</p>
109<p id="p202016525456"><a name="p202016525456"></a><a name="p202016525456"></a>copy</p>
110<p id="p8142558194520"><a name="p8142558194520"></a><a name="p8142558194520"></a>list</p>
111</td>
112</tr>
113</tbody>
114</table>
115
116其中，沙盒文件接口所使用的 URI 具体可划分为三种类型：
117
118**表 2**  URI类型表
119
120<a name="table947391523311"></a>
121<table><thead align="left"><tr id="row84733151332"><th class="cellrowborder" valign="top" width="13.969999999999999%" id="mcps1.2.5.1.1"><p id="p32271219113313"><a name="p32271219113313"></a><a name="p32271219113313"></a>目录类型</p>
122</th>
123<th class="cellrowborder" valign="top" width="16.41%" id="mcps1.2.5.1.2"><p id="p3227191993310"><a name="p3227191993310"></a><a name="p3227191993310"></a>路径前缀</p>
124</th>
125<th class="cellrowborder" valign="top" width="22%" id="mcps1.2.5.1.3"><p id="p192277196333"><a name="p192277196333"></a><a name="p192277196333"></a>访问可见性</p>
126</th>
127<th class="cellrowborder" valign="top" width="47.620000000000005%" id="mcps1.2.5.1.4"><p id="p18227719103313"><a name="p18227719103313"></a><a name="p18227719103313"></a>说明</p>
128</th>
129</tr>
130</thead>
131<tbody><tr id="row1474161514330"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p9896152614335"><a name="p9896152614335"></a><a name="p9896152614335"></a>临时目录</p>
132</td>
133<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p389632610335"><a name="p389632610335"></a><a name="p389632610335"></a>internal://cache/</p>
134</td>
135<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p989610267332"><a name="p989610267332"></a><a name="p989610267332"></a>仅本应用可见</p>
136</td>
137<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p16896726173311"><a name="p16896726173311"></a><a name="p16896726173311"></a>可读写，随时可能清除，不保证持久性。一般用作下载临时目录或缓存目录。</p>
138</td>
139</tr>
140<tr id="row194741315193312"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p12896142620339"><a name="p12896142620339"></a><a name="p12896142620339"></a>应用私有目录</p>
141</td>
142<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p118969269332"><a name="p118969269332"></a><a name="p118969269332"></a>internal://app/</p>
143</td>
144<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p189612263333"><a name="p189612263333"></a><a name="p189612263333"></a>仅本应用可见</p>
145</td>
146<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p1089682623314"><a name="p1089682623314"></a><a name="p1089682623314"></a>随应用卸载删除。</p>
147</td>
148</tr>
149<tr id="row204743152331"><td class="cellrowborder" valign="top" width="13.969999999999999%" headers="mcps1.2.5.1.1 "><p id="p3896152673319"><a name="p3896152673319"></a><a name="p3896152673319"></a>外部存储</p>
150</td>
151<td class="cellrowborder" valign="top" width="16.41%" headers="mcps1.2.5.1.2 "><p id="p158961526113310"><a name="p158961526113310"></a><a name="p158961526113310"></a>internal://share/</p>
152</td>
153<td class="cellrowborder" valign="top" width="22%" headers="mcps1.2.5.1.3 "><p id="p16896326133310"><a name="p16896326133310"></a><a name="p16896326133310"></a>所有应用可见</p>
154</td>
155<td class="cellrowborder" valign="top" width="47.620000000000005%" headers="mcps1.2.5.1.4 "><p id="p5897126113313"><a name="p5897126113313"></a><a name="p5897126113313"></a>随应用卸载删除。其他应用在有相应权限的情况下可读写此目录下的文件。</p>
156</td>
157</tr>
158</tbody>
159</table>
160
161### 使用说明<a name="section149mcpsimp"></a>
162
163当前分布式文件子系统所提供的 IO 接口，按照编程模型，可划分为如下几种类型：
164
165-   同步编程模型
166
167    名称包含 Sync 的接口实现为同步模型。用户在调用这些接口的时候，将同步等待，直至执行完成，执行结果以函数返回值的形式返回。
168
169    下例以只读的方式打开一个文件流，接着试图读取其中前 4096 个字节并将之转换为 UTF-8 编码的字符串，最后关闭该文件流。
170
171    ```
172    import fileio from '@OHOS.distributedfile.fileio';
173
174    try {
175        var ss = fileio.createStreamSync("tmp", "r")
176        buf = new ArrayBuffer(4096)
177        ss.readSync(buf)
178        console.log(String.fromCharCode.apply(null, new Uint8Array(buf)))
179        ss.closeSync()
180    }
181    catch (e) {
182        console.log(e);
183    }
184    ```
185
186
187-   异步编程模型：Promise
188
189    @OHOS.distributedfile.fileio 模块中，名称不含 Sync 的接口，在不提供最后一个函数型参数 callback 的时候，即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务，同时返回一个 promise 对象，其代表异步操作的结果。在返回的结果的个数超过一个时，其以对象属性的形式返回。
190
191    下例通过 Promise 链依次完成：以只读方式打开文件流、尝试读取文件前 4096 个字节、显示读取内容的长度，最后关闭文件。
192
193    ```
194    import fileio from '@OHOS.distributedfile.fileio';
195
196    try {
197        let openedStream
198        fileio.createStream("test.txt", "r")
199            .then(function (ss) {
200                openedStream = ss;
201                return ss.read(new ArrayBuffer(4096))
202            })
203            .then(function (res) {
204                console.log(res.bytesRead);
205                console.log(String.fromCharCode.apply(null, new Uint8Array(res.buffer)))
206                return openedStream.close()
207            })
208            .then(function (undefined) {
209                console.log("Stream is closed")
210            })
211            .catch(function (e) {
212                console.log(e)
213            })
214    } catch (e) {
215        console.log(e)
216    }
217    ```
218
219
220-   异步编程模型：Callback
221
222    @OHOS.distributedfile.fileio 模块中，名字不含 Sync 的接口，在提供最后一个函数性参数 callback 的时候，即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。
223
224    下例异步创建文件流，并在文件流的回调函数中异步读取文件的前 4096 字节，接着在读取文件的回调函数中异步关闭文件。
225
226    ```
227    import fileio from '@OHOS.distributedfile.fileio';
228
229    try {
230        fileio.createStream("./testdir/test_stream.txt", "r", function (err, ss) {
231            if (!err) {
232                ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) {
233                    if (!err) {
234                        console.log('readLen: ' + readLen)
235                        console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf)))
236                    } else {
237                        console.log('Cannot read from the stream ' + err)
238                    }
239                    ss.close(function (err) {
240                        console.log(`Stream is ${err ? 'not' : ''}closed`)
241                    });
242                })
243            } else {
244                console.log('Cannot open the stream ' + err)
245            }
246        })
247    } catch (e) {
248        console.log(e)
249    }
250    ```
251
252
253-   异步编程模型：Legacy
254
255    @system.file 模块中的所有接口都实现为 Legacy 异步模型。用户在调用这些接口的时候，需要提供 success、fail 及 complete 三个回调。在正确提供参数的情况下，当异步任务完成后，接口会根据是否成功，分别调用 success 回调或 fail 回调，并最终调用 complete 回调。
256
257    下例异步判断 URI 所指向的文件是否存在，并相应提供三个回调用于打印判断结果。
258
259
260
261## 相关仓<a name="section178mcpsimp"></a>
262
263- [**分布式文件子系统**](https://gitee.com/openharmony/distributeddatamgr_file)
264- [分布式文件服务](https://gitee.com/openharmony/filemanagement_dfs_service)
265- [公共文件访问框架](https://gitee.com/openharmony/filemanagement_user_file_service)
266- [存储管理服务](https://gitee.com/openharmony/filemanagement_storage_service)
267- [应用文件服务](https://gitee.com/openharmony/filemanagement_app_file_service)
268
269