FileUri开发指导(C/C++)

场景介绍

FileUri提供了关于文件URI的基本操作，将URI转换成对应的沙箱路径、将应用沙箱路径转换成对应应用自己的URI、获取URI所在目录路径的URI等接口能力，方便应用对文件分享业务中URI的访问。

基本概念

结果集：满足使用场景的路径或URI。

约束限制

URI转路径时，URI来源建议使用系统能力获取，例如：picker、剪切板、拖拽、及系统提供的路径转URI接口等系统能力返回的URI；如果转换应用或用户拼接的URI，则转换后的路径可能无法访问。
为保证数据的准确性，在转换或判断过程中应保持单对象处理，避免资源竞争导致数据异常。

接口说明

接口的详细说明，请参考oh_file_uri.h。

接口名称	描述
FileManagement_ErrCode OH_FileUri_GetUriFromPath(const char path, unsigned int length, char *result)	通过传入的path生成应用自己的URI。将path转URI时，path中的中文及非数字字母的特殊字符会被编码为对应的ASCII码，并拼接在URI中。
FileManagement_ErrCode OH_FileUri_GetPathFromUri(const char uri, unsigned int length, char *result)	将uri转换成对应的沙箱路径。 1. uri转路径过程中会将uri中存在的ASCII码进行解码后拼接在原处，非系统接口生成的uri中可能存在ASCII码解析范围之外的字符，导致字符串无法正常拼接。 2. 转换处理遵循系统约定的字符串替换规则（规则可能随系统演进而变化），转换过程中不进行路径校验操作，无法保证转换结果的可访问性。
FileManagement_ErrCode OH_FileUri_GetFullDirectoryUri(const char uri, unsigned int length, char *result)	获取所在路径uri。 1. uri指向文件则返回所在路径的uri。 2. uri指向目录则不处理直接返回原串。 3. uri指向的文件不存在或属性获取失败则返回空串。
bool OH_FileUri_IsValidUri(const char *uri, unsigned int length)	判断传入的uri的格式是否正确。仅校验uri是否满足系统定义的格式规范，不校验uri的有效性。
FileManagement_ErrCode OH_FileUri_GetFileName(const char uri, unsigned int length, char *result)	通过传入的uri获取到对应的文件名称（如果文件名中存在ASCII码将会被解码处理后拼接在原处）。

开发步骤

在CMake脚本中链接动态库

CMakeLists.txt中添加以下lib。

target_link_libraries(sample PUBLIC libohfileuri.so)

添加头文件

#include <filemanagement/file_uri/oh_file_uri.h>

调用OH_FileUri_GetUriFromPath接口，在接口中malloc的内存需要在使用完后释放，因此需要free对应的内存，避免内存泄漏。示例代码如下所示：

static napi_value NAPI_Global_OH_FileUri_GetUriFromPathExample(napi_env env, napi_callback_info info)
{
    // ...
    // 为 char* uri 分配内存
    char *path = new char[strLength + 1]; // +1 for null terminator
    // 将 JavaScript 字符串复制到 uri
    // ...
    unsigned int length = strlen(path);
    // 输出传入路径字符串
    // ...
    char *uriResult = nullptr;
    FileManagement_ErrCode ret = OH_FileUri_GetUriFromPath(path, length, &uriResult);
    // 输出结果uri字符串
    // ...
    if (ret == 0 && uriResult != nullptr) {
        // 将C字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, uriResult, NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            free(uriResult);
            return nullptr;
        }
        free(uriResult); // 释放临时字符串
    } else {
        // 将C字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, "Hello World", NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            return nullptr;
        }
    }
    return result;
}

调用OH_FileUri_GetPathFromUri通过URI转成对应的路径，在接口中malloc的内存需要在使用完后释放，因此需要free对应的内存，避免内存泄漏。示例代码如下所示。

