1# Querying Assets (C/C++) 2 3## Available APIs 4 5You can use [OH_Asset_Query](../../reference/apis-asset-store-kit/capi-asset-api-h.md#oh_asset_query) to query asset 6information. 7 8The following table describes the attributes for querying an asset. 9 10>**NOTE** 11> 12>In the following table, the attributes starting with **ASSET_TAG_DATA_LABEL** are custom asset attributes reserved. These attributes are not encrypted. Therefore, do not put personal data in these attributes. 13 14| Attribute Name (Asset_Tag) | Attribute Content (Asset_Value) | Mandatory| Description | 15| ------------------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | 16| ASSET_TAG_ALIAS | Type: uint8[]<br>Length: 1-256 bytes | No | Asset alias, which uniquely identifies an asset. | 17| ASSET_TAG_ACCESSIBILITY | Type: uint32_t<br>Value range: see [Asset_Accessibility](../../reference/apis-asset-store-kit/capi-asset-type-h.md#asset_accessibility).| No | Access control based on the lock screen status. | 18| 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. | 19| ASSET_TAG_AUTH_TYPE | Type: uint32_t<br>Value range: see [Asset_AuthType](../../reference/apis-asset-store-kit/capi-asset-type-h.md#asset_authtype).| No | Type of user authentication required for accessing the asset. | 20| ASSET_TAG_SYNC_TYPE | Type: uint32_t<br>Value range: see [Asset_SyncType](../../reference/apis-asset-store-kit/capi-asset-type-h.md#asset_synctype).| No | Type of sync supported by the asset. | 21| 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. | 22| ASSET_TAG_DATA_LABEL_CRITICAL_1 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 23| ASSET_TAG_DATA_LABEL_CRITICAL_2 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 24| ASSET_TAG_DATA_LABEL_CRITICAL_3 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 25| ASSET_TAG_DATA_LABEL_CRITICAL_4 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service with integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 26| ASSET_TAG_DATA_LABEL_NORMAL_1 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 27| ASSET_TAG_DATA_LABEL_NORMAL_2 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 28| ASSET_TAG_DATA_LABEL_NORMAL_3 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 29| ASSET_TAG_DATA_LABEL_NORMAL_4 | Type: uint8[]<br>Length: 1-2048 bytes | No | Asset attribute information customized by the service without integrity protection.<br>**NOTE**: The data length is 1 to 512 bytes before API version 12.| 30| ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_1<sup>12+</sup> | Type: uint8[]<br>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.| 31| ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_2<sup>12+</sup> | Type: uint8[]<br>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.| 32| ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_3<sup>12+</sup> | Type: uint8[]<br>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.| 33| ASSET_TAG_DATA_LABEL_NORMAL_LOCAL_4<sup>12+</sup> | Type: uint8[]<br>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.| 34| ASSET_TAG_RETURN_TYPE | Type: uint32_t<br>Value range: see [Asset_ReturnType](../../reference/apis-asset-store-kit/capi-asset-type-h.md#asset_returntype).| No | Type of the asset query result to return. | 35| ASSET_TAG_RETURN_LIMIT | Type: uint32_t | No | Maximum number of asset records returned. | 36| ASSET_TAG_RETURN_OFFSET | Type: uint32_t<br>Value range: 1-65536 | No | Offset of the asset query result.<br>**NOTE**: This parameter specifies the starting asset record to return in batch asset query. | 37| ASSET_TAG_RETURN_ORDERED_BY | Type: uint32_t<br>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**.<br>**NOTE**: By default, assets are returned in the order in which they are added.| 38| ASSET_TAG_REQUIRE_ATTR_ENCRYPTED<sup>14+</sup> | 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**.| 39| ASSET_TAG_GROUP_ID<sup>18+</sup> | Type: Uint8[]<br>Length: 7-127 bytes| No| Group to which the asset to be queried belongs. By default, this parameter is not specified.| 40 41## Constraints 42 43The 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. 44 45## Example 46 47### Querying the Plaintext of an Asset 48 49Query the plaintext of asset **demo_alias**. 50 51For details about how to query the plaintext of an asset in a group, see [Querying the Plaintext of an Asset in a Group](asset-native-group-access-control.md#querying-the-plaintext-of-an-asset-in-a-group). 52 531. Link the dynamic libraries in the CMake script. 54 ```txt 55 target_link_libraries(entry PUBLIC libasset_ndk.z.so) 56 ``` 57 582. Query an asset. 59 ```c 60 #include <string.h> 61 62 #include "asset/asset_api.h" 63 64 void QueryAsset() { 65 static const char *ALIAS = "demo_alias"; 66 Asset_Blob alias = { (uint32_t)(strlen(ALIAS)), (uint8_t *)ALIAS }; 67 Asset_Attr attr[] = { 68 { .tag = ASSET_TAG_ALIAS, .value.blob = alias }, // Specify the alias of the asset to query. 69 { .tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ALL }, // Return all asset information, including the attributes and asset plaintext. 70 }; 71 72 Asset_ResultSet resultSet = {0}; 73 int32_t ret = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet); 74 if (ret == ASSET_SUCCESS) { 75 // Parse the resultSet. 76 for (uint32_t i = 0; i < resultSet.count; i++) { 77 // Parse the secret: the data is secret->blob.data, the size is secret->blob.size. 78 Asset_Attr *secret = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_SECRET); 79 } 80 } 81 OH_Asset_FreeResultSet(&resultSet); 82 } 83 ``` 84 85### Querying Attributes of an Asset 86 87Query attributes of asset **demo_alias**. 88 89For details about how to query the attributes of an asset in a group, see [Querying the Attributes of an Asset in a Group](asset-native-group-access-control.md#querying-the-attributes-of-an-asset-in-a-group). 90 911. Link the dynamic libraries in the CMake script. 92 ```txt 93 target_link_libraries(entry PUBLIC libasset_ndk.z.so) 94 ``` 95 962. Query an asset. 97 ```c 98 #include <string.h> 99 100 #include "asset/asset_api.h" 101 102 void QueryAttributes() { 103 static const char *ALIAS = "demo_alias"; 104 Asset_Blob alias = { (uint32_t)(strlen(ALIAS)), (uint8_t *)ALIAS }; 105 Asset_Attr attr[] = { 106 { .tag = ASSET_TAG_ALIAS, .value.blob = alias }, // Specify the alias of the asset to query. 107 { .tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ATTRIBUTES }, // Return only the asset attributes, that is, the result does not include the asset plaintext. 108 }; 109 110 Asset_ResultSet resultSet = {0}; 111 int32_t ret = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet); 112 if (ret == ASSET_SUCCESS) { 113 // Parse the result. 114 for (uint32_t i = 0; i < resultSet.count; i++) { 115 // Parse the data label: the data is label->blob.data, the size is label->blob.size. 116 Asset_Attr *label = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_DATA_LABEL_NORMAL_1); 117 } 118 } 119 OH_Asset_FreeResultSet(&resultSet); 120 } 121 ``` 122 123### Querying Attributes of Assets 124 125Query attributes of assets with the tag of **demo_label** and return a total of 10 records sorted by **DATA_LABEL_NORMAL_1** starting from the fifth record that matches the search criteria. 126 1271. Link the dynamic libraries in the CMake script. 128 ```txt 129 target_link_libraries(entry PUBLIC libasset_ndk.z.so) 130 ``` 131 1322. Query an asset. 133 ```c 134 #include <string.h> 135 136 #include "asset/asset_api.h" 137 138 void BatchQuery() { 139 static const char *LABEL = "demo_label"; 140 Asset_Blob label = { (uint32_t)(strlen(LABEL)), (uint8_t *)LABEL }; 141 142 Asset_Attr attr[] = { 143 { .tag = ASSET_TAG_RETURN_TYPE, .value.u32 = ASSET_RETURN_ATTRIBUTES }, 144 { .tag = ASSET_TAG_DATA_LABEL_NORMAL_1, .value.blob = label }, 145 { .tag = ASSET_TAG_RETURN_OFFSET, .value.u32 = 5 }, 146 { .tag = ASSET_TAG_RETURN_LIMIT, .value.u32 = 10 }, 147 { .tag = ASSET_TAG_RETURN_ORDERED_BY, .value.u32 = ASSET_TAG_DATA_LABEL_NORMAL_1 }, 148 }; 149 150 Asset_ResultSet resultSet = { 0 }; 151 int32_t ret = OH_Asset_Query(attr, sizeof(attr) / sizeof(attr[0]), &resultSet); 152 if (ret == ASSET_SUCCESS) { 153 // Parse the result. 154 for (uint32_t i = 0; i < resultSet.count; i++) { 155 // Parse the data alias: the data is alias->blob.data, the size is alias->blob.size. 156 Asset_Attr *alias = OH_Asset_ParseAttr(resultSet.results + i, ASSET_TAG_ALIAS); 157 } 158 } 159 OH_Asset_FreeResultSet(&resultSet); 160 } 161 ``` 162