1# AssetApi 2 3 4## Overview 5 6Provides functions for adding, removing, updating, and querying sensitive data less than 1024 bytes in size, 7including passwords, app tokens, and other critical data (such as bank card numbers). 8 9**System capability**: SystemCapability.Security.Asset 10 11**Since**: 11 12 13 14## Summary 15 16 17### Files 18 19| Name| Description| 20| -------- | -------- | 21| [asset_api.h](asset__api_8h.md) | Defines the functions for accessing assets. | 22 23 24### Functions 25 26| Name| Description| 27| -------- | -------- | 28| int32_t [OH_Asset_Add](#oh_asset_add) (const [Asset_Attr](_asset___attr.md) \*attributes, uint32_t attrCnt) | Adds an asset.| 29| int32_t [OH_Asset_Remove](#oh_asset_remove) (const [Asset_Attr](_asset___attr.md) \*query, uint32_t queryCnt) | Removes one or more assets. | 30| int32_t [OH_Asset_Update](#oh_asset_update) (const [Asset_Attr](_asset___attr.md) \*query, uint32_t queryCnt, const [Asset_Attr](_asset___attr.md) \*attributesToUpdate, uint32_t updateCnt) | Updates an asset. | 31| int32_t [OH_Asset_PreQuery](#oh_asset_prequery) (const [Asset_Attr](_asset___attr.md) \*query, uint32_t queryCnt, [Asset_Blob](_asset___blob.md) \*challenge) | Performs preprocessing for the asset query. This function is used when user authentication is required for the access to the asset. | 32| int32_t [OH_Asset_Query](#oh_asset_query) (const [Asset_Attr](_asset___attr.md) \*query, uint32_t queryCnt, [Asset_ResultSet](_asset___result_set.md) \*resultSet) | Queries one or more assets. | 33| int32_t [OH_Asset_PostQuery](#oh_asset_postquery) (const [Asset_Attr](_asset___attr.md) \*handle, uint32_t handleCnt) | Performs postprocessing for the asset query. This function is used when user authentication is required for the access to the asset. | 34| [Asset_Attr](_asset___attr.md) \* [OH_Asset_ParseAttr](#oh_asset_parseattr) (const [Asset_Result](_asset___result.md) \*result, [Asset_Tag](_asset_type.md#asset_tag) tag) | Parses the query result and obtains the specified attribute. | 35| void [OH_Asset_FreeBlob](#oh_asset_freeblob) ([Asset_Blob](_asset___blob.md) \*blob) | Releases the memory occupied by the challenge value. | 36| void [OH_Asset_FreeResultSet](#oh_asset_freeresultset) ([Asset_ResultSet](_asset___result_set.md) \*resultSet) | Releases the memory occupied by the query result. | 37 38 39## Function Description 40 41 42### OH_Asset_Add() 43 44``` 45int32_t OH_Asset_Add (const Asset_Attr * attributes, uint32_t attrCnt ) 46``` 47**Description** 48Adds an asset. 49 50To set [ASSET_TAG_IS_PERSISTENT](_asset_type.md#asset_tag), the application must have the ohos.permission.STORE_PERSISTENT_DATA permission. 51 52**Since**: 11 53 54**Parameters** 55 56| Name| Description| 57| -------- | -------- | 58| attributes | Attributes of the asset to add | 59| attrCnt | Number of attributes of the asset to add. | 60 61**Returns** 62 63Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 64 650 - The operation is successful. 66 67201 - The caller does not have the required permission. 68 69401 - The parameter is invalid. 70 7124000001 - The asset store service is unavailable. 72 7324000003 - The asset already exists. 74 7524000005 - The lock screen status does not match. 76 7724000006 - The system memory is insufficient. 78 7924000007 - The asset is corrupted. 80 8124000008 - The database operation failed. 82 8324000009 - The cryptographic operation failed. 84 8524000010 - The IPC failed. 86 8724000011 - The Bundle Manager service is abnormal. 88 8924000012 - The Account service is abnormal. 90 9124000013 - The Access Token service is abnormal. 92 9324000014 - The file operation failed. 94 9524000015 - Failed to obtain the system time. 96 97### OH_Asset_FreeBlob() 98 99``` 100void OH_Asset_FreeBlob (Asset_Blob * blob) 101``` 102**Description** 103Releases the memory occupied by the challenge value. 104 105**Since**: 11 106 107**Parameters** 108 109| Name| Description| 110| -------- | -------- | 111| blob | Challenge value returned by **OH_Asset_PreQuery**. | 112 113 114### OH_Asset_FreeResultSet() 115 116``` 117void OH_Asset_FreeResultSet (Asset_ResultSet * resultSet) 118``` 119**Description** 120Releases the memory occupied by the query result. 121 122**Since**: 11 123 124**Parameters** 125 126| Name| Description| 127| -------- | -------- | 128| resultSet | Query result returned by **OH_Asset_Query**. | 129 130 131### OH_Asset_ParseAttr() 132 133``` 134Asset_Attr* OH_Asset_ParseAttr (const Asset_Result * result, Asset_Tag tag ) 135``` 136**Description** 137Parses the query result and obtains the specified attribute. 138 139**Since**: 11 140 141**Parameters** 142 143| Name| Description| 144| -------- | -------- | 145| result | Query result returned by **OH_Asset_Query**. | 146| tag | Key of the attribute to obtain. | 147 148**Returns** 149 150Returns <b>Asset_Attr</b> obtained if the operation is successful; returns <b>NULL</b> otherwise. The attribute does not need to be released by the service. 151 152 153### OH_Asset_PostQuery() 154 155``` 156int32_t OH_Asset_PostQuery (const Asset_Attr * handle, uint32_t handleCnt ) 157``` 158**Description** 159Performs postprocessing for the asset query. This API is used when user authentication is required for the access to the asset. 160 161**Since**: 11 162 163**Parameters** 164 165| Name| Description| 166| -------- | -------- | 167| handle | Handle of the query operation, including the challenge value returned by **OH_Asset_PreQuery**. | 168| handleCnt | Number of elements in the handle attribute set. | 169 170**Returns** 171 172Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 173 1740 - The operation is successful. 175 176401 - The parameter is invalid. 177 17824000001 - The asset store service is unavailable. 179 18024000006 - The system memory is insufficient. 181 18224000010 - The IPC failed. 183 18424000011 - The Bundle Manager service is abnormal. 185 18624000012 - The Account service is abnormal. 187 18824000013 - The Access Token service is abnormal. 189 190### OH_Asset_PreQuery() 191 192``` 193int32_t OH_Asset_PreQuery (const Asset_Attr * query, uint32_t queryCnt, Asset_Blob * challenge ) 194``` 195**Description** 196Performs preprocessing for the asset query. This API is used when user authentication is required for the access to the asset. 197 198**Since**: 11 199 200**Parameters** 201 202| Name| Description| 203| -------- | -------- | 204| query | Attributes of the asset to query. | 205| queryCnt | Number of attributes. | 206| challenge | Challenge value, which is used when **OH_Asset_Query** is called. | 207 208**Returns** 209 210Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 211 2120 - The operation is successful. 213 214401 - The parameter is invalid. 215 21624000001 - The asset store service is unavailable. 217 21824000002 - The asset is not found. 219 22024000005 - The lock screen status does not match. 221 22224000006 - The system memory is insufficient. 223 22424000007 - The asset is corrupted. 225 22624000008 - The database operation failed. 227 22824000009 - The cryptographic operation failed. 229 23024000010 - The IPC failed. 231 23224000011 - The Bundle Manager service is abnormal. 233 23424000012 - The Account service is abnormal. 235 23624000013 - The Access Token service is abnormal. 237 23824000016 - The number of cached assets exceeds the limit. 239 24024000017 - The function is not supported. 241 242### OH_Asset_Query() 243 244``` 245int32_t OH_Asset_Query (const Asset_Attr * query, uint32_t queryCnt, Asset_ResultSet * resultSet ) 246``` 247**Description** 248Queries one or more assets. 249 250**Since**: 11 251 252**Parameters** 253 254| Name| Description| 255| -------- | -------- | 256| query | Attributes of the asset to query. | 257| queryCnt | Number of attributes. | 258| resultSet | Array of query results. | 259 260**Returns** 261 262Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 263 2640 - The operation is successful. 265 266401 - The parameter is invalid. 267 26824000001 - The asset store service is unavailable. 269 27024000002 - The asset is not found. 271 27224000004 - The access to the asset is denied. 273 27424000005 - The lock screen status does not match. 275 27624000006 - The system memory is insufficient. 277 27824000007 - The asset is corrupted. 279 28024000008 - The database operation failed. 281 28224000009 - The cryptographic operation failed. 283 28424000010 - The IPC failed. 285 28624000011 - The Bundle Manager service is abnormal. 287 28824000012 - The Account service is abnormal. 289 29024000013 - The Access Token service is abnormal. 291 29224000017 - The function is not supported. 293 294### OH_Asset_Remove() 295 296``` 297int32_t OH_Asset_Remove (const Asset_Attr * query, uint32_t queryCnt ) 298``` 299**Description** 300Removes one or more assets. 301 302**Since**: 11 303 304**Parameters** 305 306| Name| Description| 307| -------- | -------- | 308| query | Attributes of the asset to remove. | 309| queryCnt | Number of Attributes. | 310 311**Returns** 312 313Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 314 3150 - The operation is successful. 316 317401 - The parameter is invalid. 318 31924000001 - The asset store service is unavailable. 320 32124000002 - The asset is not found. 322 32324000006 - The system memory is insufficient. 324 32524000007 - The asset is corrupted. 326 32724000008 - The database operation failed. 328 32924000010 - The IPC failed. 330 33124000011 - The Bundle Manager service is abnormal. 332 33324000012 - The Account service is abnormal. 334 33524000013 - The Access Token service is abnormal. 336 33724000015 - Failed to obtain the system time. 338 339### OH_Asset_Update() 340 341``` 342int32_t OH_Asset_Update (const Asset_Attr * query, uint32_t queryCnt, const Asset_Attr * attributesToUpdate, uint32_t updateCnt ) 343``` 344**Description** 345Updates an asset. 346 347**Since**: 11 348 349**Parameters** 350 351| Name| Description| 352| -------- | -------- | 353| query | Attributes of the asset to update. | 354| queryCnt | Number of attributes to update. | 355| attributesToUpdate | New attributes of the asset. | 356| updateCnt | Number of new attributes. | 357 358**Returns** 359 360Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise. 361 3620 - The operation is successful. 363 364401 - The parameter is invalid. 365 36624000001 - The asset store service is unavailable. 367 36824000002 - The asset is not found. 369 37024000005 - The lock screen status does not match. 371 37224000006 - The system memory is insufficient. 373 37424000007 - The asset is corrupted. 375 37624000008 - The database operation failed. 377 37824000009 - The cryptographic operation failed. 379 38024000010 - The IPC failed. 381 38224000011 - The Bundle Manager service is abnormal. 383 38424000012 - The Account service is abnormal. 385 38624000013 - The Access Token service is abnormal. 387 38824000015 - Failed to obtain the system time. 389