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