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