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操作能力,其具体包括用于管理文件的基本文件接口,管理目录的基本目录接口,获取文件信息的统计接口,流式读写文件的流式接口,以及文件锁接口。 17 18### 系统架构<a name="section110mcpsimp"></a> 19 20文件访问接口仅面向应用程序提供应用文件访问能力,其由ohos.file.fs模块、ohos.file.statvfs模块、ohos.file.hash模块、ohos.file.securityLabel模块和ohos.file.environment模块组成。架构上,文件访问接口实现了自研的 LibN,其抽象了 NAPI 层接口,向文件访问接口提供包括基本类型系统、内存管理、通用编程模型在内的基本能力。 21 22**图 1** 文件访问接口架构图<a name="fig174088216114"></a> 23 24 25## 目录<a name="section113mcpsimp"></a> 26 27``` 28foundation/filemanagement/file_api 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.file.fs</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>access</p> 71<p id="p1684318315436"><a name="p1684318315436"></a><a name="p1684318315436"></a>openSync</p> 72<p id="p0390135216324"><a name="p0390135216324"></a><a name="p0390135216324"></a>open</p> 73<p id="p202016525456"><a name="p202016525456"></a><a name="p202016525456"></a>moveFileSync</p> 74<p id="p8142558194520"><a name="p8142558194520"></a><a name="p8142558194520"></a>moveFile</p> 75</td> 76</tr> 77<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> 78</td> 79<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> 80</td> 81<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.file.fs</p> 82</td> 83<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>listFileSync</p> 84<p id="p29333177216"><a name="p29333177216"></a><a name="p29333177216"></a>listFile</p> 85</td> 86</tr> 87<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>获取文件信息接口</p> 88</td> 89<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> 90</td> 91<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.file.fs</p> 92</td> 93<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>statSync</p> 94<p id="p57231317420"><a name="p57231317420"></a><a name="p57231317420"></a>stat</p> 95</td> 96</tr> 97<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> 98</td> 99<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> 100</td> 101<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.file.fs</p> 102</td> 103<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>createStreamSync</p> 104<p id="p88031126184311"><a name="p88031126184311"></a><a name="p88031126184311"></a>createStream</p> 105<p id="p14923141711215"><a name="p14923141711215"></a><a name="p14923141711215"></a>fdopenStreamSync</p> 106<p id="p84031126184311"><a name="p84031126184311"></a><a name="p84031126184311"></a>fdopenStream</p> 107</td> 108</tr> 109<tr id="row92319171228"><td class="cellrowborder" valign="top" width="15.02%" headers="mcps1.2.5.1.1 "><p id="p1592418171526"><a name="p1592418171526"></a><a name="p1592418171526"></a>文件锁接口</p> 110</td> 111<td class="cellrowborder" valign="top" width="32.25%" headers="mcps1.2.5.1.2 "><p id="p992411171421"><a name="p992411171421"></a><a name="p992411171421"></a>提供文件阻塞式、非阻塞式施加共享锁或独占锁,及解锁的能力</p> 112</td> 113<td class="cellrowborder" valign="top" width="25.840000000000003%" headers="mcps1.2.5.1.3 "><p id="p1692421716217"><a name="p1692421716217"></a><a name="p1692421716217"></a>@ohos.file.fs</p> 114</td> 115<td class="cellrowborder" valign="top" width="26.889999999999997%" headers="mcps1.2.5.1.4 "><p id="p10924141711215"><a name="p10924141711215"></a><a name="p10924141711215"></a>lock</p> 116<p id="p88031226184311"><a name="p88031226184311"></a><a name="p88031226184311"></a>tryLock</p> 117<p id="p88031326184311"><a name="p88031326184311"></a><a name="p88031326184311"></a>unlock</p> 118</td> 119</tr> 120</tbody> 121</table> 122 123open接口可以指定mode参数以打开相应功能权限,说明如下: 124 125**表 2** OpenMode类型表 126 127| 名称 | 类型 | 值 | 说明 | 128| ---- | ------ |---- | ------- | 129| READ_ONLY | number | 0o0 | 只读打开。 | 130| WRITE_ONLY | number | 0o1 | 只写打开。 | 131| READ_WRITE | number | 0o2 | 读写打开。 | 132| CREATE | number | 0o100 | 若文件不存在,则创建文件。 | 133| TRUNC | number | 0o1000 | 如果文件存在且以只写或读写的方式打开文件,则将其长度裁剪为零。 | 134| APPEND | number | 0o2000 | 以追加方式打开,后续写将追加到文件末尾。 | 135| NONBLOCK | number | 0o4000 | 如果path指向FIFO、块特殊文件或字符特殊文件,则本次打开及后续 IO 进行非阻塞操作。 | 136| DIR | number | 0o200000 | 如果path不指向目录,则出错。 | 137| NOFOLLOW | number | 0o400000 | 如果path指向符号链接,则出错。 | 138| SYNC | number | 0o4010000 | 以同步IO的方式打开文件。 | 139 140文件过滤配置项类型,支持listFile接口使用,说明如下: 141 142**表 3** Filter 143 144| 名称 | 类型 | 说明 | 145| ----------- | --------------- | ------------------ | 146| suffix | Array<string> | 文件后缀名完全匹配,各个关键词OR关系。 | 147| displayName | Array<string> | 文件名模糊匹配,各个关键词OR关系。 | 148| mimeType | Array<string> | mime类型完全匹配,各个关键词OR关系。 | 149| fileSizeOver | number | 文件大小匹配,大于等于指定大小的文件。 | 150| lastModifiedAfter | number | 文件最近修改时间匹配,在指定时间点及之后的文件。 | 151| excludeMedia | boolean | 是否排除Media中已有的文件。 | 152 153### 使用说明<a name="section149mcpsimp"></a> 154 155当前文件访问接口所提供的 IO 接口,按照编程模型,可划分为如下几种类型: 156 157- 同步编程模型 158 159 名称包含 Sync 的接口实现为同步模型。用户在调用这些接口的时候,将同步等待,直至执行完成,执行结果以函数返回值的形式返回。 160 161 下例以只读的方式打开一个文件,接着试图读取其中前 4096 个字节,最后关闭该文件。 162 163 ``` 164 import fs from '@ohos.file.fs'; 165 166 try { 167 let file = fs.openSync("test.txt", fs.OpenMode.READ_ONLY); 168 let readlen = fs.readSync(file.fd, new ArrayBuffer(4096)); 169 fs.closeSync(file); 170 } catch (e) { 171 console.log(e); 172 } 173 ``` 174 175 176- 异步编程模型:Promise 177 178 @ohos.file.fs 模块中,名称不含 Sync 的接口,在不提供最后一个函数型参数 callback 的时候,即实现为 Promsie 异步模型。Promise 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候,接口实现将异步执行任务,同时返回一个 promise 对象,其代表异步操作的结果。在返回的结果的个数超过一个时,其以对象属性的形式返回。 179 180 下例通过 Promise 链依次完成:以只读方式打开文件,尝试读取文件前 4096 个字节,最后关闭文件。 181 182 ``` 183 import fs from '@ohos.file.fs'; 184 185 try { 186 let file = await fs.open("test.txt", fs.OpenMode.READ_ONLY); 187 fs.read(file.fd, new ArrayBuffer(4096)) 188 .then((readLen) => { 189 fs.closeSync(file); 190 }); 191 } catch (e) { 192 console.log(e); 193 } 194 ``` 195 196 197- 异步编程模型:Callback 198 199 @ohos.file.fs 模块中,名字不含 Sync 的接口,在提供最后一个函数性参数 callback 的时候,即实现为 Callback 异步模型。Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候,接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型,分别表示执行出错与正常。 200 201 下例以只读方式打开文件,并在文件的回调函数中异步读取文件的前 4096 字节,最后关闭文件。 202 203 ``` 204 import fs from '@ohos.file.fs'; 205 206 try { 207 fs.open("test.txt", fs.OpenMode.READ_ONLY, (err, file) => { 208 if(err) { 209 console.log('file is not open'); 210 } 211 fs.read(file.fd, new ArrayBuffer(4096)) 212 .then((readLen) => { 213 fs.closeSync(file); 214 }); 215 }); 216 } catch (e) { 217 console.log(e); 218 } 219 ``` 220 221 222## 相关仓<a name="section178mcpsimp"></a> 223 224- [**文件访问接口**](https://gitee.com/openharmony/filemanagement_file_api) 225- [分布式文件服务](https://gitee.com/openharmony/filemanagement_dfs_service) 226- [公共文件访问框架](https://gitee.com/openharmony/filemanagement_user_file_service) 227- [存储管理服务](https://gitee.com/openharmony/filemanagement_storage_service) 228- [应用文件服务](https://gitee.com/openharmony/filemanagement_app_file_service) 229 230