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
