1# asset_api.h 2 3## Overview 4 5Defines the functions for accessing assets. 6 7**File to include**: <asset/asset_api.h> 8 9**Library**: libasset_ndk.z.so 10 11**System capability**: SystemCapability.Security.Asset 12 13**Since**: 11 14 15**Related module**: [AssetApi](capi-assetapi.md) 16 17## Summary 18 19### Functions 20 21| Name| Description| 22| -- | -- | 23| [int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt)](#oh_asset_add) | Adds an asset.<br>To set the [Asset_Tag](capi-asset-type-h.md#asset_tag).**ASSET_TAG_IS_PERSISTENT** attribute, request the **ohos.permission.STORE_PERSISTENT_DATA** permission.| 24| [int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt)](#oh_asset_remove) | Removes one or more assets.| 25| [int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt,const Asset_Attr *attributesToUpdate, uint32_t updateCnt)](#oh_asset_update) | Updates an asset.| 26| [int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge)](#oh_asset_prequery) | Performs preprocessing for the asset query. This function is used when user authentication is required for the access to the asset.| 27| [int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet)](#oh_asset_query) | Queries one or more assets.| 28| [int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt)](#oh_asset_postquery) | Performs postprocessing for the asset query. This function is used when user authentication is required for the access to the asset.| 29| [int32_t OH_Asset_QuerySyncResult(const Asset_Attr *query, uint32_t queryCnt, Asset_SyncResult *syncResult)](#oh_asset_querysyncresult) | Queries the sync result of an asset.| 30| [Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag)](#oh_asset_parseattr) | Parses the query result and obtains the specified attribute.| 31| [void OH_Asset_FreeBlob(Asset_Blob *blob)](#oh_asset_freeblob) | Releases the memory occupied by the challenge value.| 32| [void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet)](#oh_asset_freeresultset) | Releases the memory occupied by the query result.| 33 34## Function Description 35 36### OH_Asset_Add() 37 38``` 39int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt) 40``` 41 42**Description** 43 44Adds an asset. 45 46To set the [Asset_Tag](capi-asset-type-h.md#asset_tag).**ASSET_TAG_IS_PERSISTENT** attribute, request the **ohos.permission.STORE_PERSISTENT_DATA** permission. 47 48**Since**: 11 49 50 51**Parameters** 52 53| Parameter| Description| 54| -- | -- | 55| const [Asset_Attr](capi-assettype-asset-attr.md) *attributes | Attributes of the asset to add.| 56| uint32_t attrCnt | Number of attributes of the asset to add.| 57 58**Return value** 59 60| Type| Description| 61| -- | -- | 62| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_PERMISSION_DENIED = 201: The caller is not a system application.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. Mandatory parameters are left unspecified.<br> 2. The parameter type is incorrect.<br> 3. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_DUPLICATED = 24000003: The asset already exists.<br> ASSET_STATUS_MISMATCH = 24000005: The screen lock status is incorrect.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_DATA_CORRUPTED = 24000007: The asset is corrupted.<br> ASSET_DATABASE_ERROR = 24000008: The database operation failed.<br> ASSET_CRYPTO_ERROR = 24000009: The cryptographic operation failed.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_FILE_OPERATION_ERROR = 24000014: The file operation failed.<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015: Failed to obtain the system time.| 63 64### OH_Asset_Remove() 65 66``` 67int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt) 68``` 69 70**Description** 71 72Removes one or more assets. 73 74**Since**: 11 75 76 77**Parameters** 78 79| Parameter| Description| 80| -- | -- | 81| const [Asset_Attr](capi-assettype-asset-attr.md) *query | Attributes of the asset to remove.| 82| uint32_t queryCnt | Number of attributes.| 83 84**Return value** 85 86| Type| Description| 87| -- | -- | 88| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. The parameter type is incorrect.<br> 2. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_NOT_FOUND = 24000002: The asset is not found.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_DATA_CORRUPTED = 24000007: The asset is corrupted.<br> ASSET_DATABASE_ERROR = 24000008: The database operation failed.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015: Failed to obtain the system time.| 89 90### OH_Asset_Update() 91 92``` 93int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt,const Asset_Attr *attributesToUpdate, uint32_t updateCnt) 94``` 95 96**Description** 97 98Updates an asset. 99 100**Since**: 11 101 102 103**Parameters** 104 105| Parameter| Description| 106| -- | -- | 107| const [Asset_Attr](capi-assettype-asset-attr.md) *query | Attributes of the asset to update.| 108| uint32_t queryCnt | Number of attributes to update.| 109| const [Asset_Attr](capi-assettype-asset-attr.md) *attributesToUpdate | New attributes of the asset.| 110| uint32_t updateCnt | Number of new attributes.| 111 112**Return value** 113 114| Type| Description| 115| -- | -- | 116| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. Mandatory parameters are left unspecified.<br> 2. The parameter type is incorrect.<br> 3. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_NOT_FOUND = 24000002: The asset is not found.<br> ASSET_STATUS_MISMATCH = 24000005: The screen lock status is incorrect.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_DATA_CORRUPTED = 24000007: The asset is corrupted.<br> ASSET_DATABASE_ERROR = 24000008: The database operation failed.<br> ASSET_CRYPTO_ERROR = 24000009: The cryptographic operation failed.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015: Failed to obtain the system time.| 117 118### OH_Asset_PreQuery() 119 120``` 121int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge) 122``` 123 124**Description** 125 126Performs preprocessing for the asset query. This API is used when user authentication is required for the access to the asset. 127 128**Since**: 11 129 130 131**Parameters** 132 133| Parameter| Description| 134| -- | -- | 135| const [Asset_Attr](capi-assettype-asset-attr.md) *query | Attributes of the asset to query.| 136| uint32_t queryCnt | Number of attributes.| 137| [Asset_Blob](capi-assettype-asset-blob.md) *challenge | Challenge value, which is used when **OH_Asset_Query** is called.| 138 139**Return value** 140 141| Type| Description| 142| -- | -- | 143| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. The parameter type is incorrect.<br> 2. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_NOT_FOUND = 24000002: The asset is not found.<br> ASSET_STATUS_MISMATCH = 24000005: The screen lock status is incorrect.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_DATA_CORRUPTED = 24000007: The asset is corrupted.<br> ASSET_DATABASE_ERROR = 24000008: The database operation failed.<br> ASSET_CRYPTO_ERROR = 24000009: The cryptographic operation failed.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_LIMIT_EXCEEDED = 24000016: The number of cached assets reaches the limit.<br> ASSET_UNSUPPORTED = 24000017: This function is not supported.| 144 145### OH_Asset_Query() 146 147``` 148int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet) 149``` 150 151**Description** 152 153Queries one or more assets. 154 155**Since**: 11 156 157 158**Parameters** 159 160| Parameter| Description| 161| -- | -- | 162| const [Asset_Attr](capi-assettype-asset-attr.md) *query | Attributes of the asset to query.| 163| uint32_t queryCnt | Number of attributes.| 164| [Asset_ResultSet](capi-assettype-asset-resultset.md) *resultSet | Array of query results.| 165 166**Return value** 167 168| Type| Description| 169| -- | -- | 170| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. The parameter type is incorrect.<br> 2. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_NOT_FOUND = 24000002: The asset is not found.<br> ASSET_ACCESS_DENIED = 24000004: Access to the asset is denied.<br> ASSET_STATUS_MISMATCH = 24000005: The screen lock status is incorrect.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_DATA_CORRUPTED = 24000007: The asset is corrupted.<br> ASSET_DATABASE_ERROR = 24000008: The database operation failed.<br> ASSET_CRYPTO_ERROR = 24000009: The cryptographic operation failed.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_UNSUPPORTED = 24000017: This function is not supported.| 171 172### OH_Asset_PostQuery() 173 174``` 175int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt) 176``` 177 178**Description** 179 180Performs postprocessing for the asset query. This API is used when user authentication is required for the access to the asset. 181 182**Since**: 11 183 184 185**Parameters** 186 187| Parameter| Description| 188| -- | -- | 189| const [Asset_Attr](capi-assettype-asset-attr.md) *handle | Handle of the query operation, including the challenge value returned by **OH_Asset_PreQuery**.| 190| uint32_t handleCnt | Number of elements in the handle attribute set.| 191 192**Return value** 193 194| Type| Description| 195| -- | -- | 196| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_INVALID_ARGUMENT = 401: invalid parameter. Possible causes:<br> 1. Mandatory parameters are left unspecified.<br> 2. The parameter type is incorrect.<br> 3. Parameter verification failed.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.| 197 198### OH_Asset_QuerySyncResult() 199 200``` 201int32_t OH_Asset_QuerySyncResult(const Asset_Attr *query, uint32_t queryCnt, Asset_SyncResult *syncResult) 202``` 203 204**Description** 205 206Queries the sync result of an asset. 207 208**Since**: 20 209 210 211**Parameters** 212 213| Parameter| Description| 214| -- | -- | 215| const [Asset_Attr](capi-assettype-asset-attr.md) *query | Attributes of the asset to query the sync result.| 216| uint32_t queryCnt | Number of attributes.| 217| [Asset_SyncResult](capi-assettype-asset-syncresult.md) *syncResult | Sync result of the queried asset.| 218 219**Return value** 220 221| Type| Description| 222| -- | -- | 223| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0: Operation succeeded.<br> ASSET_SERVICE_UNAVAILABLE = 24000001: The asset service is unavailable.<br> ASSET_OUT_OF_MEMORY = 24000006: The system memory is insufficient.<br> ASSET_IPC_ERROR = 24000010: The IPC failed.<br> ASSET_BMS_ERROR = 24000011: The bundle manager service is abnormal.<br> ASSET_ACCOUNT_ERROR = 24000012: The account service is abnormal.<br> ASSET_ACCESS_TOKEN_ERROR = 24000013: The access token service is abnormal.<br> ASSET_FILE_OPERATION_ERROR = 24000014: The file operation failed.<br> ASSET_PARAM_VERIFICATION_FAILED = 24000018: Parameter verification failed.| 224 225### OH_Asset_ParseAttr() 226 227``` 228Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag) 229``` 230 231**Description** 232 233Parses the query result and obtains the specified attribute. 234 235**Since**: 11 236 237 238**Parameters** 239 240| Parameter| Description| 241| -- | -- | 242| const [Asset_Result](capi-assettype-asset-result.md) *result | Query result returned by **OH_Asset_Query**.| 243| [Asset_Tag](capi-asset-type-h.md#asset_tag) tag | Key of the attribute to obtain.| 244 245**Return value** 246 247| Type| Description| 248| -- | -- | 249| [Asset_Attr](capi-assettype-asset-attr.md) | Returns **Asset_Attr** obtained if the operation is successful; returns **NULL** otherwise. The attribute does not need to be released by the service.| 250 251### OH_Asset_FreeBlob() 252 253``` 254void OH_Asset_FreeBlob(Asset_Blob *blob) 255``` 256 257**Description** 258 259Releases the memory occupied by the challenge value. 260 261**Since**: 11 262 263 264**Parameters** 265 266| Parameter| Description| 267| -- | -- | 268| [Asset_Blob](capi-assettype-asset-blob.md) *blob | Challenge value returned by **OH_Asset_PreQuery**.| 269 270### OH_Asset_FreeResultSet() 271 272``` 273void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet) 274``` 275 276**Description** 277 278Releases the memory occupied by the query result. 279 280**Since**: 11 281 282 283**Parameters** 284 285| Parameter| Description| 286| -- | -- | 287| [Asset_ResultSet](capi-assettype-asset-resultset.md) *resultSet | Query result returned by **OH_Asset_Query**.| 288