1# asset_api.h 2 3<!--Kit: Asset Store Kit--> 4<!--Subsystem: Security--> 5<!--Owner: @JeremyXu--> 6<!--Designer: @skye_you--> 7<!--Tester: @nacyli--> 8<!--Adviser: @zengyawen--> 9 10## 概述 11 12声明用于访问关键资产的接口。 13 14**引用文件：** <asset/asset_api.h> 15 16**库：** libasset_ndk.z.so 17 18**系统能力：** SystemCapability.Security.Asset 19 20**起始版本：** 11 21 22**相关模块：** [AssetApi](capi-assetapi.md) 23 24## 汇总 25 26### 函数 27 28| 名称 | 描述 | 29| -- | -- | 30| [int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt)](#oh_asset_add) | 新增一条关键资产。<br>如果要设置[Asset_Tag](capi-asset-type-h.md#asset_tag).ASSET_TAG_IS_PERSISTENT属性，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。 | 31| [int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt)](#oh_asset_remove) | 删除符合条件的一条或多条关键资产。 | 32| [int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt, const Asset_Attr *attributesToUpdate, uint32_t updateCnt)](#oh_asset_update) | 更新符合条件的一条关键资产。 | 33| [int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge)](#oh_asset_prequery) | 查询的预处理，用于需要用户认证的关键资产。 | 34| [int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet)](#oh_asset_query) | 查询一条或多条符合条件的关键资产。 | 35| [int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt)](#oh_asset_postquery) | 查询的后置处理，用于需要用户认证的关键资产。 | 36| [int32_t OH_Asset_QuerySyncResult(const Asset_Attr *query, uint32_t queryCnt, Asset_SyncResult *syncResult)](#oh_asset_querysyncresult) | 查询关键资产的同步结果。 | 37| [Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag)](#oh_asset_parseattr) | 解析查询结果，并获取指定的属性值。 | 38| [void OH_Asset_FreeBlob(Asset_Blob *blob)](#oh_asset_freeblob) | 释放挑战值所占用的内存。 | 39| [void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet)](#oh_asset_freeresultset) | 释放查询结果所占用的内存。 | 40 41## 函数说明 42 43### OH_Asset_Add() 44 45``` 46int32_t OH_Asset_Add(const Asset_Attr *attributes, uint32_t attrCnt) 47``` 48 49**描述** 50 51新增一条关键资产。 52 53如果要设置[Asset_Tag](capi-asset-type-h.md#asset_tag).ASSET_TAG_IS_PERSISTENT属性，需要申请ohos.permission.STORE_PERSISTENT_DATA权限。 54 55**起始版本：** 11 56 57 58**参数：** 59 60| 参数项 | 描述 | 61| -- | -- | 62| const [Asset_Attr](capi-assettype-asset-attr.md) *attributes | 待新增关键资产的属性集合。 | 63| uint32_t attrCnt | 待新增关键资产的属性数量。 | 64 65**返回：** 66 67| 类型 | 说明 | 68| -- | -- | 69| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_PERMISSION_DENIED = 201：调用方不是一个系统应用。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 必选参数未指定。<br> 2. 参数类型错误。<br> 3. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_DUPLICATED = 24000003：关键资产已存在。<br> ASSET_STATUS_MISMATCH = 24000005：锁屏状态不匹配。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_DATA_CORRUPTED = 24000007：关键资产损坏。<br> ASSET_DATABASE_ERROR = 24000008：数据库操作失败。<br> ASSET_CRYPTO_ERROR = 24000009：算法库操作失败。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_FILE_OPERATION_ERROR = 24000014：文件操作失败。<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015：获取系统时间失败。 | 70 71### OH_Asset_Remove() 72 73``` 74int32_t OH_Asset_Remove(const Asset_Attr *query, uint32_t queryCnt) 75``` 76 77**描述** 78 79删除符合条件的一条或多条关键资产。 80 81**起始版本：** 11 82 83 84**参数：** 85 86| 参数项 | 描述 | 87| -- | -- | 88| const [Asset_Attr](capi-assettype-asset-attr.md) *query | 待删除关键资产的搜索条件。 | 89| uint32_t queryCnt | 待删除关键资产搜索条件的个数。 | 90 91**返回：** 92 93| 类型 | 说明 | 94| -- | -- | 95| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 参数类型错误。<br> 2. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_NOT_FOUND = 24000002：未找到关键资产。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_DATA_CORRUPTED = 24000007：关键资产损坏。<br> ASSET_DATABASE_ERROR = 24000008：数据库操作失败。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015：获取系统时间失败。 | 96 97### OH_Asset_Update() 98 99``` 100int32_t OH_Asset_Update(const Asset_Attr *query, uint32_t queryCnt,const Asset_Attr *attributesToUpdate, uint32_t updateCnt) 101``` 102 103**描述** 104 105更新符合条件的一条关键资产。 106 107**起始版本：** 11 108 109 110**参数：** 111 112| 参数项 | 描述 | 113| -- | -- | 114| const [Asset_Attr](capi-assettype-asset-attr.md) *query | 待更新关键资产的搜索条件。 | 115| uint32_t queryCnt | 待更新关键资产搜索条件的个数。 | 116| const [Asset_Attr](capi-assettype-asset-attr.md) *attributesToUpdate | 待更新关键资产的属性集合。 | 117| uint32_t updateCnt | 待更新关键资产的属性数量。 | 118 119**返回：** 120 121| 类型 | 说明 | 122| -- | -- | 123| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 必选参数未指定。<br> 2. 参数类型错误。<br> 3. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_NOT_FOUND = 24000002：未找到关键资产。<br> ASSET_STATUS_MISMATCH = 24000005：锁屏状态不匹配。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_DATA_CORRUPTED = 24000007：关键资产损坏。<br> ASSET_DATABASE_ERROR = 24000008：数据库操作失败。<br> ASSET_CRYPTO_ERROR = 24000009：算法库操作失败。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_GET_SYSTEM_TIME_ERROR = 24000015：获取系统时间失败。 | 124 125### OH_Asset_PreQuery() 126 127``` 128int32_t OH_Asset_PreQuery(const Asset_Attr *query, uint32_t queryCnt, Asset_Blob *challenge) 129``` 130 131**描述** 132 133查询的预处理，用于需要用户认证的关键资产。 134 135**起始版本：** 11 136 137 138**参数：** 139 140| 参数项 | 描述 | 141| -- | -- | 142| const [Asset_Attr](capi-assettype-asset-attr.md) *query | 关键资产的查询条件。 | 143| uint32_t queryCnt | 关键资产查询条件的个数。 | 144| [Asset_Blob](capi-assettype-asset-blob.md) *challenge | 挑战值，在后续调用[OH_Asset_Query](#oh_asset_query)时使用。 | 145 146**返回：** 147 148| 类型 | 说明 | 149| -- | -- | 150| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 参数类型错误。<br> 2. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_NOT_FOUND = 24000002：未找到关键资产。<br> ASSET_STATUS_MISMATCH = 24000005：锁屏状态不匹配。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_DATA_CORRUPTED = 24000007：关键资产损坏。<br> ASSET_DATABASE_ERROR = 24000008：数据库操作失败。<br> ASSET_CRYPTO_ERROR = 24000009：算法库操作失败。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_LIMIT_EXCEEDED = 24000016：缓存数量超限。<br> ASSET_UNSUPPORTED = 24000017：该子功能不支持。 | 151 152### OH_Asset_Query() 153 154``` 155int32_t OH_Asset_Query(const Asset_Attr *query, uint32_t queryCnt, Asset_ResultSet *resultSet) 156``` 157 158**描述** 159 160查询一条或多条符合条件的关键资产。 161 162**起始版本：** 11 163 164 165**参数：** 166 167| 参数项 | 描述 | 168| -- | -- | 169| const [Asset_Attr](capi-assettype-asset-attr.md) *query | 关键资产的查询条件。 | 170| uint32_t queryCnt | 关键资产查询条件的个数。 | 171| [Asset_ResultSet](capi-assettype-asset-resultset.md) *resultSet | 查询结果列表。 | 172 173**返回：** 174 175| 类型 | 说明 | 176| -- | -- | 177| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 参数类型错误。<br> 2. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_NOT_FOUND = 24000002：未找到关键资产。<br> ASSET_ACCESS_DENIED = 24000004：拒绝访问关键资产。<br> ASSET_STATUS_MISMATCH = 24000005：锁屏状态不匹配。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_DATA_CORRUPTED = 24000007：关键资产损坏。<br> ASSET_DATABASE_ERROR = 24000008：数据库操作失败。<br> ASSET_CRYPTO_ERROR = 24000009：算法库操作失败。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_UNSUPPORTED = 24000017：该子功能不支持。 | 178 179### OH_Asset_PostQuery() 180 181``` 182int32_t OH_Asset_PostQuery(const Asset_Attr *handle, uint32_t handleCnt) 183``` 184 185**描述** 186 187查询的后置处理，用于需要用户认证的关键资产。 188 189**起始版本：** 11 190 191 192**参数：** 193 194| 参数项 | 描述 | 195| -- | -- | 196| const [Asset_Attr](capi-assettype-asset-attr.md) *handle | 待处理的查询句柄，当前包含[OH_Asset_PreQuery](#oh_asset_prequery)执行成功返回的挑战值。 | 197| uint32_t handleCnt | 句柄属性集合中元素的个数。 | 198 199**返回：** 200 201| 类型 | 说明 | 202| -- | -- | 203| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode):<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_INVALID_ARGUMENT = 401：参数错误。 可能原因:<br> 1. 必选参数未指定。<br> 2. 参数类型错误。<br> 3. 参数校验失败。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。 | 204 205### OH_Asset_QuerySyncResult() 206 207``` 208int32_t OH_Asset_QuerySyncResult(const Asset_Attr *query, uint32_t queryCnt, Asset_SyncResult *syncResult) 209``` 210 211**描述** 212 213查询关键资产的同步结果。 214 215**起始版本：** 20 216 217 218**参数：** 219 220| 参数项 | 描述 | 221| -- | -- | 222| const [Asset_Attr](capi-assettype-asset-attr.md) *query | 关键资产同步结果的查询条件。 | 223| uint32_t queryCnt | 关键资产同步结果的查询条件个数。 | 224| [Asset_SyncResult](capi-assettype-asset-syncresult.md) *syncResult | 查询到的关键资产同步结果。 | 225 226**返回：** 227 228| 类型 | 说明 | 229| -- | -- | 230| int32_t | [Asset_ResultCode](capi-asset-type-h.md#asset_resultcode)：<br> ASSET_SUCCESS = 0：操作成功。<br> ASSET_SERVICE_UNAVAILABLE = 24000001：关键资产服务不可用。<br> ASSET_OUT_OF_MEMORY = 24000006：系统内存不足。<br> ASSET_IPC_ERROR = 24000010：进程通信错误。<br> ASSET_BMS_ERROR = 24000011：包管理服务异常。<br> ASSET_ACCOUNT_ERROR = 24000012：账号系统异常。<br> ASSET_ACCESS_TOKEN_ERROR = 24000013：访问控制服务异常。<br> ASSET_FILE_OPERATION_ERROR = 24000014：文件操作失败。<br> ASSET_PARAM_VERIFICATION_FAILED = 24000018：参数校验失败。 | 231 232### OH_Asset_ParseAttr() 233 234``` 235Asset_Attr *OH_Asset_ParseAttr(const Asset_Result *result, Asset_Tag tag) 236``` 237 238**描述** 239 240解析查询结果，并获取指定的属性值。 241 242**起始版本：** 11 243 244 245**参数：** 246 247| 参数项 | 描述 | 248| -- | -- | 249| const [Asset_Result](capi-assettype-asset-result.md) *result | 从[OH_Asset_Query](#oh_asset_query)中获取的查询结果。 | 250| [Asset_Tag](capi-asset-type-h.md#asset_tag) tag | 待获取的属性标签。 | 251 252**返回：** 253 254| 类型 | 说明 | 255| -- | -- | 256| [Asset_Attr](capi-assettype-asset-attr.md) | 如果操作成功，则以Asset_Attr的形式返回属性，该属性不需要业务进行释放；否则返回NULL。 | 257 258### OH_Asset_FreeBlob() 259 260``` 261void OH_Asset_FreeBlob(Asset_Blob *blob) 262``` 263 264**描述** 265 266释放挑战值所占用的内存。 267 268**起始版本：** 11 269 270 271**参数：** 272 273| 参数项 | 描述 | 274| -- | -- | 275| [Asset_Blob](capi-assettype-asset-blob.md) *blob | 从[OH_Asset_PreQuery](#oh_asset_prequery)获取的挑战值。 | 276 277### OH_Asset_FreeResultSet() 278 279``` 280void OH_Asset_FreeResultSet(Asset_ResultSet *resultSet) 281``` 282 283**描述** 284 285释放查询结果所占用的内存。 286 287**起始版本：** 11 288 289 290**参数：** 291 292| 参数项 | 描述 | 293| -- | -- | 294| [Asset_ResultSet](capi-assettype-asset-resultset.md) *resultSet | 从[OH_Asset_Query](#oh_asset_query)得到的查询结果列表。 | 295 296 297