1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file asset_system_api.h 18 * 19 * @brief Declares asset operation system interface. 20 * 21 * @since 11 22 */ 23 24 #ifndef ASSET_SYSTEM_API_H 25 #define ASSET_SYSTEM_API_H 26 27 #include <stdint.h> 28 #include <stdlib.h> 29 30 #include "asset_system_type.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @brief Adds an asset. 38 * 39 * @param attributes Pointer to the attributes of the asset to add. 40 * @param attributes Number of the attributes of the asset to add. 41 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 42 * @since 11 43 */ 44 int32_t AssetAdd(const AssetAttr *attributes, uint32_t attrCnt); 45 46 /** 47 * @brief Removes one or more assets. 48 * 49 * @param query Pointer to the conditions for removing the assets. 50 * @param queryCnt Number of conditions for removing the assets. 51 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 52 * @since 11 53 */ 54 int32_t AssetRemove(const AssetAttr *query, uint32_t queryCnt); 55 56 /** 57 * @brief Updates an asset. 58 * 59 * @param query Pointer to the conditions for updating the asset. 60 * @param queryCnt Number of conditions for updating the asset. 61 * @param attributes Pointer to the attributes of the asset to update. 62 * @param attributes Number of the attributes of the asset to update. 63 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 64 * @since 11 65 */ 66 int32_t AssetUpdate(const AssetAttr *query, uint32_t queryCnt, 67 const AssetAttr *attributesToUpdate, uint32_t updateCnt); 68 69 /** 70 * @brief Preprocesses data before querying the asset that can be accessed only after a successful user authentication. 71 * 72 * @param query Pointer to the search criteria of the asset. 73 * @param queryCnt Number of the search criteria. 74 * @param challenge Pointer to the challenge value to be used when <b>AssetQuery</b> is called. 75 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 76 * @since 11 77 */ 78 int32_t AssetPreQuery(const AssetAttr *query, uint32_t queryCnt, AssetBlob *challenge); 79 80 /** 81 * @brief Queries assets. 82 * 83 * @param query Pointer to the search criteria. 84 * @param queryCnt Number of the search criteria. 85 * @param resultSet Pointer to the query result obtained. 86 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 87 * @since 11 88 */ 89 int32_t AssetQuery(const AssetAttr *query, uint32_t queryCnt, AssetResultSet *resultSet); 90 91 /** 92 * @brief Processes data after the query of the asset that requires user authentication. 93 * 94 * @param handle Pointer to the handle of the data to process, which includes the challenge value returned by 95 * <b>AssetPreQuery</b>. 96 * @param handleCnt Number of the elements in the handle attribute set. 97 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 98 * @since 11 99 */ 100 int32_t AssetPostQuery(const AssetAttr *handle, uint32_t handleCnt); 101 102 /** 103 * @brief Query the result of synchronization. 104 * 105 * @param query Pointer to the search criteria. 106 * @param queryCnt Number of the search criteria. 107 * @param syncResult Pointer to the synchronization result obtained. 108 * @return Returns <b>SEC_ASSET_SUCCESS</b> if the operation is successful; returns an error code otherwise. 109 * @since 20 110 */ 111 int32_t AssetQuerySyncResult(const AssetAttr *query, uint32_t queryCnt, AssetSyncResult *syncResult); 112 113 /** 114 * @brief Parses the query result to obtain the specified attribute value. 115 * 116 * @param result Pointer to the query result to parse, which is obtained by <b>AssetQuery</b>. 117 * @param tag Tag of the attribute to obtain. 118 * @return Returns <b>AssetAttr</b> obtained if the operation is successful; returns <b>NULL</b> otherwise. 119 * The attribute does not need to be released by the service. 120 * @since 11 121 */ 122 AssetAttr *AssetParseAttr(const AssetResult *result, AssetTag tag); 123 124 /** 125 * @brief Releases the memory occupied by the challenge value. 126 * 127 * @param blob Pointer to the challenge value (obtained by <b>AssetPreQuery</b>) to release. 128 * @since 11 129 */ 130 void AssetFreeBlob(AssetBlob *blob); 131 132 /** 133 * @brief Releases the memory occupied by the query result. 134 * 135 * @param resultSet Pointer to the query result (obtained by <b>AssetQuery</b>) to release. 136 * @since 11 137 */ 138 void AssetFreeResultSet(AssetResultSet *resultSet); 139 140 #ifdef __cplusplus 141 } 142 #endif 143 144 #endif // ASSET_SYSTEM_API_H 145