1 /* 2 * Copyright (c) 2023 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 * @defgroup cloud_extension C headers 18 * @ingroup cloud_extension 19 */ 20 21 #ifndef CLOUD_EXTENSION_H 22 #define CLOUD_EXTENSION_H 23 24 #ifndef CLOUD_EXTENSION_BASIC_RUST_TYPES_H 25 #include "basic_rust_types.h" 26 #endif 27 28 #ifndef CLOUD_EXTENSION_TYPES_H 29 #include "cloud_ext_types.h" 30 #endif 31 32 #ifndef CLOUD_EXTENSION_ERROR_H 33 #include "error.h" 34 #endif 35 36 #include <stddef.h> 37 38 #ifdef __cplusplus 39 #if __cplusplus 40 extern "C" { 41 #endif 42 #endif 43 44 // CloudAssetLoader, CloudDatabase, CloudSync 45 /** 46 * @brief Type declaration of Rust cloud extension struct CloudAssetLoader. 47 * @attention When an instance is created by CloudAssetLoaderNew，memory is managed by Rust and 48 * it will return a pointer. When destroying this instance, users should call 49 * CloudAssetLoaderFree to release memory and prevent leak. 50 * 51 * Besides, CloudAssetLoader is only valid when the database passed in its initialization 52 * function is valid. 53 */ 54 typedef struct { 55 const size_t id; 56 } OhCloudExtCloudAssetLoader; 57 58 /** 59 * @brief Information needed when upload or download assets through CloudAssetLoader. 60 */ 61 typedef struct { 62 const unsigned char *tableName; 63 const unsigned int tableNameLen; 64 const unsigned char *gid; 65 const unsigned int gidLen; 66 const unsigned char *prefix; 67 const unsigned int prefixLen; 68 } OhCloudExtUpDownloadInfo; 69 70 /** 71 * @brief Create an CloudAssetLoader instance. 72 * @param userId [IN] 73 * bundleName [IN] 74 * nameLen [IN] 75 * db [IN] 76 */ 77 OhCloudExtCloudAssetLoader *OhCloudExtCloudAssetLoaderNew( 78 int userId, 79 const unsigned char *bundleName, 80 unsigned int nameLen, 81 OhCloudExtDatabase* db 82 ); 83 84 /** 85 * @brief Upload assets. 86 * @param loader [IN] 87 * tableName [IN] 88 * tableNameLen [IN] 89 * gid [IN] 90 * gidLen [IN] 91 * prefix [IN] 92 * prefixLen [IN] 93 * assets [IN/OUT] HashMap<String, Value> 94 * @attention The Vector returned should be freed by `OhCloudExtVectorFree` if no longer in use. 95 */ 96 int OhCloudExtCloudAssetLoaderUpload( 97 OhCloudExtCloudAssetLoader *loader, 98 const OhCloudExtUpDownloadInfo *info, 99 OhCloudExtVector *assets 100 ); 101 102 /** 103 * @brief Download assets. 104 * @param loader [IN] 105 * tableName [IN] 106 * tableNameLen [IN] 107 * gid [IN] 108 * gidLen [IN] 109 * prefix [IN] 110 * prefixLen [IN] 111 * assets [IN/OUT] HashMap<String, Value> 112 * @attention The Vector returned should be freed by `OhCloudExtVectorFree` if no longer in use. 113 */ 114 int OhCloudExtCloudAssetLoaderDownload( 115 OhCloudExtCloudAssetLoader *loader, 116 const OhCloudExtUpDownloadInfo *info, 117 OhCloudExtVector *assets 118 ); 119 120 /** 121 * @brief Remove one asset from the local path. 122 * @param asset [IN] 123 */ 124 int OhCloudExtCloudAssetLoaderRemoveLocalAssets(const OhCloudExtCloudAsset *asset); 125 126 /** 127 * @brief Destroy an CloudAssetLoader instance. 128 * @param ptr [IN] The pointer of CloudAssetLoader that should be destroyed. 129 */ 130 void OhCloudExtCloudAssetLoaderFree(OhCloudExtCloudAssetLoader *ptr); 131 132 /** 133 * @brief Type declaration of Rust cloud extension struct CloudDatabase. 134 * @attention When an instance is created by CloudDbNew，memory is managed by Rust and it will return a pointer. 135 * When destroying this instance, users should call CloudDatabaseFree to release memory and prevent leak. 136 */ 137 typedef struct { 138 const size_t id; 139 } OhCloudExtCloudDatabase; 140 141 /** 142 * @brief Create an CloudDatabase instance. 143 * @retval != NULL, a valid pointer of CloudDatabase. 144 * @attention Database passed in will be managed by CloudDb instead. No free function is needed to call on it. 145 */ 146 OhCloudExtCloudDatabase *OhCloudExtCloudDbNew( 147 int userId, 148 const unsigned char *bundleName, 149 unsigned int nameLen, 150 OhCloudExtDatabase *database 151 ); 152 153 /** 154 * @brief Sql that will passed to CloudDatabase and executed. 155 */ 156 typedef struct { 157 const unsigned char *table; 158 const unsigned int tableLen; 159 const unsigned char *sql; 160 const unsigned int sqlLen; 161 } OhCloudExtSql; 162 163 /** 164 * @brief Execute a sql on a CloudDatabase instance. 165 * @param cdb [IN] 166 * table [IN] 167 * tableLen [IN] 168 * sql [IN] 169 * sqlLen [IN] 170 * extend [IN/OUT] HashMap<String, Value> 171 * @retval SUCCESS 172 * ERRNO_Unsupported 173 */ 174 int OhCloudExtCloudDbExecuteSql( 175 OhCloudExtCloudDatabase *cdb, 176 const OhCloudExtSql *sql, 177 OhCloudExtHashMap *extend 178 ); 179 180 /** 181 * @brief Insert batches of value buckets into a CloudDatabase instance. 182 * @param cdb [IN] 183 * table [IN] 184 * tableLen [IN] 185 * value [IN] Vec<HashMap<String, Value>> 186 * extend [IN/OUT] Vec<HashMap<String, Value>> 187 * @retval SUCCESS 188 */ 189 int OhCloudExtCloudDbBatchInsert( 190 OhCloudExtCloudDatabase *cdb, 191 const unsigned char *table, 192 unsigned int tableLen, 193 const OhCloudExtVector *value, 194 OhCloudExtVector *extend 195 ); 196 197 /** 198 * @brief Update batches of value buckets in a CloudDatabase instance. 199 * @param cdb [IN] 200 * table [IN] 201 * tableLen [IN] 202 * value [IN] Vec<HashMap<String, Value>> 203 * extend [IN/OUT] Vec<HashMap<String, Value>> 204 * @retval SUCCESS 205 */ 206 int OhCloudExtCloudDbBatchUpdate( 207 OhCloudExtCloudDatabase *cdb, 208 const unsigned char *table, 209 unsigned int tableLen, 210 const OhCloudExtVector *value, 211 OhCloudExtVector *extend 212 ); 213 214 /** 215 * @brief Delete batches of value buckets from a CloudDatabase instance. 216 * @param cdb [IN] 217 * table [IN] 218 * tableLen [IN] 219 * value [IN] Vec<HashMap<String, Value>> 220 * extend [IN/OUT] Vec<HashMap<String, Value>> 221 * @retval SUCCESS 222 */ 223 int OhCloudExtCloudDbBatchDelete( 224 OhCloudExtCloudDatabase *cdb, 225 const unsigned char *table, 226 unsigned int tableLen, 227 const OhCloudExtVector *extend 228 ); 229 230 /** 231 * @brief Query info that will passed to CloudDatabase. 232 */ 233 typedef struct { 234 const unsigned char *table; 235 const unsigned int tableLen; 236 const unsigned char *cursor; 237 const unsigned int cursorLen; 238 } OhCloudExtQueryInfo; 239 240 /** 241 * @brief Search batches of value buckets from a CloudDatabase instance. 242 * @param cdb [IN] 243 * table [IN] 244 * tableLen [IN] 245 * cursor [IN] 246 * cursorLen [IN] 247 * out [OUT] The address of a pointer to a Cursor. The pointer value will be updated when 248 * query function successfully returns. 249 * @attention The CloudDbData returned should be freed by `OhCloudExtCloudDbDataFree` if no longer in use. 250 */ 251 int OhCloudExtCloudDbBatchQuery( 252 OhCloudExtCloudDatabase *cdb, 253 const OhCloudExtQueryInfo *info, 254 OhCloudExtCloudDbData **out 255 ); 256 257 /** 258 * @brief Lock a CloudDatabase instance. 259 * @param cdb [IN] 260 * expire [OUT] 261 */ 262 int OhCloudExtCloudDbLock(OhCloudExtCloudDatabase *cdb, int *expire); 263 264 /** 265 * @brief Unlock a CloudDatabase instance. 266 * @param cdb [IN] 267 */ 268 int OhCloudExtCloudDbUnlock(OhCloudExtCloudDatabase *cdb); 269 270 /** 271 * @brief Heartbeat function of a CloudDatabase. Extend the current locking session. 272 * @param cdb [IN] 273 */ 274 int OhCloudExtCloudDbHeartbeat(OhCloudExtCloudDatabase *cdb); 275 276 /** 277 * @brief Destroy an CloudDatabase instance. 278 * @param ptr [IN] The pointer of CloudDatabase that should be destroyed. 279 */ 280 void OhCloudExtCloudDbFree(OhCloudExtCloudDatabase *ptr); 281 282 /** 283 * @brief Type declaration of Rust cloud extension struct CloudSync. 284 * @attention When an instance is created by CloudSyncNew，memory is managed by Rust and it will return a pointer. 285 * When destroying this instance, users should call CloudSyncFree to release memory and prevent leak. 286 */ 287 typedef struct { 288 const size_t id; 289 } OhCloudExtCloudSync; 290 291 /** 292 * @brief Create an CloudSync instance. 293 * @param userId [IN] 294 * @retval != NULL, a valid pointer of CloudSync. 295 */ 296 OhCloudExtCloudSync *OhCloudExtCloudSyncNew(int userId); 297 298 /** 299 * @brief Get service info from a CloudSync pointer. 300 * @param server [IN] 301 * info [OUT] 302 * @attention The CloudInfo returned should be freed by `CloudInfoFree` if no longer in use. 303 */ 304 int OhCloudExtCloudSyncGetServiceInfo(OhCloudExtCloudSync *server, OhCloudExtCloudInfo **info); 305 306 /** 307 * @brief Get app schema from a CloudSync pointer, with a bundle name. 308 * @param server [IN] 309 * bundleName [IN] 310 * bundleNameLen [IN] 311 * schema [OUT] 312 * @attention The SchemaMeta returned should be freed by `SchemaMetaFree` if no longer in use. 313 */ 314 int OhCloudExtCloudSyncGetAppSchema( 315 OhCloudExtCloudSync *server, 316 const unsigned char *bundleName, 317 unsigned int bundleNameLen, 318 OhCloudExtSchemaMeta **schema 319 ); 320 321 /** 322 * @brief Pass a batch of subscription orders to a CloudSync pointer, with target database information 323 * and expected expire time. 324 * @param server [IN] 325 * dbs [IN] HashMap<String, Vec<Databases>>, bundle name as key 326 * relations [OUT] HashMap<String, RelationSet>, bundle name as key 327 * err [OUT] Vec<I32> 328 * @attention The Vector returned should be freed by `OhCloudExtVectorFree`. Similar for the HashMap. 329 */ 330 int OhCloudExtCloudSyncSubscribe( 331 OhCloudExtCloudSync *server, 332 const OhCloudExtHashMap *dbs, 333 unsigned long long expire, 334 OhCloudExtHashMap **relations, 335 OhCloudExtVector **err 336 ); 337 338 /** 339 * @brief Pass a batch of unsubscription orders to a CloudSync pointer, with target relations. 340 * @param server [IN] 341 * relations [IN] HashMap<String, Vec<String>>, bundle name as key, ids as value 342 * err [OUT] Vec<I32> 343 * @attention The Vector returned should be freed by `OhCloudExtVectorFree`. 344 */ 345 int OhCloudExtCloudSyncUnsubscribe( 346 OhCloudExtCloudSync *server, 347 const OhCloudExtHashMap *relations, 348 OhCloudExtVector **err 349 ); 350 351 /** 352 * @brief Destroy an CloudSync instance. 353 * @param ptr [IN] The pointer of CloudSync that should be destroyed. 354 */ 355 void OhCloudExtCloudSyncFree(OhCloudExtCloudSync *ptr); 356 357 #ifdef __cplusplus 358 #if __cplusplus 359 } 360 #endif 361 #endif 362 363 364 #endif // CLOUD_EXTENSION_H