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 * @addtogroup RDB 18 * @{ 19 * 20 * @brief The relational database (RDB) store manages data based on relational models. 21 * With the underlying SQLite database, the RDB store provides a complete mechanism for managing local databases. 22 * To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations 23 * such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. 24 * 25 * @since 10 26 */ 27 28 /** 29 * @file relational_store.h 30 * 31 * @brief Provides database related functions and enumerations. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * @since 10 37 */ 38 39 #ifndef RELATIONAL_STORE_H 40 #define RELATIONAL_STORE_H 41 42 #include "database/rdb/oh_cursor.h" 43 #include "database/rdb/oh_predicates.h" 44 #include "database/rdb/oh_value_object.h" 45 #include "database/rdb/oh_values_bucket.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Describe the security level of the database. 53 * 54 * @since 10 55 */ 56 typedef enum OH_Rdb_SecurityLevel { 57 /** 58 * @brief Low-level security. Data leaks have a minor impact. 59 */ 60 S1 = 1, 61 /** 62 * @brief Medium-level security. Data leaks have a major impact. 63 */ 64 S2, 65 /** 66 * @brief High-level security. Data leaks have a severe impact. 67 */ 68 S3, 69 /** 70 * @brief Critical-level security. Data leaks have a critical impact. 71 */ 72 S4 73 } OH_Rdb_SecurityLevel; 74 75 /** 76 * @brief Describe the security area of the database. 77 * 78 * @since 11 79 */ 80 typedef enum Rdb_SecurityArea { 81 /** 82 * @brief Security Area 1. 83 */ 84 RDB_SECURITY_AREA_EL1 = 1, 85 /** 86 * @brief Security Area 2. 87 */ 88 RDB_SECURITY_AREA_EL2, 89 /** 90 * @brief Security Area 3. 91 */ 92 RDB_SECURITY_AREA_EL3, 93 /** 94 * @brief Security Area 4. 95 */ 96 RDB_SECURITY_AREA_EL4, 97 98 /** 99 * @brief Security Area 5. 100 * 101 * @since 12 102 */ 103 RDB_SECURITY_AREA_EL5, 104 } Rdb_SecurityArea; 105 106 /** 107 * @brief Manages relational database configurations. 108 * @since 10 109 */ 110 #pragma pack(1) 111 typedef struct { 112 /** 113 * Indicates the size of the {@link OH_Rdb_Config}. It is mandatory. 114 */ 115 int selfSize; 116 /** 117 * Indicates the directory of the database. 118 */ 119 const char *dataBaseDir; 120 /** 121 * Indicates the name of the database. 122 */ 123 const char *storeName; 124 /** 125 * Indicates the bundle name of the application. 126 */ 127 const char *bundleName; 128 /** 129 * Indicates the module name of the application. 130 */ 131 const char *moduleName; 132 /** 133 * Indicates whether the database is encrypted. 134 */ 135 bool isEncrypt; 136 /** 137 * Indicates the security level {@link OH_Rdb_SecurityLevel} of the database. 138 */ 139 int securityLevel; 140 /** 141 * Indicates the security area {@link Rdb_SecurityArea} of the database. 142 * 143 * @since 11 144 */ 145 int area; 146 } OH_Rdb_Config; 147 #pragma pack() 148 149 /** 150 * @brief Define OH_Rdb_Store type. 151 * 152 * @since 10 153 */ 154 typedef struct { 155 /** 156 * The id used to uniquely identify the OH_Rdb_Store struct. 157 */ 158 int64_t id; 159 } OH_Rdb_Store; 160 161 /** 162 * @brief Define OH_Rdb_ConfigV2 type. 163 * 164 * @since 14 165 */ 166 typedef struct OH_Rdb_ConfigV2 OH_Rdb_ConfigV2; 167 168 /** 169 * @brief Define Rdb_DBType type. 170 * 171 * @since 14 172 */ 173 typedef enum Rdb_DBType { 174 /** 175 * @brief Means using SQLITE as the db kernal 176 */ 177 RDB_SQLITE = 1, 178 /** 179 * @brief Means using CARLEY_DB as the db kernal 180 */ 181 RDB_CAYLEY = 2, 182 /** 183 * @brief Means largest value for Rdb_DBType 184 */ 185 DBTYPE_BUTT = 64, 186 } Rdb_DBType; 187 188 /** 189 * @brief Create OH_Rdb_ConfigV2 which is used to open store 190 * 191 * @return Returns the newly created OH_Rdb_ConfigV2 object. If NULL is returned, the creation fails. 192 * The possible cause is that the address space of the application is full, As a result, the space 193 * cannot be allocated. 194 * @see OH_Rdb_ConfigV2 195 * @since 14 196 */ 197 OH_Rdb_ConfigV2 *OH_Rdb_CreateConfig(); 198 199 /** 200 * @brief Destroy OH_Rdb_ConfigV2 which is created by OH_Rdb_CreateConfig 201 * 202 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 203 * Indicates the configuration of the database related to this RDB store. 204 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 205 * {@link RDB_OK} - success. 206 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 207 * @since 14 208 */ 209 int OH_Rdb_DestroyConfig(OH_Rdb_ConfigV2 *config); 210 211 /** 212 * @brief Set property databaseDir into config 213 * 214 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 215 * Indicates the configuration of the database related to this RDB store. 216 * @param databaseDir Indicates the directory of the database. 217 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 218 * {@link RDB_OK} - success. 219 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 220 * @since 14 221 */ 222 int OH_Rdb_SetDatabaseDir(OH_Rdb_ConfigV2 *config, const char *databaseDir); 223 224 /** 225 * @brief Set property storeName into config 226 * 227 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 228 * Indicates the configuration of the database related to this RDB store. 229 * @param storeName Indicates the name of the database. 230 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 231 * {@link RDB_OK} - success. 232 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 233 * @since 14 234 */ 235 int OH_Rdb_SetStoreName(OH_Rdb_ConfigV2 *config, const char *storeName); 236 237 /** 238 * @brief Set property bundleName into config 239 * 240 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 241 * Indicates the configuration of the database related to this RDB store. 242 * @param bundleName Indicates the bundle name of the application 243 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 244 * {@link RDB_OK} - success. 245 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 246 * @since 14 247 */ 248 int OH_Rdb_SetBundleName(OH_Rdb_ConfigV2 *config, const char *bundleName); 249 250 /** 251 * @brief Set property moduleName into config 252 * 253 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 254 * Indicates the configuration of the database related to this RDB store. 255 * @param moduleName Indicates the module name of the application. 256 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 257 * {@link RDB_OK} - success. 258 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 259 * @since 14 260 */ 261 int OH_Rdb_SetModuleName(OH_Rdb_ConfigV2 *config, const char *moduleName); 262 263 /** 264 * @brief Set property isEncrypted into config 265 * 266 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 267 * Indicates the configuration of the database related to this RDB store. 268 * @param isEncrypted Indicates whether the database is encrypted. 269 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 270 * {@link RDB_OK} - success. 271 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 272 * @since 14 273 */ 274 int OH_Rdb_SetEncrypted(OH_Rdb_ConfigV2 *config, bool isEncrypted); 275 276 /** 277 * @brief Set property securityLevel into config 278 * 279 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 280 * Indicates the configuration of the database related to this RDB store. 281 * @param securityLevel Indicates the security level {@link OH_Rdb_SecurityLevel} of the database. 282 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 283 * {@link RDB_OK} - success. 284 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 285 * @since 14 286 */ 287 int OH_Rdb_SetSecurityLevel(OH_Rdb_ConfigV2 *config, int securityLevel); 288 289 /** 290 * @brief Set property area into config 291 * 292 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 293 * Indicates the configuration of the database related to this RDB store 294 * @param area Represents the security area of the database. 295 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 296 * {@link RDB_OK} - success. 297 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 298 * @since 14 299 */ 300 int OH_Rdb_SetArea(OH_Rdb_ConfigV2 *config, int area); 301 302 /** 303 * @brief Set property dbType into config 304 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 305 * @param dbType Indicates the dbType {@link Rdb_DBType} of the database 306 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 307 * {@link RDB_OK} - success. 308 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 309 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support db types. 310 * @since 14 311 */ 312 int OH_Rdb_SetDbType(OH_Rdb_ConfigV2 *config, int dbType); 313 314 /** 315 * @brief Get support db type list 316 * @param typeCount The output parameter, which is used to recieve the length of the support db type array. 317 * @return Return Rdb_DBType array contains supported db type, array length is number of support type 318 * @since 14 319 */ 320 const int *OH_Rdb_GetSupportedDbType(int *typeCount); 321 322 /** 323 * @brief Creates an {@link OH_VObject} instance. 324 * 325 * @return If the creation is successful, a pointer to the instance of the @link OH_VObject} structure is returned, 326 * otherwise NULL is returned. 327 * @see OH_VObject. 328 * @since 10 329 */ 330 OH_VObject *OH_Rdb_CreateValueObject(); 331 332 /** 333 * @brief Creates an {@link OH_VBucket} object. 334 * 335 * @return If the creation is successful, a pointer to the instance of the @link OH_VBucket} structure is returned, 336 * otherwise NULL is returned. 337 * @see OH_VBucket. 338 * @since 10 339 */ 340 OH_VBucket *OH_Rdb_CreateValuesBucket(); 341 342 /** 343 * @brief Creates an {@link OH_Predicates} instance. 344 * 345 * @param table Indicates the table name. 346 * @return If the creation is successful, a pointer to the instance of the @link OH_Predicates} structure is returned. 347 * If the table name is nullptr, Nullptr is returned. 348 * @see OH_Predicates. 349 * @since 10 350 */ 351 OH_Predicates *OH_Rdb_CreatePredicates(const char *table); 352 353 /** 354 * @brief Obtains an RDB store. 355 * 356 * You can set parameters of the RDB store as required. In general, 357 * this method is recommended to obtain a rdb store. 358 * 359 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 360 * Indicates the configuration of the database related to this RDB store. 361 * @param errCode This parameter is the output parameter, 362 * and the execution status of a function is written to this variable. 363 * @return If the creation is successful, a pointer to the instance of the @link OH_Rdb_Store} structure is returned. 364 * If the Config is empty, config.size does not match, or errCode is empty. 365 * Get database path failed.Get RDB Store fail. Nullptr is returned. 366 * @see OH_Rdb_Config, OH_Rdb_Store. 367 * @since 10 368 */ 369 OH_Rdb_Store *OH_Rdb_GetOrOpen(const OH_Rdb_Config *config, int *errCode); 370 371 /** 372 * @brief Obtains an RDB store with OH_Rdb_ConfigV2. 373 * 374 * You can set parameters of the RDB store as required. In general, 375 * this method is recommended to obtain a rdb store. 376 * 377 * @param config Represents a pointer to an {@link OH_Rdb_ConfigV2} instance. 378 * Indicates the configuration of the database related to this RDB store. 379 * @param errCode This parameter is the output parameter, 380 * and the execution status of a function is written to this variable. 381 * @return If the creation is successful, a pointer to the instance of the @link OH_Rdb_Store} structure is returned. 382 * If the Config is empty, config.size does not match, or errCode is empty. 383 * Get database path failed.Get RDB Store fail. Nullptr is returned. 384 * @see OH_Rdb_ConfigV2, OH_Rdb_Store. 385 * @since 14 386 */ 387 OH_Rdb_Store *OH_Rdb_CreateOrOpen(const OH_Rdb_ConfigV2 *config, int *errCode); 388 389 /** 390 * @brief Close the {@link OH_Rdb_Store} object and reclaim the memory occupied by the object. 391 * 392 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 393 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 394 * {@link RDB_OK} - success. 395 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 396 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 397 * @see OH_Rdb_Store, OH_Rdb_ErrCode. 398 * @since 10 399 */ 400 int OH_Rdb_CloseStore(OH_Rdb_Store *store); 401 402 /** 403 * @brief Deletes the database with a specified path. 404 * 405 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 406 * Indicates the configuration of the database related to this RDB store. 407 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 408 * {@link RDB_OK} - success. 409 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 410 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 411 * @see OH_Rdb_ErrCode. 412 * @since 10 413 */ 414 int OH_Rdb_DeleteStore(const OH_Rdb_Config *config); 415 416 /** 417 * @brief Deletes the database with a specified path. 418 * 419 * @param config Represents a pointer to an {@link OH_Rdb_ConfigV2} instance. 420 * Indicates the configuration of the database related to this RDB store. 421 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 422 * {@link RDB_OK} - success. 423 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 424 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 425 * @see OH_Rdb_ErrCode. 426 * @since 14 427 */ 428 int OH_Rdb_DeleteStoreV2(const OH_Rdb_ConfigV2 *config); 429 430 /** 431 * @brief Inserts a row of data into the target table. 432 * 433 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 434 * @param table Indicates the target table. 435 * @param valuesBucket Indicates the row of data {@link OH_VBucket} to be inserted into the table. 436 * @return Returns the rowId if success, returns a specific error code. 437 * {@link RDB_ERR} - Indicates that the function execution exception. 438 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 439 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 440 * @see OH_Rdb_Store, OH_VBucket, OH_Rdb_ErrCode. 441 * @since 10 442 */ 443 int OH_Rdb_Insert(OH_Rdb_Store *store, const char *table, OH_VBucket *valuesBucket); 444 445 /** 446 * @brief Updates data in the database based on specified conditions. 447 * 448 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 449 * @param valuesBucket Indicates the row of data {@link OH__VBucket} to be updated in the database 450 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 451 * Indicates the specified update condition. 452 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 453 * {@link RDB_ERR} - Indicates that the function execution exception. 454 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 455 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 456 * @see OH_Rdb_Store, OH_Bucket, OH_Predicates, OH_Rdb_ErrCode. 457 * @since 10 458 */ 459 int OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates); 460 461 /** 462 * @brief Deletes data from the database based on specified conditions. 463 * 464 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 465 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 466 * Indicates the specified delete condition. 467 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 468 * {@link RDB_ERR} - Indicates that the function execution exception. 469 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 470 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 471 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 472 * @since 10 473 */ 474 int OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates); 475 476 /** 477 * @brief Queries data in the database based on specified conditions. 478 * 479 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 480 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 481 * Indicates the specified query condition. 482 * @param columnNames Indicates the columns to query. If the value is empty array, the query applies to all columns. 483 * @param length Indicates the length of columnNames. 484 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 485 * If Get store failed or resultSet is nullptr, nullptr is returned. 486 * @see OH_Rdb_Store, OH_Predicates, OH_Cursor. 487 * @since 10 488 */ 489 OH_Cursor *OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length); 490 491 /** 492 * @brief Executes an SQL statement. 493 * 494 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 495 * @param sql Indicates the SQL statement to execute. 496 * @return Returns the status code of the execution. 497 * {@link RDB_OK} - success. 498 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 499 * @see OH_Rdb_Store. 500 * @since 10 501 */ 502 int OH_Rdb_Execute(OH_Rdb_Store *store, const char *sql); 503 504 /** 505 * @brief Write operations are performed using the specified transaction represented by the transaction ID 506 * 507 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 508 * @param trxId The transaction ID of the specified transaction, must be greater than 0 509 * @param sql Indicates the SQL statement to execute. 510 * @return Returns the status code of the execution. 511 * {@link RDB_OK} - success. 512 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 513 * {@link RDB_E_NOT_SUPPORTED} - The error code for not supprt. 514 * @see OH_Rdb_Store. 515 * @since 14 516 */ 517 int OH_Rdb_ExecuteByTrxId(OH_Rdb_Store *store, int64_t trxId, const char *sql); 518 519 /** 520 * @brief Queries data in the database based on an SQL statement. 521 * 522 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 523 * @param sql Indicates the SQL statement to execute. 524 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 525 * If Get store failed,sql is nullptr or resultSet is nullptr, nullptr is returned. 526 * @see OH_Rdb_Store. 527 * @since 10 528 */ 529 OH_Cursor *OH_Rdb_ExecuteQuery(OH_Rdb_Store *store, const char *sql); 530 531 /** 532 * @brief Begins a transaction in EXCLUSIVE mode. 533 * 534 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 535 * @return Returns the status code of the execution. 536 * {@link RDB_OK} - success. 537 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 538 * @see OH_Rdb_Store. 539 * @since 10 540 */ 541 int OH_Rdb_BeginTransaction(OH_Rdb_Store *store); 542 543 /** 544 * @brief Rolls back a transaction in EXCLUSIVE mode. 545 * 546 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 547 * @return Returns the status code of the execution. 548 * {@link RDB_OK} - success. 549 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 550 * @see OH_Rdb_Store. 551 * @since 10 552 */ 553 int OH_Rdb_RollBack(OH_Rdb_Store *store); 554 555 /** 556 * @brief Commits a transaction in EXCLUSIVE mode. 557 * 558 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 559 * @return Returns the status code of the execution. 560 * {@link RDB_OK} - success. 561 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 562 * @see OH_Rdb_Store. 563 * @since 10 564 */ 565 int OH_Rdb_Commit(OH_Rdb_Store *store); 566 567 /** 568 * @brief Begin a transaction and the transaction ID corresponding to the transaction. 569 * 570 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 571 * @param trxId The output parameter, which is used to receive the transaction ID corresponding to the transaction 572 * @return Returns the status code of the execution. 573 * {@link RDB_OK} - success. 574 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 575 * {@link RDB_E_NOT_SUPPORTED} - The error code for not supprt. 576 * @see OH_Rdb_Store. 577 * @since 14 578 */ 579 int OH_Rdb_BeginTransWithTrxId(OH_Rdb_Store *store, int64_t *trxId); 580 581 /** 582 * @brief Roll back a transaction that is represented by a specified transaction ID 583 * 584 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 585 * @param trxId The transaction ID of the specified transaction, must be greater than 0 586 * @return Returns the status code of the execution. 587 * {@link RDB_OK} - success. 588 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 589 * {@link RDB_E_NOT_SUPPORTED} - The error code for not supprt. 590 * @see OH_Rdb_Store. 591 * @since 14 592 */ 593 int OH_Rdb_RollBackByTrxId(OH_Rdb_Store *store, int64_t trxId); 594 595 /** 596 * @brief Commit a transaction that is represented by a specified transaction ID 597 * 598 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 599 * @param trxId The transaction ID of the specified transaction, must be greater than 0 600 * @return Returns the status code of the execution. 601 * {@link RDB_OK} - success. 602 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 603 * {@link RDB_E_NOT_SUPPORTED} - The error code for not supprt. 604 * @see OH_Rdb_Store. 605 * @since 14 606 */ 607 int OH_Rdb_CommitByTrxId(OH_Rdb_Store *store, int64_t trxId); 608 609 /** 610 * @brief Backs up a database on specified path. 611 * 612 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 613 * @param databasePath Indicates the database file path. 614 * @return Returns the status code of the execution. 615 * {@link RDB_OK} - success. 616 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 617 * @see OH_Rdb_Store. 618 * @since 10 619 */ 620 int OH_Rdb_Backup(OH_Rdb_Store *store, const char *databasePath); 621 622 /** 623 * @brief Restores a database from a specified database file. 624 * 625 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 626 * @param databasePath Indicates the database file path. 627 * @return Returns the status code of the execution. 628 * {@link RDB_OK} - success. 629 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 630 * @see OH_Rdb_Store. 631 * @since 10 632 */ 633 int OH_Rdb_Restore(OH_Rdb_Store *store, const char *databasePath); 634 635 /** 636 * @brief Gets the version of a database. 637 * 638 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 639 * @param version Indicates the version number. 640 * @return Returns the status code of the execution. 641 * {@link RDB_OK} - success. 642 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 643 * @see OH_Rdb_Store. 644 * @since 10 645 */ 646 int OH_Rdb_GetVersion(OH_Rdb_Store *store, int *version); 647 648 /** 649 * @brief Sets the version of a database. 650 * 651 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 652 * @param version Indicates the version number. 653 * @return Returns the status code of the execution. 654 * {@link RDB_OK} - success. 655 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 656 * @see OH_Rdb_Store. 657 * @since 10 658 */ 659 int OH_Rdb_SetVersion(OH_Rdb_Store *store, int version); 660 661 /** 662 * @brief Describes the distribution type of the tables. 663 * 664 * @since 11 665 */ 666 typedef enum Rdb_DistributedType { 667 /** 668 * @brief Indicates the table is distributed among the devices. 669 */ 670 RDB_DISTRIBUTED_CLOUD 671 } Rdb_DistributedType; 672 673 /** 674 * @brief Indicates version of {@link Rdb_DistributedConfig} 675 * 676 * @since 11 677 */ 678 #define DISTRIBUTED_CONFIG_VERSION 1 679 /** 680 * @brief Manages the distributed configuration of the table. 681 * 682 * @since 11 683 */ 684 typedef struct Rdb_DistributedConfig { 685 /** 686 * The version used to uniquely identify the Rdb_DistributedConfig struct. 687 */ 688 int version; 689 /** 690 * Specifies whether the table auto syncs. 691 */ 692 bool isAutoSync; 693 } Rdb_DistributedConfig; 694 695 /** 696 * @brief Set table to be distributed table. 697 * 698 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 699 * @param tables Indicates the table names you want to set. 700 * @param count Indicates the count of tables you want to set. 701 * @param type Indicates the distributed type {@link Rdb_DistributedType}. 702 * @param config Indicates the distributed config of the tables. For details, see {@link Rdb_DistributedConfig}. 703 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 704 * {@link RDB_OK} - success. 705 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 706 * @see OH_Rdb_Store. 707 * @see Rdb_DistributedConfig. 708 * @since 11 709 */ 710 int OH_Rdb_SetDistributedTables(OH_Rdb_Store *store, const char *tables[], uint32_t count, Rdb_DistributedType type, 711 const Rdb_DistributedConfig *config); 712 713 /** 714 * @brief Set table to be distributed table. 715 * 716 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 717 * @param tableName Indicates the name of the table to check. 718 * @param columnName Indicates the name of the column corresponding to the primary key. 719 * If the table has no primary key , please pass in "rowid". 720 * @param values Indicates the primary keys of the rows to check. 721 * If the table has no primary key , please pass in the row-ids of the rows to check. 722 * @return If the operation is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 723 * If Get store failed, NULL is returned. 724 * There are two columns, "data_key" and "timestamp". Otherwise NULL is returned. 725 * @see OH_Rdb_Store. 726 * @see OH_VObject. 727 * @see OH_Cursor. 728 * @since 11 729 */ 730 OH_Cursor *OH_Rdb_FindModifyTime(OH_Rdb_Store *store, const char *tableName, const char *columnName, 731 OH_VObject *values); 732 733 /** 734 * @brief Describes the change type. 735 * 736 * @since 11 737 */ 738 typedef enum Rdb_ChangeType { 739 /** 740 * @brief Means the change type is data change. 741 */ 742 RDB_DATA_CHANGE, 743 /** 744 * @brief Means the change type is asset change. 745 */ 746 RDB_ASSET_CHANGE 747 } Rdb_ChangeType; 748 749 /** 750 * @brief Describes the primary keys or row-ids of changed rows. 751 * 752 * @since 11 753 */ 754 typedef struct Rdb_KeyInfo { 755 /** 756 * Indicates the count of the primary keys or row-ids. 757 */ 758 int count; 759 760 /** 761 * Indicates data type {@link OH_ColumnType} of the key. 762 */ 763 int type; 764 765 /** 766 * Indicates the data of the key info. 767 */ 768 union Rdb_KeyData { 769 /** 770 * Indicates uint64_t type of the data. 771 */ 772 uint64_t integer; 773 774 /** 775 * Indicates double type of the data. 776 */ 777 double real; 778 779 /** 780 * Indicates const char * type of the data. 781 */ 782 const char *text; 783 } *data; 784 } Rdb_KeyInfo; 785 786 /** 787 * @brief Indicates version of {@link Rdb_ChangeInfo} 788 * 789 * @since 11 790 */ 791 #define DISTRIBUTED_CHANGE_INFO_VERSION 1 792 793 /** 794 * @brief Describes the notify info of data change. 795 * 796 * @since 11 797 */ 798 typedef struct Rdb_ChangeInfo { 799 /** 800 * The version used to uniquely identify the Rdb_ChangeInfo struct. 801 */ 802 int version; 803 804 /** 805 * The name of changed table. 806 */ 807 const char *tableName; 808 809 /** 810 * The {@link Rdb_ChangeType} of changed table. 811 */ 812 int ChangeType; 813 814 /** 815 * The {@link Rdb_KeyInfo} of inserted rows. 816 */ 817 Rdb_KeyInfo inserted; 818 819 /** 820 * The {@link Rdb_KeyInfo} of updated rows. 821 */ 822 Rdb_KeyInfo updated; 823 824 /** 825 * The {@link Rdb_KeyInfo} of deleted rows. 826 */ 827 Rdb_KeyInfo deleted; 828 } Rdb_ChangeInfo; 829 830 /** 831 * @brief Indicates the subscribe type. 832 * 833 * @since 11 834 */ 835 typedef enum Rdb_SubscribeType { 836 /** 837 * @brief Subscription to cloud data changes. 838 */ 839 RDB_SUBSCRIBE_TYPE_CLOUD, 840 841 /** 842 * @brief Subscription to cloud data change details. 843 */ 844 RDB_SUBSCRIBE_TYPE_CLOUD_DETAILS, 845 846 /** 847 * @brief Subscription to local data change details. 848 * @since 12 849 */ 850 RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, 851 } Rdb_SubscribeType; 852 853 /** 854 * @brief The callback function of cloud data change event. 855 * 856 * @param context Represents the context of data observer. 857 * @param values Indicates the cloud accounts that changed. 858 * @param count The count of changed cloud accounts. 859 * @since 11 860 */ 861 typedef void (*Rdb_BriefObserver)(void *context, const char *values[], uint32_t count); 862 863 /** 864 * @brief The callback function of cloud data change details event. 865 * 866 * @param context Represents the context of data observer. 867 * @param changeInfo Indicates the {@link Rdb_ChangeInfo} of changed tables. 868 * @param count The count of changed tables. 869 * @see Rdb_ChangeInfo. 870 * @since 11 871 */ 872 typedef void (*Rdb_DetailsObserver)(void *context, const Rdb_ChangeInfo **changeInfo, uint32_t count); 873 874 /** 875 * @brief Indicates the callback functions. 876 * 877 * @since 11 878 */ 879 typedef union Rdb_SubscribeCallback { 880 /** 881 * The callback function of cloud data change details event. 882 */ 883 Rdb_DetailsObserver detailsObserver; 884 885 /** 886 * The callback function of cloud data change event. 887 */ 888 Rdb_BriefObserver briefObserver; 889 } Rdb_SubscribeCallback; 890 891 /** 892 * @brief Indicates the observer of data. 893 * 894 * @since 11 895 */ 896 typedef struct Rdb_DataObserver { 897 /** 898 * The context of data observer. 899 */ 900 void *context; 901 902 /** 903 * The callback of data observer. 904 */ 905 Rdb_SubscribeCallback callback; 906 } Rdb_DataObserver; 907 908 /** 909 * @brief Registers an observer for the database. 910 * When data in the distributed database or the local database changes, the callback will be invoked. 911 * 912 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 913 * @param type Indicates the subscription type, which is defined in {@link Rdb_SubscribeType}. 914 * If its value is RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, the callback will be invoked for data changes 915 * in the local database. 916 * @param observer The {@link Rdb_DataObserver} of change events in the database. 917 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 918 * {@link RDB_OK} - success. 919 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 920 * @see OH_Rdb_Store. 921 * @see Rdb_DataObserver. 922 * @since 11 923 */ 924 int OH_Rdb_Subscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer); 925 926 /** 927 * @brief Remove specified observer of specified type from the database. 928 * 929 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 930 * @param type Indicates the subscription type, which is defined in {@link Rdb_SubscribeType}. 931 * @param observer The {@link Rdb_DataObserver} of change events in the database. 932 * If this is nullptr, remove all observers of the type. 933 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 934 * {@link RDB_OK} - success. 935 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 936 * @see OH_Rdb_Store. 937 * @see Rdb_DataObserver. 938 * @since 11 939 */ 940 int OH_Rdb_Unsubscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer); 941 942 /** 943 * @brief Indicates the database synchronization mode. 944 * 945 * @since 11 946 */ 947 typedef enum Rdb_SyncMode { 948 /** 949 * @brief Indicates that data is synchronized from the end with the closest modification time 950 * to the end with a more distant modification time. 951 */ 952 RDB_SYNC_MODE_TIME_FIRST, 953 /** 954 * @brief Indicates that data is synchronized from local to cloud. 955 */ 956 RDB_SYNC_MODE_NATIVE_FIRST, 957 /** 958 * @brief Indicates that data is synchronized from cloud to local. 959 */ 960 RDB_SYNC_MODE_CLOUD_FIRST 961 } Rdb_SyncMode; 962 963 /** 964 * @brief Describes the statistic of the cloud sync process. 965 * 966 * @since 11 967 */ 968 typedef struct Rdb_Statistic { 969 /** 970 * Describes the total number of data to sync. 971 */ 972 int total; 973 974 /** 975 * Describes the number of successfully synced data. 976 */ 977 int successful; 978 979 /** 980 * Describes the number of data failed to sync. 981 */ 982 int failed; 983 984 /** 985 * Describes the number of data remained to sync. 986 */ 987 int remained; 988 } Rdb_Statistic; 989 990 /** 991 * @brief Describes the {@link Rdb_Statistic} details of the table. 992 * 993 * @since 11 994 */ 995 typedef struct Rdb_TableDetails { 996 /** 997 * Indicates the name of changed table. 998 */ 999 const char *table; 1000 1001 /** 1002 * Describes the {@link Rdb_Statistic} details of the upload process. 1003 */ 1004 Rdb_Statistic upload; 1005 1006 /** 1007 * Describes the {@link Rdb_Statistic} details of the download process. 1008 */ 1009 Rdb_Statistic download; 1010 } Rdb_TableDetails; 1011 1012 /** 1013 * The cloud sync progress 1014 * 1015 * @since 11 1016 */ 1017 typedef enum Rdb_Progress { 1018 /** 1019 * @brief Means the sync process begin. 1020 */ 1021 RDB_SYNC_BEGIN, 1022 1023 /** 1024 * @brief Means the sync process is in progress 1025 */ 1026 RDB_SYNC_IN_PROGRESS, 1027 1028 /** 1029 * @brief Means the sync process is finished 1030 */ 1031 RDB_SYNC_FINISH 1032 } Rdb_Progress; 1033 1034 /** 1035 * Describes the status of cloud sync progress. 1036 * 1037 * @since 11 1038 */ 1039 typedef enum Rdb_ProgressCode { 1040 /** 1041 * @brief Means the status of progress is success. 1042 */ 1043 RDB_SUCCESS, 1044 1045 /** 1046 * @brief Means the progress meets unknown error. 1047 */ 1048 RDB_UNKNOWN_ERROR, 1049 1050 /** 1051 * @brief Means the progress meets network error. 1052 */ 1053 RDB_NETWORK_ERROR, 1054 1055 /** 1056 * @brief Means cloud is disabled. 1057 */ 1058 RDB_CLOUD_DISABLED, 1059 1060 /** 1061 * @brief Means the progress is locked by others. 1062 */ 1063 RDB_LOCKED_BY_OTHERS, 1064 1065 /** 1066 * @brief Means the record exceeds the limit. 1067 */ 1068 RDB_RECORD_LIMIT_EXCEEDED, 1069 1070 /** 1071 * Means the cloud has no space for the asset. 1072 */ 1073 RDB_NO_SPACE_FOR_ASSET 1074 } Rdb_ProgressCode; 1075 1076 /** 1077 * @brief Indicates version of {@link Rdb_ProgressDetails} 1078 * 1079 * @since 11 1080 */ 1081 #define DISTRIBUTED_PROGRESS_DETAIL_VERSION 1 1082 1083 /** 1084 * @brief Describes detail of the cloud sync progress. 1085 * 1086 * @since 11 1087 */ 1088 typedef struct Rdb_ProgressDetails { 1089 /** 1090 * The version used to uniquely identify the Rdb_ProgressDetails struct. 1091 */ 1092 int version; 1093 1094 /** 1095 * Describes the status of data sync progress. Defined in {@link Rdb_Progress}. 1096 */ 1097 int schedule; 1098 1099 /** 1100 * Describes the code of data sync progress. Defined in {@link Rdb_ProgressCode}. 1101 */ 1102 int code; 1103 1104 /** 1105 * Describes the length of changed tables in data sync progress. 1106 */ 1107 int32_t tableLength; 1108 } Rdb_ProgressDetails; 1109 1110 /** 1111 * @brief Get table details from progress details. 1112 * 1113 * @param progress Represents a pointer to an {@link Rdb_ProgressDetails} instance. 1114 * @param version Indicates the version of current {@link Rdb_ProgressDetails}. 1115 * @return If the operation is successful, a pointer to the instance of the {@link Rdb_TableDetails} 1116 * structure is returned.If get details is failed, nullptr is returned. 1117 * @see Rdb_ProgressDetails 1118 * @see Rdb_TableDetails 1119 * @since 11 1120 */ 1121 Rdb_TableDetails *OH_Rdb_GetTableDetails(Rdb_ProgressDetails *progress, int32_t version); 1122 1123 /** 1124 * @brief The callback function of progress. 1125 * 1126 * @param progressDetails The details of the sync progress. 1127 * @see Rdb_ProgressDetails. 1128 * @since 11 1129 */ 1130 typedef void (*Rdb_ProgressCallback)(void *context, Rdb_ProgressDetails *progressDetails); 1131 1132 /** 1133 * @brief The callback function of sync. 1134 * 1135 * @param progressDetails The details of the sync progress. 1136 * @see Rdb_ProgressDetails. 1137 * @since 11 1138 */ 1139 typedef void (*Rdb_SyncCallback)(Rdb_ProgressDetails *progressDetails); 1140 1141 /** 1142 * @brief The observer of progress. 1143 * 1144 * @since 11 1145 */ 1146 typedef struct Rdb_ProgressObserver { 1147 /** 1148 * The context of progress observer. 1149 */ 1150 void *context; 1151 1152 /** 1153 * The callback function of progress observer. 1154 */ 1155 Rdb_ProgressCallback callback; 1156 } Rdb_ProgressObserver; 1157 1158 /** 1159 * @brief Sync data to cloud. 1160 * 1161 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1162 * @param mode Represents the {@link Rdb_SyncMode} of sync progress. 1163 * @param tables Indicates the names of tables to sync. 1164 * @param count The count of tables to sync. If value equals 0, sync all tables of the store. 1165 * @param observer The {@link Rdb_ProgressObserver} of cloud sync progress. 1166 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1167 * {@link RDB_OK} - success. 1168 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1169 * @see OH_Rdb_Store. 1170 * @see Rdb_ProgressObserver. 1171 * @since 11 1172 */ 1173 int OH_Rdb_CloudSync(OH_Rdb_Store *store, Rdb_SyncMode mode, const char *tables[], uint32_t count, 1174 const Rdb_ProgressObserver *observer); 1175 1176 /** 1177 * @brief Subscribes to the automatic synchronization progress of an RDB store. 1178 * A callback will be invoked when there is a notification of the automatic synchronization progress. 1179 * 1180 * @param store Indicates the pointer to the target {@Link OH_Rdb_Store} instance. 1181 * @param observer The {@link Rdb_ProgressObserver} for the automatic synchornizaiton progress. 1182 * Indicates the callback invoked to return the automatic synchronization progress. 1183 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1184 * {@link RDB_OK} - success. 1185 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1186 * @see OH_Rdb_Store. 1187 * @see Rdb_ProgressObserver. 1188 * @since 11 1189 **/ 1190 int OH_Rdb_SubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer); 1191 1192 /** 1193 * @brief Unsubscribes from the automatic synchronziation progress of an RDB store. 1194 * 1195 * @param store Indicates the pointer to the target {@Link OH_Rdb_Store} instance. 1196 * @param observer Indicates the {@link Rdb_ProgressObserver} callback for the automatic synchornizaiton progress. 1197 * If it is a null pointer, all callbacks for the automatic synchornizaiton progress will be unregistered. 1198 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1199 * {@link RDB_OK} - success. 1200 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1201 * @see OH_Rdb_Store. 1202 * @see Rdb_ProgressObserver. 1203 * @since 11 1204 */ 1205 int OH_Rdb_UnsubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer); 1206 1207 /** 1208 * @brief Lock data from the database based on specified conditions. 1209 * 1210 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1211 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1212 * Indicates the specified lock condition. 1213 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1214 * {@link RDB_OK} - success. 1215 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1216 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 1217 * @since 12 1218 */ 1219 int OH_Rdb_LockRow(OH_Rdb_Store *store, OH_Predicates *predicates); 1220 1221 /** 1222 * @brief Unlock data from the database based on specified conditions. 1223 * 1224 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1225 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1226 * Indicates the specified unlock condition. 1227 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1228 * {@link RDB_OK} - success. 1229 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1230 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 1231 * @since 12 1232 */ 1233 int OH_Rdb_UnlockRow(OH_Rdb_Store *store, OH_Predicates *predicates); 1234 1235 /** 1236 * @brief Queries locked data in the database based on specified conditions. 1237 * 1238 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1239 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1240 * Indicates the specified query condition. 1241 * @param columnNames Indicates the columns to query. If the value is empty array, the query applies to all columns. 1242 * @param length Indicates the length of columnNames. 1243 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 1244 * If Get store failed or resultSet is nullptr, nullptr is returned. 1245 * @see OH_Rdb_Store, OH_Predicates, OH_Cursor. 1246 * @since 12 1247 */ 1248 OH_Cursor *OH_Rdb_QueryLockedRow( 1249 OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length); 1250 #ifdef __cplusplus 1251 }; 1252 #endif 1253 1254 /** @} */ 1255 1256 #endif // RELATIONAL_STORE_H