README.md
1# Distributed File<a name="EN-US_TOPIC_0000001101541814"></a>
2
3- [Introduction](#section104mcpsimp)
4 - [Architecture](#section110mcpsimp)
5
6- [Directory Structure](#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
24
25## Directory Structure<a name="section113mcpsimp"></a>
26
27```
28foundation/distributeddatamgr/distributedfile
29└── interfaces # APIs
30 └── kits # APIs exposed externally
31```
32
33## Constraints<a name="section117mcpsimp"></a>
34
35Constraints on local I/O APIs:
36
37- Only UTF-8/16 encoding is supported.
38- The URIs cannot include external storage directories.
39
40## Usage<a name="section125mcpsimp"></a>
41
42### Available APIs<a name="section127mcpsimp"></a>
43
44Currently, the Distributed File subsystem provides APIs for accessing local files and directories. The following table describes the API types classified by function.
45
46**Table 1** API types
47
48<a name="table99228171027"></a>
49<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>
50</th>
51<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>
52</th>
53<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>
54</th>
55<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>
56</th>
57</tr>
58</thead>
59<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>
60</td>
61<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>
62</td>
63<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>
64</td>
65<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>
66<p id="p184313310437"><a name="p184313310437"></a><a name="p184313310437"></a>chownSync</p>
67<p id="p1684318315436"><a name="p1684318315436"></a><a name="p1684318315436"></a>chmodSync</p>
68</td>
69</tr>
70<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>
71</td>
72<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>
73</td>
74<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>
75</td>
76<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>
77</td>
78</tr>
79<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>
80</td>
81<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>
82</td>
83<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>
84</td>
85<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>
86</td>
87</tr>
88<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>
89</td>
90<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>
91</td>
92<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>
93</td>
94<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>
95<p id="p88031126184311"><a name="p88031126184311"></a><a name="p88031126184311"></a>Stream.fdopenStreamSync</p>
96</td>
97</tr>
98<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>
99</td>
100<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>
101</td>
102<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>
103</td>
104<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>
105<p id="p202016525456"><a name="p202016525456"></a><a name="p202016525456"></a>copy</p>
106<p id="p8142558194520"><a name="p8142558194520"></a><a name="p8142558194520"></a>list</p>
107</td>
108</tr>
109</tbody>
110</table>
111
112The URIs used in sandbox file APIs are classified into three types, as described in the following table.
113
114**Table 2** URI types
115
116<a name="table947391523311"></a>
117<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>
118</th>
119<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>
120</th>
121<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>
122</th>
123<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>
124</th>
125</tr>
126</thead>
127<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>
128</td>
129<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>
130</td>
131<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>
132</td>
133<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>
134</td>
135</tr>
136<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>
137</td>
138<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>
139</td>
140<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>
141</td>
142<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>
143</td>
144</tr>
145<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>
146</td>
147<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>
148</td>
149<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>
150</td>
151<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>
152</td>
153</tr>
154</tbody>
155</table>
156
157### Usage Guidelines<a name="section149mcpsimp"></a>
158
159The I/O APIs provided by the Distributed File subsystem can be classified into the following types based on the programming model:
160
161- Synchronous programming model
162
163 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.
164
165 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:
166
167 ```
168 import fileio from '@OHOS.distributedfile.fileio';
169
170 try {
171 var ss = fileio.Stream.createStreamSync("tmp", "r")
172 buf = new ArrayBuffer(4096)
173 ss.readSync(buf)
174 console.log(String.fromCharCode.apply(null, new Uint8Array(buf)))
175 ss.closeSync()
176 }
177 catch (e) {
178 console.log(e);
179 }
180 ```
181
182
183- Asynchronous programming model: Promise
184
185 In the **@OHOS.distributedfile.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.
186
187 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:
188
189 ```
190 import fileio from '@OHOS.distributedfile.fileio';
191
192 try {
193 let openedStream
194 fileio.Stream.createStream("test.txt", "r")
195 .then(function (ss) {
196 openedStream = ss;
197 return ss.read(new ArrayBuffer(4096))
198 })
199 .then(function (res) {
200 console.log(res.bytesRead);
201 console.log(String.fromCharCode.apply(null, new Uint8Array(res.buffer)))
202 return openedStream.close()
203 })
204 .then(function (undefined) {
205 console.log("Stream is closed")
206 })
207 .catch(function (e) {
208 console.log(e)
209 })
210 } catch (e) {
211 console.log(e)
212 }
213 ```
214
215
216- Asynchronous programming model: Callback
217
218 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.
219
220 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:
221
222 ```
223 import fileio from '@OHOS.distributedfile.fileio';
224
225 try {
226 fileio.Stream.createStream("./testdir/test_stream.txt", "r", function (err, ss) {
227 if (!err) {
228 ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) {
229 if (!err) {
230 console.log('readLen: ' + readLen)
231 console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf)))
232 } else {
233 console.log('Cannot read from the stream ' + err)
234 }
235 ss.close(function (err) {
236 console.log(`Stream is ${err ? 'not' : ''}closed`)
237 });
238 })
239 } else {
240 console.log('Cannot open the stream ' + err)
241 }
242 })
243 } catch (e) {
244 console.log(e)
245 }
246 ```
247
248
249- Asynchronous programming model: Legacy
250
251 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.
252
253 The following example asynchronously checks whether the file pointed to by the specified URI exists and provides three callbacks to print the check result:
254
255 ```
256 import file from '@system.file'
257
258 file.access({
259 uri: 'internal://app/test.txt',
260 success: function() {
261 console.log('call access success.');
262 },
263 fail: function(data, code) {
264 console.error('call fail callback fail, code: ' + code + ', data: ' + data);
265 },
266 complete: function () {
267 console.log('call access finally.');
268 }
269 });
270
271 console.log("file access tested done")
272 ```
273
274
275## Repositories Involved<a name="section178mcpsimp"></a>
276
277**Distributed File subsystem**
278
279distributeddatamgr_distributedfile
280
281
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
24
25## 目录结构<a name="section113mcpsimp"></a>
26
27```
28foundation/distributeddatamgr/distributedfile
29├── figures # 仓库图床
30└── interfaces # 接口代码
31 └── kits # 对外接口代码
32```
33
34## 约束<a name="section117mcpsimp"></a>
35
36本地 IO 接口
37
38- 目前仅支持 UTF-8/16 编码；
39- 目前 URI 暂不支持外部存储目录；
40
41## 说明<a name="section125mcpsimp"></a>
42
43### 接口说明<a name="section127mcpsimp"></a>
44
45当前分布式文件子系统开放本地文件目录访问接口，按照功能，其可划分为如下几种类型：
46
47**表 1** 接口类型表
48
49<a name="table99228171027"></a>
50<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>
51</th>
52<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>
53</th>
54<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>
55</th>
56<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>
57</th>
58</tr>
59</thead>
60<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>
61</td>
62<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>
63</td>
64<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>
65</td>
66<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>
67<p id="p184313310437"><a name="p184313310437"></a><a name="p184313310437"></a>chownSync</p>
68<p id="p1684318315436"><a name="p1684318315436"></a><a name="p1684318315436"></a>chmodSync</p>
69</td>
70</tr>
71<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>
72</td>
73<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>
74</td>
75<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>
76</td>
77<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>
78</td>
79</tr>
80<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>
81</td>
82<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>
83</td>
84<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>
85</td>
86<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>
87</td>
88</tr>
89<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>
90</td>
91<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>
92</td>
93<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>
94</td>
95<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>
96<p id="p88031126184311"><a name="p88031126184311"></a><a name="p88031126184311"></a>Stream.fdopenStreamSync</p>
97</td>
98</tr>
99<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>
100</td>
101<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>
102</td>
103<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>
104</td>
105<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>
106<p id="p202016525456"><a name="p202016525456"></a><a name="p202016525456"></a>copy</p>
107<p id="p8142558194520"><a name="p8142558194520"></a><a name="p8142558194520"></a>list</p>
108</td>
109</tr>
110</tbody>
111</table>
112
113其中，沙盒文件接口所使用的 URI 具体可划分为三种类型：
114
115**表 2** URI类型表
116
117<a name="table947391523311"></a>
118<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>
119</th>
120<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>
121</th>
122<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>
123</th>
124<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>
125</th>
126</tr>
127</thead>
128<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>
129</td>
130<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>
131</td>
132<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>
133</td>
134<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>
135</td>
136</tr>
137<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>
138</td>
139<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>
140</td>
141<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>
142</td>
143<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>
144</td>
145</tr>
146<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>
147</td>
148<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>
149</td>
150<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>
151</td>
152<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>
153</td>
154</tr>
155</tbody>
156</table>
157
158### 使用说明<a name="section149mcpsimp"></a>
159
160当前分布式文件子系统所提供的 IO 接口，按照编程模型，可划分为如下几种类型：
161
162- 同步编程模型
163
164 名称包含 Sync 的接口实现为同步模型。用户在调用这些接口的时候，将同步等待，直至执行完成，执行结果以函数返回值的形式返回。
165
166 下例以只读的方式打开一个文件流，接着试图读取其中前 4096 个字节并将之转换为 UTF-8 编码的字符串，最后关闭该文件流。
167
168 ```
169 import fileio from '@OHOS.distributedfile.fileio';
170
171 try {
172 var ss = fileio.Stream.createStreamSync("tmp", "r")
173 buf = new ArrayBuffer(4096)
174 ss.readSync(buf)
175 console.log(String.fromCharCode.apply(null, new Uint8Array(buf)))
176 ss.closeSync()
177 }
178 catch (e) {
179 console.log(e);
180 }
181 ```
182
183
184- 异步编程模型：Promise
185
186 @OHOS.distributedfile.fileio 模块中，名称不含 Sync 的接口，在不提供最后一个函数型参数 callback 的时候，即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务，同时返回一个 promise 对象，其代表异步操作的结果。在返回的结果的个数超过一个时，其以对象属性的形式返回。
187
188 下例通过 Promise 链依次完成：以只读方式打开文件流、尝试读取文件前 4096 个字节、显示读取内容的长度，最后关闭文件。
189
190 ```
191 import fileio from '@OHOS.distributedfile.fileio';
192
193 try {
194 let openedStream
195 fileio.Stream.createStream("test.txt", "r")
196 .then(function (ss) {
197 openedStream = ss;
198 return ss.read(new ArrayBuffer(4096))
199 })
200 .then(function (res) {
201 console.log(res.bytesRead);
202 console.log(String.fromCharCode.apply(null, new Uint8Array(res.buffer)))
203 return openedStream.close()
204 })
205 .then(function (undefined) {
206 console.log("Stream is closed")
207 })
208 .catch(function (e) {
209 console.log(e)
210 })
211 } catch (e) {
212 console.log(e)
213 }
214 ```
215
216
217- 异步编程模型：Callback
218
219 @OHOS.distributedfile.fileio 模块中，名字不含 Sync 的接口，在提供最后一个函数性参数 callback 的时候，即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候，接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。
220
221 下例异步创建文件流，并在文件流的回调函数中异步读取文件的前 4096 字节，接着在读取文件的回调函数中异步关闭文件。
222
223 ```
224 import fileio from '@OHOS.distributedfile.fileio';
225
226 try {
227 fileio.Stream.createStream("./testdir/test_stream.txt", "r", function (err, ss) {
228 if (!err) {
229 ss.read(new ArrayBuffer(4096), {}, function (err, buf, readLen) {
230 if (!err) {
231 console.log('readLen: ' + readLen)
232 console.log('data: ' + String.fromCharCode.apply(null, new Uint8Array(buf)))
233 } else {
234 console.log('Cannot read from the stream ' + err)
235 }
236 ss.close(function (err) {
237 console.log(`Stream is ${err ? 'not' : ''}closed`)
238 });
239 })
240 } else {
241 console.log('Cannot open the stream ' + err)
242 }
243 })
244 } catch (e) {
245 console.log(e)
246 }
247 ```
248
249
250- 异步编程模型：Legacy
251
252 @system.file 模块中的所有接口都实现为 Legacy 异步模型。用户在调用这些接口的时候，需要提供 success、fail 及 complete 三个回调。在正确提供参数的情况下，当异步任务完成后，接口会根据是否成功，分别调用 success 回调或 fail 回调，并最终调用 complete 回调。
253
254 下例异步判断 URI 所指向的文件是否存在，并相应提供三个回调用于打印判断结果。
255
256 ```
257 import file from '@system.file'
258
259 file.access({
260 uri: 'internal://app/test.txt',
261 success: function() {
262 console.log('call access success.');
263 },
264 fail: function(data, code) {
265 console.error('call fail callback fail, code: ' + code + ', data: ' + data);
266 },
267 complete: function () {
268 console.log('call access finally.');
269 }
270 });
271
272 console.log("file access tested done")
273 ```
274
275
276## 相关仓<a name="section178mcpsimp"></a>
277
278**分布式文件**
279
280distributeddatamgr_distributedfile
281
282
