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
65
66### OH_Asset_FreeBlob()
67
68```
69void OH_Asset_FreeBlob (Asset_Blob * blob)
70```
71**Description**
72Releases the memory occupied by the challenge value.
73
74**Since**: 11
75
76**Parameters**
77
78| Name| Description|
79| -------- | -------- |
80| blob | Challenge value returned by **OH_Asset_PreQuery**. |
81
82
83### OH_Asset_FreeResultSet()
84
85```
86void OH_Asset_FreeResultSet (Asset_ResultSet * resultSet)
87```
88**Description**
89Releases the memory occupied by the query result.
90
91**Since**: 11
92
93**Parameters**
94
95| Name| Description|
96| -------- | -------- |
97| resultSet | Query result returned by **OH_Asset_Query**. |
98
99
100### OH_Asset_ParseAttr()
101
102```
103Asset_Attr* OH_Asset_ParseAttr (const Asset_Result * result, Asset_Tag tag )
104```
105**Description**
106Parses the query result and obtains the specified attribute.
107
108**Since**: 11
109
110**Parameters**
111
112| Name| Description|
113| -------- | -------- |
114| result | Query result returned by **OH_Asset_Query**. |
115| tag | Key of the attribute to obtain. |
116
117**Returns**
118
119Returns <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.
120
121
122### OH_Asset_PostQuery()
123
124```
125int32_t OH_Asset_PostQuery (const Asset_Attr * handle, uint32_t handleCnt )
126```
127**Description**
128Performs postprocessing for the asset query. This API is used when user authentication is required for the access to the asset.
129
130**Since**: 11
131
132**Parameters**
133
134| Name| Description|
135| -------- | -------- |
136| handle | Handle of the query operation, including the challenge value returned by **OH_Asset_PreQuery**. |
137| handleCnt | Number of elements in the handle attribute set. |
138
139**Returns**
140
141Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise.
142
143
144### OH_Asset_PreQuery()
145
146```
147int32_t OH_Asset_PreQuery (const Asset_Attr * query, uint32_t queryCnt, Asset_Blob * challenge )
148```
149**Description**
150Performs preprocessing for the asset query. This API is used when user authentication is required for the access to the asset.
151
152**Since**: 11
153
154**Parameters**
155
156| Name| Description|
157| -------- | -------- |
158| query | Attributes of the asset to query. |
159| queryCnt | Number of attributes. |
160| challenge | Challenge value, which is used when **OH_Asset_Query** is called. |
161
162**Returns**
163
164Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise.
165
166
167### OH_Asset_Query()
168
169```
170int32_t OH_Asset_Query (const Asset_Attr * query, uint32_t queryCnt, Asset_ResultSet * resultSet )
171```
172**Description**
173Queries one or more assets.
174
175**Since**: 11
176
177**Parameters**
178
179| Name| Description|
180| -------- | -------- |
181| query | Attributes of the asset to query. |
182| queryCnt | Number of attributes. |
183| resultSet | Array of query results. |
184
185**Returns**
186
187Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise.
188
189### OH_Asset_Remove()
190
191```
192int32_t OH_Asset_Remove (const Asset_Attr * query, uint32_t queryCnt )
193```
194**Description**
195Removes one or more assets.
196
197**Since**: 11
198
199**Parameters**
200
201| Name| Description|
202| -------- | -------- |
203| query | Attributes of the asset to remove. |
204| queryCnt | Number of Attributes. |
205
206**Returns**
207
208Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise.
209
210
211### OH_Asset_Update()
212
213```
214int32_t OH_Asset_Update (const Asset_Attr * query, uint32_t queryCnt, const Asset_Attr * attributesToUpdate, uint32_t updateCnt )
215```
216**Description**
217Updates an asset.
218
219**Since**: 11
220
221**Parameters**
222
223| Name| Description|
224| -------- | -------- |
225| query | Attributes of the asset to update. |
226| queryCnt | Number of attributes to update. |
227| attributesToUpdate | New attributes of the asset. |
228| updateCnt | Number of new attributes. |
229
230**Returns**
231
232Returns [ASSET_SUCCESS](_asset_type.md#asset_resultcode) if the operation is successful; returns an error code otherwise.
233