Querying Assets (C/C++)

Available APIs

You can use OH_Asset_Query to query assets.

The following table describes the attributes for querying an asset.

NOTE

In the following table, the attributes ASSET_TAG_ALIAS and those containing ASSET_TAG_DATA_LABEL are custom asset attributes reserved for services. These attributes are not encrypted. Therefore, do not put sensitive personal data in these attributes. It takes a long time to query the plaintext of the asset attribute ASSET_TAG_SECRET due to the need of decryption. Therefore, Asset_ReturnType must be set to ASSET_RETURN_ALL. For other asset attributes, decryption is not required, so the query takes a short time. Therefore, Asset_ReturnType must be set to ASSET_RETURN_ATTRIBUTES.

Attribute Name (Asset_Tag)	Attribute Content (Asset_Value)	Mandatory	Description
ASSET_TAG_ALIAS	Type: uint8[] Length: 1-256 bytes	No	Asset alias, which uniquely identifies an asset.
ASSET_TAG_ACCESSIBILITY	Type: uint32_t Value range: see Asset_Accessibility.	No	Access control based on the lock screen status.
ASSET_TAG_REQUIRE_PASSWORD_SET	Type: bool	No	Whether the asset is accessible only when a lock screen password is set. The value true means the asset is accessible only when a lock screen password is set. The value false means that the asset can be accessed regardless of whether a lock screen password is set.
ASSET_TAG_AUTH_TYPE	Type: uint32_t Value range: see Asset_AuthType.	No	Type of user authentication required for accessing the asset.
ASSET_TAG_SYNC_TYPE	Type: uint32_t Value range: see Asset_SyncType.	No	Type of sync supported by the asset.
ASSET_TAG_IS_PERSISTENT	Type: bool	No	Whether to retain the asset when the application is uninstalled. The value true means to retain the asset even after the application is uninstalled. The value false means the opposite.
ASSET_TAG_DATA_LABEL_CRITICAL_1	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_CRITICAL_2	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_CRITICAL_3	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_CRITICAL_4	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service with integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_NORMAL_1	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_NORMAL_2	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_NORMAL_3	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_NORMAL_4	Type: uint8[] Length: 1-2048 bytes	No	Asset attribute information customized by the service without integrity protection. Note: The data length is 1 to 512 bytes before API version 12.
ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1¹²⁺	Type: uint8[] Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2¹²⁺	Type: uint8[] Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3¹²⁺	Type: uint8[] Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4¹²⁺	Type: uint8[] Length: 1-2048 bytes	No	Local attribute information about the asset. The value is assigned by the service without integrity protection and will not be synced.
ASSET_TAG_RETURN_TYPE	Type: uint32_t Value range: see Asset_ReturnType.	No	Type of the asset query result to return.
ASSET_TAG_RETURN_LIMIT	Type: uint32_t	No	Maximum number of asset records returned.
ASSET_TAG_RETURN_OFFSET	Type: uint32_t Value range: 1-65536	No	Offset of the asset query result. Note: This parameter specifies the starting asset record to return in batch asset query.
ASSET_TAG_RETURN_ORDERED_BY	Type: uint32_t Value: ASSET_TAG_DATA_LABEL_xxx	No	How the query results are sorted. Currently, the results can be sorted only by ASSET_TAG_DATA_LABEL. Note: By default, assets are returned in the order in which they are added.
ASSET_TAG_REQUIRE_ATTR_ENCRYPTED¹⁴⁺	Type: bool	No	Whether to query the encrypted data of service customized supplementary information. The value true means to query the encrypted data of service customized supplementary information; the value false means to query the non-encrypted data of service customized supplementary information. Default value: false.
ASSET_TAG_GROUP_ID¹⁸⁺	Type: Uint8[] Length: 7-127 bytes	No	Group to which the asset to be queried belongs. By default, this parameter is not specified.

Constraints

The assets queried are transmitted to the service through an IPC channel. Due to the limitation of the IPC buffer size, the maximum number of assets to be queried at a time cannot exceed 40.

Example

NOTE

Before querying an asset, ensure that the asset exists. For details about how to add an asset, see Adding an Asset. Otherwise, the NOT_FOUND error (24000002) is reported.

Querying the Plaintext of an Asset

Query the plaintext of asset demo_alias.

For details about how to query the plaintext of an asset in a group, see Querying the Plaintext of an Asset in a Group.

Link the dynamic libraries in the CMake script.

target_link_libraries(entry PUBLIC libasset_ndk.z.so)

Include header files.

#include "napi/native_api.h"
#include <string.h>
#include "asset/asset_api.h"

