目录

FileUri Development (C/C++)

When to Use

FileUri provides APIs for basic file URI operations, such as converting URIs to sandbox paths, converting sandbox paths to URIs, and obtaining URIs of directories where the specified URIs are located, facilitating URI access in file sharing services.

Basic Concepts

Result set: path or URI that meets the service requirements.

Constraints

Available APIs

For detailed API descriptions, see oh_file_uri.h.

API Description
FileManagement_ErrCode OH_FileUri_GetUriFromPath(const char *path, unsigned int length, char **result) Converts the input path to the URI of the application. In this process, Chinese characters and non-digit characters in the path will be encoded to their corresponding ASCII codes and concatenated to the URI.
FileManagement_ErrCode OH_FileUri_GetPathFromUri(const char *uri, unsigned int length, char **result)

Converts the URI to the corresponding sandbox path.

1. During URI-to-path conversion, the ASCII code in the URI is decoded and then concatenated to the original position. The URI generated by a non-system API may contain characters beyond the ASCII code parsing range. As a result, the string cannot be concatenated.

2. The conversion is performed based on the string replacement rule specified by the system (the rule may change with the system evolution). During the conversion, the path is not verified, so that the conversion result may not be accessible.
FileManagement_ErrCode OH_FileUri_GetFullDirectoryUri(const char *uri, unsigned int length, char **result)

Obtains the URI of the path.

1. If the URI points to a file, the URI of the path is returned.

2. If the URI points to a directory, the original string is returned without processing.

3. If the file specified by the URI does not exist or the property fails to be obtained, an empty string is returned.
bool OH_FileUri_IsValidUri(const char *uri, unsigned int length) Checks whether the format of the input URI is correct. The system only checks whether the URI meets the format specifications defined by the system. The validity of the URI is not verified.
FileManagement_ErrCode OH_FileUri_GetFileName(const char *uri, unsigned int length, char **result) Obtains the file name based on the input URI. (If the file name contains ASCII codes, the ASCII codes will be decoded and concatenated to the original position.)

How to Develop

Linking the Dynamic Library in the CMake Script

Add the following library to CMakeLists.txt.

target_link_libraries(sample PUBLIC libohfileuri.so)

Adding the Header File

#include <filemanagement/file_uri/oh_file_uri.h>

  1. Call OH_FileUri_GetUriFromPath. The memory malloc'd in the API must be freed after use to avoid memory leaks. The sample code is as follows:

    static napi_value NAPI_Global_OH_FileUri_GetUriFromPathExample(napi_env env, napi_callback_info info)
{
    // ...
    // Allocate memory for the char* uri.
    char *path = new char[strLength + 1]; // +1 for null terminator
    // Copy the JavaScript string to uri.
    // ...
    unsigned int length = strlen(path);
    // Output the input path string.
    // ...
    char *uriResult = nullptr;
    FileManagement_ErrCode ret = OH_FileUri_GetUriFromPath(path, length, &uriResult);
    delete[] path;
    // Output the result URI string.
    // ...
    // After creating the return value, release the memory allocated by the API, including on error paths.
    const char *value = (ret == 0 && uriResult != nullptr) ? uriResult : "Hello World";
    napi_status status = napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &result);
    free(uriResult);
    if (status != napi_ok) {
        return nullptr;
    }
    return result;
}

  2. Call OH_FileUri_GetPathFromUri to convert a URI to the corresponding path. The memory malloc'd in the API must be freed after use to avoid memory leaks. The sample code is as follows:

    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
    // Copy the JavaScript string to uri.
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // Output the incoming URI string.
    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);
    delete[] uri;
    // Output the path result string.
    // ...
    // After creating the return value, release the memory allocated by the API, including on error paths.
    const char *value = (ret == 0 && pathResult != nullptr) ? pathResult : "";
    napi_status status = napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &result);
    free(pathResult);
    if (status != napi_ok) {
        return nullptr;
    }
    return result;
}

  3. Call OH_FileUri_GetFullDirectoryUri to obtain the URI of the directory where the URI resides. The memory malloc'd in the API must be freed after use to avoid memory leaks. The sample code is as follows:

    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
    // Copy the JavaScript string to uri.
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // Output the input URI string.
    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);
    delete[] uri;
    // Output the URI string of the path.
    // ...
    if (ret == 0 && uriResult != nullptr) {
        // Use NAPIs to create a napi_value of the string type to return the correct result.
        napi_create_string_utf8(env, uriResult, NAPI_AUTO_LENGTH, &result);
    } else {
        // Use NAPIs to create a napi_value of the null type to return the error or null value.
        napi_get_null(env, &result);
    }
    if (uriResult != nullptr) {
        free(uriResult);
    }
    return result;
}

  4. Call OH_FileUri_IsValidUri to check whether a URI is valid. The sample code is as follows:

    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
    // Copy the JavaScript string to uri.
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);
    unsigned int length = strlen(uri);
    // Output the input URI string.
    OH_LOG_INFO(LogType::LOG_APP, "HiAppEvent eventInfo.WatcherType=OnTrigger: %{public}s", uri);
    bool flags = OH_FileUri_IsValidUri(uri, length);
    delete[] uri;
    // ...
}

  5. Call OH_FileUri_GetFileName to obtain the file name from the URI. The memory malloc'd in the API must be freed after use to avoid memory leaks. The sample code is as follows:

    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
    // Copy the JavaScript string to uri.
    napi_get_value_string_utf8(env, args[0], uri, strLength + 1, &strLength);

    unsigned int length = strlen(uri);
    // Output the input URI string.
    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);
    delete[] uri;
    // Output the obtained file name.
    // ...
    // Release the memory allocated by the API after creating the return value, including on error paths.
    const char *value = (ret == 0 && uriResult != nullptr) ? uriResult : "";
    napi_status status = napi_create_string_utf8(env, value, NAPI_AUTO_LENGTH, &result);
    free(uriResult);
    if (status != napi_ok) {
        return nullptr;
    }
    return result;
}