1# FileUri 2 3 4## 概述 5 6文件统一资源标识符（File Uniform Resource Identifier）。 7 8支持fileuri与路径path的转换、有效性校验、以及指向的变换（指向的文件或路径）。 9 10该类主要用于uri格式验证和uri转换处理。且uri用于应用间文件分享场景，将应用沙箱路径按照固定关系转换为uri; 11 12调用者需保证所有接口入参的有效性，接口按照固定规则转换输出结果，并不检查其是否存在。 13 14**系统能力**：SystemCapability.FileManagement.AppFileService 15 16**起始版本**：12 17 18## 汇总 19 20### 文件 21 22| 名称 | 描述 | 23| -------- | -------- | 24| [oh_file_uri.h](oh__file__uri_8h.md) | 提供uri和路径path之间的相互转换，目录uri获取，以及uri的有效性校验的方法。 | 25 26### 函数 27 28| 接口名称 | 描述 | 29| -------- | -------- | 30| [FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode) [OH_FileUri_GetUriFromPath](#oh_fileuri_geturifrompath) (const char \*path, unsigned int length, char \*\*result) | 通过传入的路径path生成应用自己的uri；<br/>将path转uri时，路径中的中文及非数字字母的特殊字符将会被编译成对应的ASCII码，拼接在uri中。 | 31| [FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode) [OH_FileUri_GetPathFromUri](#oh_fileuri_getpathfromuri) (const char \*uri, unsigned int length, char \*\*result) | 将uri转换成对应的沙箱路径path。<br/>1、uri转path过程中会将uri中存在的ASCII码进行解码后拼接在原处，非系统接口生成的uri中可能存在ASCII码解析范围之外的字符， 导致字符串无法正常拼接；<br/>2、转换处理为系统约定的字符串替换规则（规则随系统演进可能会发生变化），转换过程中不进行路径校验操作，无法保证转换结果的一定可以访问。 | 32| [FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode) [OH_FileUri_GetFullDirectoryUri](#oh_fileuri_getfulldirectoryuri) (const char \*uri, unsigned int length, char \*\*result) | 获取所在路径uri。uri指向文件则返回所在路径的uri，uri指向目录则不处理直接返回原串；<br/>uri指向的文件不存在或属性获取失败则返回空串。 | 33| bool [OH_FileUri_IsValidUri](#oh_fileuri_isvaliduri) (const char \*uri, unsigned int length) | 判断传入的uri的格式是否正确。仅校验uri是否满足系统定义的格式规范，不校验uri的有效性。 | 34| [FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode) [OH_FileUri_GetFileName](#oh_fileuri_getfilename) (const char \*uri, unsigned int length, char \*\*result) | 通过传入的uri获取到对应的文件名称。（如果文件名中存在ASCII码将会被解码处理后拼接在原处）。 | 35 36## 函数说明 37 38### OH_FileUri_GetFileName() 39 40``` 41FileManagement_ErrCode OH_FileUri_GetFileName(const char *uri, unsigned int length, char **result) 42``` 43**描述** 44通过传入的uri获取到对应的文件名称。（如果文件名中存在ASCII码将会被解码处理后拼接在原处）。 45 46**系统能力**：SystemCapability.FileManagement.AppFileService 47 48**起始版本**：13 49 50**参数:** 51 52| 名称 | 描述 | 53| -------- | -------- | 54| uri | 传入的uri。 | 55| length | 表示传入uri的字节长度。 | 56| result | 表示转换后的名称。需要使用standard library标准库的free()方法释放申请的资源。 | 57 58**返回：** 59 60返回特定的错误码值，详细信息可以查看[FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode)。 61**ERR_PARAMS** 401 - 输入参数无效。可能的原因： 621.参数uri为空指针； 632.参数result为空指针； 643.输入的uri长度与length不一致； 654.uri格式不正确。 66 67**ERR_ENOMEM** 13900011 - 分配或者拷贝内存失败。 68**ERR_OK** 0 - 接口调用成功。 69 70### OH_FileUri_GetFullDirectoryUri() 71 72``` 73FileManagement_ErrCode OH_FileUri_GetFullDirectoryUri(const char *uri, unsigned int length, char **result) 74``` 75**描述** 76获取所在路径uri。uri指向文件则返回所在路径的uri，uri指向目录则不处理直接返回原串； 77 78uri指向的文件不存在或属性获取失败则返回空串。 79 80**系统能力**：SystemCapability.FileManagement.AppFileService 81 82**起始版本**：12 83 84**参数:** 85 86| 名称 | 描述 | 87| -------- | -------- | 88| uri | 表示要获取目录的uri的原始uri。 | 89| length | 表示原始uri的字节长度。 | 90| result | 表示获取到的目录uri，需要使用standard library标准库的free()方法释放申请的资源。 | 91 92**返回：** 93 94返回特定的错误码值，详细信息可以查看[FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode)。 95**ERR_PARAMS** 401 - 输入参数无效。可能的原因： 961.参数uri为空指针； 972.参数result为空指针； 983.输入的uri长度与length不一致。 99 100**ERR_ENOMEM** 13900011 - 分配或者拷贝内存失败。 101**ERR_ENOENT** 13900002 - 没有该文件或目录。 102**ERR_UNKNOWN** 13900042 - 未知错误。获取到的目录uri长度为0会返回此错误。 103**ERR_OK** 0 - 接口调用成功。 104 105### OH_FileUri_GetPathFromUri() 106 107``` 108FileManagement_ErrCode OH_FileUri_GetPathFromUri(const char *uri, unsigned int length, char **result) 109``` 110**描述** 111将uri转换成对应的沙箱路径path。 112 1131、uri转path过程中会将uri中存在的ASCII码进行解码后拼接在原处，非系统接口生成的uri中可能存在ASCII码解析范围之外的字符， 导致字符串无法正常拼接； 1142、转换处理为系统约定的字符串替换规则（规则随系统演进可能会发生变化），转换过程中不进行路径校验操作，无法保证转换结果的一定可以访问。 115 116**系统能力**：SystemCapability.FileManagement.AppFileService 117 118**起始版本**：12 119 120**参数:** 121 122| 名称 | 描述 | 123| -------- | -------- | 124| uri | 表示要转换的uri。 | 125| length | 表示要转换uri的字节长度。 | 126| result | 表示转换后的路径path。需要使用standard library标准库的free()方法释放申请的资源。 | 127 128**返回：** 129 130返回特定的错误码值，详细信息可以查看[FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode)。 131**ERR_PARAMS** 401 - 输入参数无效。可能的原因： 1321.参数uri为空指针； 1332.参数result为空指针； 1343.输入的uri长度与length不一致。 135 136**ERR_UNKNOWN** 13900042 - 未知错误。转换后的路径path长度为0会返回此错误。 137**ERR_ENOMEM** 13900011 - 分配或者拷贝内存失败。 138**ERR_OK** 0 - 接口调用成功。 139 140### OH_FileUri_GetUriFromPath() 141 142``` 143FileManagement_ErrCode OH_FileUri_GetUriFromPath(const char *path, unsigned int length, char **result) 144``` 145**描述** 146通过传入的路径path生成应用自己的uri； 147 148将path转uri时，路径中的中文及非数字字母的特殊字符将会被编译成对应的ASCII码，拼接在uri中。 149 150**系统能力**：SystemCapability.FileManagement.AppFileService 151 152**起始版本**：12 153 154**参数:** 155 156| 名称 | 描述 | 157| -------- | -------- | 158| path | 表示要转换的路径。 | 159| length | 表示要转换路径的字节长度。 | 160| result | 表示转换后的uri, 需要使用standard library标准库的free()方法释放申请的资源。 | 161 162**返回：** 163 164返回特定的错误码值，详细信息可以查看[FileManagement_ErrCode](_file_i_o.md#filemanagement_errcode)。 165**ERR_PARAMS** 401 - 输入参数无效。可能的原因： 1661.参数path为空指针； 1672.参数result为空指针； 1683.输入的path长度与length不一致。 169 170**ERR_UNKNOWN** 13900042 - 未知错误。转换后的uri长度为0会返回此错误。 171**ERR_ENOMEM** 13900011 - 分配或者拷贝内存失败。 172**ERR_OK** 0 - 接口调用成功。 173 174### OH_FileUri_IsValidUri() 175 176``` 177bool OH_FileUri_IsValidUri(const char *uri, unsigned int length) 178``` 179**描述** 180判断传入的uri的格式是否正确。仅校验uri是否满足系统定义的格式规范，不校验uri的有效性。 181 182**系统能力**：SystemCapability.FileManagement.AppFileService 183 184**起始版本**：12 185 186**参数:** 187 188| 名称 | 描述 | 189| -------- | -------- | 190| uri | 表示需要校验的uri。 | 191| length | 需要校验uri的字节长度。 | 192 193**返回：** 194 195返回 true: 传入uri是有效的uri；false: 传入的uri是无效的uri。 196