napi_init.cpp

Query an asset.

static napi_value QueryAssetPlaintext(napi_env env, napi_callback_info info)
{
    const char *aliasStr = "demo_alias";
    
    Asset_Blob alias = {(uint32_t)(strlen(aliasStr)), (uint8_t *)aliasStr};
    Asset_Attr attr[] = {
        {.tag = ASSET_TAG_ALIAS, .value.blob = alias}, // Specify the alias of the asset to query. At most one asset will meet the condition.
        {.tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ALL}, // Return all asset information, including the attributes and asset plaintext. The plaintext needs to be decrypted, so the query takes a long time.
    };

    Asset_ResultSet resultSet = {0};
    int32_t queryResult = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet);
    if (queryResult == ASSET_SUCCESS) {
        // Parse resultSet.
        for (uint32_t i = 0; i < resultSet.count; i++) {
            // Parse the secret attribute. The data corresponds to secret->blob.data, and the size corresponds to secret->blob.size.
            Asset_Attr *secret = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_SECRET);
        }
    }
    OH_Asset_FreeResultSet(&resultSet);
 
    napi_value ret;
    napi_create_int32(env, queryResult, &ret);
    return ret;
}

napi_init.cpp

Querying Attributes of an Asset

Query attributes of asset demo_alias.

For details about how to query the attributes of an asset in a group, see Querying the Attributes of an Asset in a Group.

Link the dynamic libraries in the CMake script.

target_link_libraries(entry PUBLIC libasset_ndk.z.so)

Include header files.

#include "napi/native_api.h"
#include <string.h>
#include "asset/asset_api.h"

napi_init.cpp

Query an asset.

static napi_value QueryAssetAttribute(napi_env env, napi_callback_info info)
{
    const char *aliasStr = "demo_alias";
    
    Asset_Blob alias = { (uint32_t)(strlen(aliasStr)), (uint8_t *)aliasStr };
    Asset_Attr attr[] = {
        {.tag = ASSET_TAG_ALIAS, .value.blob = alias}, // Specify the alias of the asset to query. At most one asset will meet the condition.
        {.tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ATTRIBUTES}, // Return only the asset attributes. The attributes do not need to be decrypted, so the query takes a short time.
    };

    Asset_ResultSet resultSet = {0};
    int32_t queryResult = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet);
    if (queryResult == ASSET_SUCCESS) {
        // Parse the result
        for (uint32_t i = 0; i < resultSet.count; i++) {
            // Parse the data label. The data corresponds to label->blob.data, and the size corresponds to label->blob.size.
            Asset_Attr *label = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_DATA_LABEL_NORMAL_1);
        }
    }
    OH_Asset_FreeResultSet(&resultSet);
 
    napi_value ret;
    napi_create_int32(env, queryResult, &ret);
    return ret;
}

napi_init.cpp

Querying Attributes of Assets in Batches

Query attributes of assets whose label is demo_label in batches. A total of 10 records that meet the conditions are returned. The results are sorted by the content of the ASSET_TAG_DATA_LABEL_NORMAL_1 attribute.

Link the dynamic libraries in the CMake script.

target_link_libraries(entry PUBLIC libasset_ndk.z.so)

Include header files.

#include "napi/native_api.h"
#include <string.h>
#include "asset/asset_api.h"

napi_init.cpp

Query an asset.

static napi_value QueryBatchAssetAttributes(napi_env env, napi_callback_info info)
{
    const char *labelStr = "demo_label";
    
    Asset_Blob label = {(uint32_t)(strlen(labelStr)), (uint8_t *)labelStr};
    Asset_Attr attr[] = {
        {.tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ATTRIBUTES},
        {.tag = ASSET_TAG_DATA_LABEL_NORMAL_1, .value.blob = label},
        {.tag = ASSET_TAG_RETURN_LIMIT, .value.u32 = 10},
        {.tag = ASSET_TAG_RETURN_ORDERED_BY, .value.u32 = ASSET_TAG_DATA_LABEL_NORMAL_1},
    };

    Asset_ResultSet resultSet = { 0 };
    int32_t queryResult = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet);
    if (queryResult == ASSET_SUCCESS) {
        // Parse the result
        for (uint32_t i = 0; i < resultSet.count; i++) {
            // Parse the data alias. The alias corresponds to label->blob.data, and the size corresponds to label->blob.size.
            Asset_Attr *alias = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_ALIAS);
        }
    }
    OH_Asset_FreeResultSet(&resultSet);
 
    napi_value ret;
    napi_create_int32(env, queryResult, &ret);
    return ret;
}

napi_init.cpp