static napi_value NAPI_Global_OH_FileUri_GetPathFromUriExample(napi_env env, napi_callback_info info)
{
    // ...
    char *uri = new char[strLength + 1]; // +1 for null terminator
    // 将 JavaScript 字符串复制到 uri
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // 输出传入uri字符串
    OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.WatcherType=OnTrigger: %{public}s", uri);
    char *pathResult = nullptr;
    FileManagement_ErrCode ret = OH_FileUri_GetPathFromUri(uri, length, &pathResult);
    // 输出获取路径结果字符串
    // ...
    if (ret == 0 && pathResult != nullptr) {
        // 将C字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, pathResult, NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            free(pathResult);
            return nullptr;
        }
        free(pathResult); // 释放临时字符串
    } else {
        // 将空字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, "", NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            return nullptr;
        }
    }
    return result;
}

调用OH_FileUri_GetFullDirectoryUri获取URI所在路径的URI，在接口中malloc的内存需要在使用完后释放，因此需要free对应的内存，避免内存泄漏。示例代码如下所示。

static napi_value NAPI_Global_OH_FileUri_GetFullDirectoryUriExample(napi_env env, napi_callback_info info)
{
    // ...
    char *uri = new char[strLength + 1]; // +1 for null terminator
    // 将 JavaScript 字符串复制到 uri
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // 输出传入uri字符串
    OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.WatcherType=OnTrigger: %{public}s", uri);
    char *uriResult = nullptr;
    FileManagement_ErrCode ret = OH_FileUri_GetFullDirectoryUri(uri, length, &uriResult);
    // 输出所在路径uri字符串
    // ...
    if (ret == 0 && uriResult != nullptr) {
        // 使用napi接口创建一个字符串类型的napi_value来返回正确结果
        napi_create_string_utf8(env, uriResult, NAPI_AUTO_LENGTH, &result);
    } else {
        // 使用napi接口创建一个表示null值的napi_value来返回错误或空值情况
        napi_get_null(env, &result);
    }
    if (uriResult != nullptr) {
        free(uriResult);
    }
    return result;
}

可以调用OH_FileUri_IsValidUri接口进行URI格式验证。示例代码如下所示。

static napi_value NAPI_Global_OH_FileUri_IsValidUriExample(napi_env env, napi_callback_info info)
{
    // ...
    char *uri = new char[strLength + 1]; // +1 for null terminator
    // 将 JavaScript 字符串复制到 uri
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);
    unsigned int length = strlen(uri);
    // 输出传入uri字符串
    OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.WatcherType=OnTrigger: %{public}s", uri);
    bool flags = OH_FileUri_IsValidUri(uri, length);
    // ...
}

调用OH_FileUri_GetFileName获取URI中的文件名称，在接口中malloc的内存需要在使用完后释放，因此需要free对应的内存，避免内存泄漏。示例代码如下所示。

static napi_value NAPI_Global_OH_FileUri_GetFileNameExample(napi_env env, napi_callback_info info)
{
    // ...
    char *uri = new char[strLength + 1]; // +1 for null terminator
    // 将 JavaScript 字符串复制到 uri
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // 输出传入uri字符串
    OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.WatcherType=OnTrigger: %{public}s", uri);
    char *uriResult = nullptr;
    FileManagement_ErrCode ret = OH_FileUri_GetFileName(uri, length, &uriResult);
    // 输出获取到的文件名称
    // ...
    if (ret == 0 && uriResult != nullptr) {
        // 将C字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, uriResult, NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            free(uriResult);
            return NULL;
        }
        free(uriResult); // 释放临时字符串
    } else {
        // 将空字符串转换为napi_value
        napi_status status = napi_create_string_utf8(env, "", NAPI_AUTO_LENGTH, &result);
        if (status != napi_ok) {
            return nullptr;
        }
    }
    return result;
}

场景介绍​

基本概念​

约束限制​

接口说明​

开发步骤​

场景介绍

基本概念

约束限制

接口说明

开发步骤