1# File Api<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 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.
17
18### Architecture<a name="section110mcpsimp"></a>
19
20Currently, 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.
21
22**Figure  1**  File Api architecture<a name="fig174088216114"></a>
23![](figures/file-api-architecture.png "file-api-architecture.png")
24
25## Directory<a name="section113mcpsimp"></a>
26
27```
28foundation/filemanagement/file_api
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 File Api 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.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.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.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.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 File Api 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.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-   Asynchronous programming model: Promise
188
189    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.
190
191    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:
192
193    ```
194    import fileio from '@ohos.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-   Asynchronous programming model: Callback
221
222    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.
223
224    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:
225
226    ```
227    import fileio from '@ohos.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## Repositories Involved<a name="section178mcpsimp"></a>
254
255- [**File Api**](https://gitee.com/openharmony/filemanagement_file_api)
256- [filemanagement_dfs_service](https://gitee.com/openharmony/filemanagement_dfs_service)
257- [filemanagement_user_file_service](https://gitee.com/openharmony/filemanagement_user_file_service)
258- [filemanagement_storage_service](https://gitee.com/openharmony/filemanagement_storage_service)
259- [filemanagement_app_file_service](https://gitee.com/openharmony/filemanagement_app_file_service)
260
261