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 * @since 10 38 */ 39 40 #include "oh_cursor.h" 41 #include "oh_predicates.h" 42 #include "oh_value_object.h" 43 #include "oh_values_bucket.h" 44 #include "oh_rdb_transaction.h" 45 #include "oh_rdb_types.h" 46 #include "oh_rdb_crypto_param.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Describe the security level of the database. 54 * 55 * @since 10 56 */ 57 typedef enum OH_Rdb_SecurityLevel { 58 /** 59 * @brief Low-level security. Data leaks have a minor impact. 60 */ 61 S1 = 1, 62 /** 63 * @brief Medium-level security. Data leaks have a major impact. 64 */ 65 S2, 66 /** 67 * @brief High-level security. Data leaks have a severe impact. 68 */ 69 S3, 70 /** 71 * @brief Critical-level security. Data leaks have a critical impact. 72 */ 73 S4 74 } OH_Rdb_SecurityLevel; 75 76 /** 77 * @brief Describe the security area of the database. 78 * 79 * @since 11 80 */ 81 typedef enum Rdb_SecurityArea { 82 /** 83 * @brief Security Area 1. 84 */ 85 RDB_SECURITY_AREA_EL1 = 1, 86 /** 87 * @brief Security Area 2. 88 */ 89 RDB_SECURITY_AREA_EL2, 90 /** 91 * @brief Security Area 3. 92 */ 93 RDB_SECURITY_AREA_EL3, 94 /** 95 * @brief Security Area 4. 96 */ 97 RDB_SECURITY_AREA_EL4, 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 * 109 * @since 10 110 */ 111 #pragma pack(1) 112 typedef struct { 113 /** 114 * Indicates the size of the {@link OH_Rdb_Config}. It is mandatory. 115 */ 116 int selfSize; 117 /** 118 * Indicates the directory of the database. 119 */ 120 const char *dataBaseDir; 121 /** 122 * Indicates the name of the database. 123 */ 124 const char *storeName; 125 /** 126 * Indicates the bundle name of the application. 127 */ 128 const char *bundleName; 129 /** 130 * Indicates the module name of the application. 131 */ 132 const char *moduleName; 133 /** 134 * Indicates whether the database is encrypted. 135 */ 136 bool isEncrypt; 137 /** 138 * Indicates the security level {@link OH_Rdb_SecurityLevel} of the database. 139 */ 140 int securityLevel; 141 /** 142 * Indicates the security area {@link Rdb_SecurityArea} of the database. 143 * 144 * @since 11 145 */ 146 int area; 147 } OH_Rdb_Config; 148 #pragma pack() 149 150 /** 151 * @brief Define OH_Rdb_Store type. 152 * 153 * @since 10 154 */ 155 typedef struct { 156 /** 157 * The id used to uniquely identify the OH_Rdb_Store struct. 158 */ 159 int64_t id; 160 } OH_Rdb_Store; 161 162 /** 163 * @brief Define OH_Rdb_ConfigV2 type. 164 * 165 * @since 14 166 */ 167 typedef struct OH_Rdb_ConfigV2 OH_Rdb_ConfigV2; 168 169 /** 170 * @brief Define Rdb_DBType type. 171 * 172 * @since 14 173 */ 174 typedef enum Rdb_DBType { 175 /** 176 * @brief Means using SQLITE as the db kernal 177 */ 178 RDB_SQLITE = 1, 179 /** 180 * @brief Means using CARLEY_DB as the db kernal 181 */ 182 RDB_CAYLEY = 2, 183 /** 184 * @brief Means largest value for Rdb_DBType 185 */ 186 DBTYPE_BUTT = 64, 187 } Rdb_DBType; 188 189 /** 190 * @brief Define Rdb_Tokenizer type. 191 * 192 * @since 16 193 */ 194 typedef enum Rdb_Tokenizer { 195 /** 196 * @brief Means not using tokenizer. 197 */ 198 RDB_NONE_TOKENIZER = 1, 199 /** 200 * @brief Means using native icu tokenizer. 201 */ 202 RDB_ICU_TOKENIZER = 2, 203 /** 204 * @brief Means using self-developed enhance tokenizer. 205 */ 206 RDB_CUSTOM_TOKENIZER = 3, 207 } Rdb_Tokenizer; 208 209 /** 210 * @brief Create OH_Rdb_ConfigV2 which is used to open store 211 * 212 * @return Returns the newly created OH_Rdb_ConfigV2 object. If NULL is returned, the creation fails. 213 * The possible cause is that the address space of the application is full, As a result, the space 214 * cannot be allocated. 215 * @see OH_Rdb_ConfigV2 216 * @since 14 217 */ 218 OH_Rdb_ConfigV2 *OH_Rdb_CreateConfig(); 219 220 /** 221 * @brief Destroy OH_Rdb_ConfigV2 which is created by OH_Rdb_CreateConfig 222 * 223 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 224 * Indicates the configuration of the database related to this RDB store. 225 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 226 * {@link RDB_OK} - success. 227 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 228 * @since 14 229 */ 230 int OH_Rdb_DestroyConfig(OH_Rdb_ConfigV2 *config); 231 232 /** 233 * @brief Set property databaseDir into config 234 * 235 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 236 * Indicates the configuration of the database related to this RDB store. 237 * @param dataBaseDir Indicates the directory of the database. 238 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 239 * {@link RDB_OK} - success. 240 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 241 * @since 14 242 */ 243 int OH_Rdb_SetDatabaseDir(OH_Rdb_ConfigV2 *config, const char *databaseDir); 244 245 /** 246 * @brief Set property storeName into config 247 * 248 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 249 * Indicates the configuration of the database related to this RDB store. 250 * @param storeName Indicates the name of the database. 251 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 252 * {@link RDB_OK} - success. 253 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 254 * @since 14 255 */ 256 int OH_Rdb_SetStoreName(OH_Rdb_ConfigV2 *config, const char *storeName); 257 258 /** 259 * @brief Set property bundleName into config 260 * 261 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 262 * Indicates the configuration of the database related to this RDB store. 263 * @param bundleName Indicates the bundle name of the application 264 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 265 * {@link RDB_OK} - success. 266 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 267 * @since 14 268 */ 269 int OH_Rdb_SetBundleName(OH_Rdb_ConfigV2 *config, const char *bundleName); 270 271 /** 272 * @brief Set property moduleName into config 273 * 274 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 275 * Indicates the configuration of the database related to this RDB store. 276 * @param moduleName Indicates the module name of the application. 277 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 278 * {@link RDB_OK} - success. 279 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 280 * @since 14 281 */ 282 int OH_Rdb_SetModuleName(OH_Rdb_ConfigV2 *config, const char *moduleName); 283 284 /** 285 * @brief Set property isEncrypted into config 286 * 287 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 288 * Indicates the configuration of the database related to this RDB store. 289 * @param isEncrypted Indicates whether the database is encrypted. 290 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 291 * {@link RDB_OK} - success. 292 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 293 * @since 14 294 */ 295 int OH_Rdb_SetEncrypted(OH_Rdb_ConfigV2 *config, bool isEncrypted); 296 297 /** 298 * @brief Set property securityLevel into config 299 * 300 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 301 * Indicates the configuration of the database related to this RDB store. 302 * @param securityLevel Indicates the security level {@link OH_Rdb_SecurityLevel} of the database. 303 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 304 * {@link RDB_OK} - success. 305 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 306 * @since 14 307 */ 308 int OH_Rdb_SetSecurityLevel(OH_Rdb_ConfigV2 *config, int securityLevel); 309 310 /** 311 * @brief Set property area into config 312 * 313 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 314 * Indicates the configuration of the database related to this RDB store 315 * @param area Represents the security area of the database. 316 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 317 * {@link RDB_OK} - success. 318 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 319 * @since 14 320 */ 321 int OH_Rdb_SetArea(OH_Rdb_ConfigV2 *config, int area); 322 323 /** 324 * @brief Set whether the database enable the capabilities for semantic indexing processing. 325 * 326 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 327 * Indicates the configuration of the database related to this RDB store. 328 * @param enableSemanticIndex Indicates whether the database enable the capabilities for semantic indexing processing. 329 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 330 * {@link RDB_OK} - success. 331 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 332 * @since 20 333 */ 334 int OH_Rdb_SetSemanticIndex(OH_Rdb_ConfigV2 *config, bool enableSemanticIndex); 335 336 /** 337 * @brief Set property dbType into config 338 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 339 * @param dbType Indicates the dbType {@link Rdb_DBType} of the database 340 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 341 * {@link RDB_OK} - success. 342 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 343 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support db types. 344 * @since 14 345 */ 346 int OH_Rdb_SetDbType(OH_Rdb_ConfigV2 *config, int dbType); 347 348 /** 349 * @brief Sets the customized directory relative to the database. 350 * 351 * @param config Represents a pointer to a configuration of the database related to this relation database store. 352 * @param customDir Represents the customized relative to the database directory, the value cannot exceed 128 bytes. 353 * @return Returns the error code. 354 * Returns {@link RDB_OK} if the execution is successful. 355 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 356 * @since 20 357 */ 358 int OH_Rdb_SetCustomDir(OH_Rdb_ConfigV2 *config, const char *customDir); 359 360 /** 361 * @brief Sets the relation database store is read-only mode. 362 * 363 * @param config Represents a pointer to a configuration of the database related to this relation database store. 364 * @param readOnly Represents whether the relation database store is read-only. 365 * @return Returns the error code. 366 * Returns {@link RDB_OK} if the execution is successful. 367 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 368 * @since 20 369 */ 370 int OH_Rdb_SetReadOnly(OH_Rdb_ConfigV2 *config, bool readOnly); 371 372 /** 373 * @brief Sets the dynamic libraries with capabilities such as Full-Text Search (FTS). 374 * 375 * @param config Represents a pointer to a configuration of the database related to this relation database store. 376 * @param plugins Represents the dynamic libraries. 377 * @param length the size of plugins that the maximum value is 16. 378 * @return Returns the error code. 379 * Returns {@link RDB_OK} if the execution is successful. 380 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 381 * @since 20 382 */ 383 int OH_Rdb_SetPlugins(OH_Rdb_ConfigV2 *config, const char **plugins, int32_t length); 384 385 /** 386 * @brief Sets the custom encryption parameters. 387 * 388 * @param config Represents a pointer to a configuration of the database related to this relation database store. 389 * @param cryptoParam Represents the custom encryption parameters. 390 * @return Returns the error code. 391 * Returns {@link RDB_OK} if the execution is successful. 392 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 393 * @since 20 394 */ 395 int OH_Rdb_SetCryptoParam(OH_Rdb_ConfigV2 *config, const OH_Rdb_CryptoParam *cryptoParam); 396 397 /** 398 * @brief Check if a tokenizer is supported or not. 399 * 400 * @param tokenizer the tokenizer type of {@Link Rdb_Tokenizer}. 401 * @param isSupported Pointer to the Boolean value obtained. 402 * @return Returns the status code of the execution. 403 * {@link RDB_OK} indicates the operation is successful. 404 * {@link RDB_E_INVALID_ARGS} indicates invalid args are passed in. 405 * @since 16 406 */ 407 int OH_Rdb_IsTokenizerSupported(Rdb_Tokenizer tokenizer, bool *isSupported); 408 409 /** 410 * @brief Set property tokenizer into config 411 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 412 * @param tokenizer Indicates the tokenizer {@link Rdb_Tokenizer} of the database 413 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 414 * {@link RDB_OK} - success. 415 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 416 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support tokenizer. 417 * @since 16 418 */ 419 int OH_Rdb_SetTokenizer(OH_Rdb_ConfigV2 *config, Rdb_Tokenizer tokenizer); 420 421 /** 422 * @brief Set property isPersistent into config 423 * 424 * @param config Represents a pointer to {@link OH_Rdb_ConfigV2} instance. 425 * Indicates the configuration of the database related to this RDB store. 426 * @param isPersistent Indicates whether the database need persistence. 427 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 428 * {@link RDB_OK} - success. 429 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 430 * @since 18 431 */ 432 int OH_Rdb_SetPersistent(OH_Rdb_ConfigV2 *config, bool isPersistent); 433 434 /** 435 * @brief Get support db type list 436 * @param typeCount The output parameter, which is used to receive the length of the support db type array. 437 * @return Return Rdb_DBType array contains supported db type, array length is number of support type 438 * @since 14 439 */ 440 const int *OH_Rdb_GetSupportedDbType(int *typeCount); 441 442 /** 443 * @brief Creates an {@link OH_VObject} instance. 444 * 445 * @return If the creation is successful, a pointer to the instance of the @link OH_VObject} structure is returned, 446 * otherwise NULL is returned. 447 * @see OH_VObject. 448 * @since 10 449 */ 450 OH_VObject *OH_Rdb_CreateValueObject(); 451 452 /** 453 * @brief Creates an {@link OH_VBucket} object. 454 * 455 * @return If the creation is successful, a pointer to the instance of the @link OH_VBucket} structure is returned, 456 * otherwise NULL is returned. 457 * @see OH_VBucket. 458 * @since 10 459 */ 460 OH_VBucket *OH_Rdb_CreateValuesBucket(); 461 462 /** 463 * @brief Creates an {@link OH_Predicates} instance. 464 * 465 * @param table Indicates the table name. 466 * @return If the creation is successful, a pointer to the instance of the @link OH_Predicates} structure is returned. 467 * If the table name is nullptr, nullptr is returned. 468 * @see OH_Predicates. 469 * @since 10 470 */ 471 OH_Predicates *OH_Rdb_CreatePredicates(const char *table); 472 473 /** 474 * @brief Obtains an RDB store. 475 * 476 * You can set parameters of the RDB store as required. In general, 477 * this method is recommended to obtain a rdb store. 478 * 479 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 480 * Indicates the configuration of the database related to this RDB store. 481 * @param errCode This parameter is the output parameter, 482 * and the execution status of a function is written to this variable. 483 * @return If the creation is successful, a pointer to the instance of the @link OH_Rdb_Store} structure is returned. 484 * If the Config is empty, config.size does not match, or errCode is empty. 485 * Get database path failed.Get RDB Store fail. Nullptr is returned. 486 * @see OH_Rdb_Config, OH_Rdb_Store. 487 * @since 10 488 */ 489 OH_Rdb_Store *OH_Rdb_GetOrOpen(const OH_Rdb_Config *config, int *errCode); 490 491 /** 492 * @brief Obtains an RDB store with OH_Rdb_ConfigV2. 493 * 494 * You can set parameters of the RDB store as required. In general, 495 * this method is recommended to obtain a rdb store. 496 * 497 * @param config Represents a pointer to an {@link OH_Rdb_ConfigV2} instance. 498 * Indicates the configuration of the database related to this RDB store. 499 * @param errCode This parameter is the output parameter, 500 * and the execution status of a function is written to this variable. 501 * @return If the creation is successful, a pointer to the instance of the @link OH_Rdb_Store} structure is returned. 502 * If the Config is empty, config.size does not match, or errCode is empty. 503 * Get database path failed.Get RDB Store fail. Nullptr is returned. 504 * @see OH_Rdb_ConfigV2, OH_Rdb_Store. 505 * @since 14 506 */ 507 OH_Rdb_Store *OH_Rdb_CreateOrOpen(const OH_Rdb_ConfigV2 *config, int *errCode); 508 509 /** 510 * @brief Close the {@link OH_Rdb_Store} object and reclaim the memory occupied by the object. 511 * 512 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 513 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 514 * {@link RDB_OK} - success. 515 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 516 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 517 * @see OH_Rdb_Store, OH_Rdb_ErrCode. 518 * @since 10 519 */ 520 int OH_Rdb_CloseStore(OH_Rdb_Store *store); 521 522 /** 523 * @brief Deletes the database with a specified path. 524 * 525 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 526 * Indicates the configuration of the database related to this RDB store. 527 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 528 * {@link RDB_OK} - success. 529 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 530 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 531 * @see OH_Rdb_ErrCode. 532 * @since 10 533 */ 534 int OH_Rdb_DeleteStore(const OH_Rdb_Config *config); 535 536 /** 537 * @brief Deletes the database with a specified path. 538 * 539 * @param config Represents a pointer to an {@link OH_Rdb_ConfigV2} instance. 540 * Indicates the configuration of the database related to this RDB store. 541 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 542 * {@link RDB_OK} - success. 543 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 544 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 545 * @see OH_Rdb_ErrCode. 546 * @since 14 547 */ 548 int OH_Rdb_DeleteStoreV2(const OH_Rdb_ConfigV2 *config); 549 550 /** 551 * @brief Inserts a row of data into the target table. 552 * 553 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 554 * @param table Indicates the target table. 555 * @param valuesBucket Indicates the row of data {@link OH_VBucket} to be inserted into the table. 556 * @return Returns the rowId if success, returns a specific error code. 557 * {@link RDB_ERR} - Indicates that the function execution exception. 558 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 559 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 560 * @see OH_Rdb_Store, OH_VBucket, OH_Rdb_ErrCode. 561 * @since 10 562 */ 563 int OH_Rdb_Insert(OH_Rdb_Store *store, const char *table, OH_VBucket *valuesBucket); 564 565 /** 566 * @brief Inserts a row of data into the target table and support conflict resolution. 567 * 568 * @param store Represents a pointer to an OH_Rdb_Store instance. 569 * @param table Represents the target table. 570 * @param row Represents the row data to be inserted into the table. 571 * @param resolution Represents the resolution when conflict occurs. 572 * @param rowId Represents the number of successful insertion. 573 * @return Returns the status code of the execution. 574 * Returns {@link RDB_OK} if the execution is successful. 575 * Returns {@link RDB_E_ERROR} database common error. 576 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 577 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 578 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 579 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 580 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 581 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 582 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 583 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 584 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 585 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 586 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 587 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 588 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 589 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 590 * @since 20 591 */ 592 int OH_Rdb_InsertWithConflictResolution(OH_Rdb_Store *store, const char *table, OH_VBucket *row, 593 Rdb_ConflictResolution resolution, int64_t *rowId); 594 595 /** 596 * @brief Inserts a batch of data into the target table. 597 * 598 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 599 * @param table Represents the target table. 600 * @param rows Represents the rows data to be inserted into the table. 601 * @param resolution Represents the resolution when conflict occurs. 602 * @param changes Represents the number of successful insertions. 603 * @return Returns the status code of the execution. 604 * Returns {@link RDB_OK} if the execution is successful. 605 * Returns {@link RDB_E_ERROR} database common error. 606 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 607 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 608 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 609 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 610 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 611 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 612 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 613 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 614 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 615 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 616 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 617 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 618 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 619 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 620 * @since 16 621 */ 622 int OH_Rdb_BatchInsert(OH_Rdb_Store *store, const char *table, 623 const OH_Data_VBuckets *rows, Rdb_ConflictResolution resolution, int64_t *changes); 624 625 /** 626 * @brief Updates data in the database based on specified conditions. 627 * 628 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 629 * @param valuesBucket Indicates the row of data {@link OH__VBucket} to be updated in the database 630 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 631 * Indicates the specified update condition. 632 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 633 * {@link RDB_ERR} - Indicates that the function execution exception. 634 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 635 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 636 * @see OH_Rdb_Store, OH_Bucket, OH_Predicates, OH_Rdb_ErrCode. 637 * @since 10 638 */ 639 int OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates); 640 /** 641 * @brief Updates data in the database based on specified conditions and support conflict resolution. 642 * 643 * @param store Represents a pointer to an OH_Rdb_Store instance. 644 * @param row Represents the row data to be inserted into the table. 645 * @param predicates Represents a pointer to an link OH_Predicates instance. 646 * @param resolution Represents the resolution when conflict occurs. 647 * @param changes Represents the number of successful update. 648 * @return Returns the status code of the execution. 649 * Returns {@link RDB_OK} if the execution is successful. 650 * Returns {@link RDB_E_ERROR} database common error. 651 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 652 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 653 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 654 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 655 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 656 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 657 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 658 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 659 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 660 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 661 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 662 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 663 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 664 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 665 * @since 20 666 */ 667 int OH_Rdb_UpdateWithConflictResolution(OH_Rdb_Store *store, OH_VBucket *row, OH_Predicates *predicates, 668 Rdb_ConflictResolution resolution, int64_t *changes); 669 670 /** 671 * @brief Deletes data from the database based on specified conditions. 672 * 673 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 674 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 675 * Indicates the specified delete condition. 676 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 677 * {@link RDB_ERR} - Indicates that the function execution exception. 678 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 679 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 680 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 681 * @since 10 682 */ 683 int OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates); 684 685 /** 686 * @brief Queries data in the database based on specified conditions. 687 * 688 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 689 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 690 * Indicates the specified query condition. 691 * @param columnNames Indicates the columns to query. If the value is empty array, the query applies to all columns. 692 * @param length Indicates the length of columnNames. 693 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 694 * If Get store failed or resultSet is nullptr, nullptr is returned. 695 * @see OH_Rdb_Store, OH_Predicates, OH_Cursor. 696 * @since 10 697 */ 698 OH_Cursor *OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length); 699 700 /** 701 * @brief Executes an SQL statement. 702 * 703 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 704 * @param sql Indicates the SQL statement to execute. 705 * @return Returns the status code of the execution. 706 * {@link RDB_OK} - success. 707 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 708 * @see OH_Rdb_Store. 709 * @since 10 710 */ 711 int OH_Rdb_Execute(OH_Rdb_Store *store, const char *sql); 712 713 /** 714 * @brief Write operations are performed using the specified transaction represented by the transaction ID 715 * 716 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 717 * @param trxId The transaction ID of the specified transaction, must be greater than 0 718 * @param sql Indicates the SQL statement to execute. 719 * @return Returns the status code of the execution. 720 * {@link RDB_OK} - success. 721 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 722 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 723 * @see OH_Rdb_Store. 724 * @since 14 725 */ 726 int OH_Rdb_ExecuteByTrxId(OH_Rdb_Store *store, int64_t trxId, const char *sql); 727 728 /** 729 * @brief Queries data in the database based on an SQL statement. 730 * 731 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 732 * @param sql Indicates the SQL statement to execute. 733 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 734 * If Get store failed,sql is nullptr or resultSet is nullptr, nullptr is returned. 735 * @see OH_Rdb_Store. 736 * @since 10 737 */ 738 OH_Cursor *OH_Rdb_ExecuteQuery(OH_Rdb_Store *store, const char *sql); 739 740 /** 741 * @brief Begins a transaction in EXCLUSIVE mode. 742 * 743 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 744 * @return Returns the status code of the execution. 745 * {@link RDB_OK} - success. 746 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 747 * @see OH_Rdb_Store. 748 * @since 10 749 */ 750 int OH_Rdb_BeginTransaction(OH_Rdb_Store *store); 751 752 /** 753 * @brief Rolls back a transaction in EXCLUSIVE mode. 754 * 755 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 756 * @return Returns the status code of the execution. 757 * {@link RDB_OK} - success. 758 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 759 * @see OH_Rdb_Store. 760 * @since 10 761 */ 762 int OH_Rdb_RollBack(OH_Rdb_Store *store); 763 764 /** 765 * @brief Commits a transaction in EXCLUSIVE mode. 766 * 767 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 768 * @return Returns the status code of the execution. 769 * {@link RDB_OK} - success. 770 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 771 * @see OH_Rdb_Store. 772 * @since 10 773 */ 774 int OH_Rdb_Commit(OH_Rdb_Store *store); 775 776 /** 777 * @brief Begin a transaction and the transaction ID corresponding to the transaction. 778 * 779 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 780 * @param trxId The output parameter, which is used to receive the transaction ID corresponding to the transaction 781 * @return Returns the status code of the execution. 782 * {@link RDB_OK} - success. 783 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 784 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 785 * @see OH_Rdb_Store. 786 * @since 14 787 */ 788 int OH_Rdb_BeginTransWithTrxId(OH_Rdb_Store *store, int64_t *trxId); 789 790 /** 791 * @brief Roll back a transaction that is represented by a specified transaction ID 792 * 793 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 794 * @param trxId The transaction ID of the specified transaction, must be greater than 0 795 * @return Returns the status code of the execution. 796 * {@link RDB_OK} - success. 797 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 798 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 799 * @see OH_Rdb_Store. 800 * @since 14 801 */ 802 int OH_Rdb_RollBackByTrxId(OH_Rdb_Store *store, int64_t trxId); 803 804 /** 805 * @brief Commit a transaction that is represented by a specified transaction ID 806 * 807 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 808 * @param trxId The transaction ID of the specified transaction, must be greater than 0 809 * @return Returns the status code of the execution. 810 * {@link RDB_OK} - success. 811 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 812 * {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 813 * @see OH_Rdb_Store. 814 * @since 14 815 */ 816 int OH_Rdb_CommitByTrxId(OH_Rdb_Store *store, int64_t trxId); 817 818 /** 819 * @brief Backs up a database on specified path. 820 * 821 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 822 * @param databasePath Indicates the database file path. 823 * @return Returns the status code of the execution. 824 * {@link RDB_OK} - success. 825 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 826 * @see OH_Rdb_Store. 827 * @since 10 828 */ 829 int OH_Rdb_Backup(OH_Rdb_Store *store, const char *databasePath); 830 831 /** 832 * @brief Restores a database from a specified database file. 833 * 834 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 835 * @param databasePath Indicates the database file path. 836 * @return Returns the status code of the execution. 837 * {@link RDB_OK} - success. 838 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 839 * @see OH_Rdb_Store. 840 * @since 10 841 */ 842 int OH_Rdb_Restore(OH_Rdb_Store *store, const char *databasePath); 843 844 /** 845 * @brief Gets the version of a database. 846 * 847 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 848 * @param version Indicates the version number. 849 * @return Returns the status code of the execution. 850 * {@link RDB_OK} - success. 851 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 852 * @see OH_Rdb_Store. 853 * @since 10 854 */ 855 int OH_Rdb_GetVersion(OH_Rdb_Store *store, int *version); 856 857 /** 858 * @brief Sets the version of a database. 859 * 860 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 861 * @param version Indicates the version number. 862 * @return Returns the status code of the execution. 863 * {@link RDB_OK} - success. 864 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 865 * @see OH_Rdb_Store. 866 * @since 10 867 */ 868 int OH_Rdb_SetVersion(OH_Rdb_Store *store, int version); 869 870 /** 871 * @brief Describes the distribution type of the tables. 872 * 873 * @since 11 874 */ 875 typedef enum Rdb_DistributedType { 876 /** 877 * @brief Indicates the table is distributed among the devices. 878 */ 879 RDB_DISTRIBUTED_CLOUD 880 } Rdb_DistributedType; 881 882 /** 883 * @brief Indicates version of {@link Rdb_DistributedConfig} 884 * 885 * @since 11 886 */ 887 #define DISTRIBUTED_CONFIG_VERSION 1 888 /** 889 * @brief Manages the distributed configuration of the table. 890 * 891 * @since 11 892 */ 893 typedef struct Rdb_DistributedConfig { 894 /** 895 * The version used to uniquely identify the Rdb_DistributedConfig struct. 896 */ 897 int version; 898 /** 899 * Specifies whether the table auto syncs. 900 */ 901 bool isAutoSync; 902 } Rdb_DistributedConfig; 903 904 /** 905 * @brief Set table to be distributed table. 906 * 907 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 908 * @param tables Indicates the table names you want to set. 909 * @param count Indicates the count of tables you want to set. 910 * @param type Indicates the distributed type {@link Rdb_DistributedType}. 911 * @param config Indicates the distributed config of the tables. For details, see {@link Rdb_DistributedConfig}. 912 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 913 * {@link RDB_OK} - success. 914 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 915 * @see OH_Rdb_Store. 916 * @see Rdb_DistributedConfig. 917 * @since 11 918 */ 919 int OH_Rdb_SetDistributedTables(OH_Rdb_Store *store, const char *tables[], uint32_t count, Rdb_DistributedType type, 920 const Rdb_DistributedConfig *config); 921 922 /** 923 * @brief Set table to be distributed table. 924 * 925 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 926 * @param tableName Indicates the name of the table to check. 927 * @param columnName Indicates the name of the column corresponding to the primary key. 928 * If the table has no primary key , please pass in "rowid". 929 * @param values Indicates the primary keys of the rows to check. 930 * If the table has no primary key , please pass in the row-ids of the rows to check. 931 * @return If the operation is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 932 * If Get store failed, nullptr is returned. 933 * There are two columns, "data_key" and "timestamp". Otherwise NULL is returned. 934 * @see OH_Rdb_Store. 935 * @see OH_VObject. 936 * @see OH_Cursor. 937 * @since 11 938 */ 939 OH_Cursor *OH_Rdb_FindModifyTime( 940 OH_Rdb_Store *store, const char *tableName, const char *columnName, OH_VObject *values); 941 942 /** 943 * @brief Describes the change type. 944 * 945 * @since 11 946 */ 947 typedef enum Rdb_ChangeType { 948 /** 949 * @brief Means the change type is data change. 950 */ 951 RDB_DATA_CHANGE, 952 /** 953 * @brief Means the change type is asset change. 954 */ 955 RDB_ASSET_CHANGE 956 } Rdb_ChangeType; 957 958 /** 959 * @brief Describes the primary keys or row-ids of changed rows. 960 * 961 * @since 11 962 */ 963 typedef struct Rdb_KeyInfo { 964 /** 965 * Indicates the count of the primary keys or row-ids. 966 */ 967 int count; 968 969 /** 970 * Indicates data type {@link OH_ColumnType} of the key. 971 */ 972 int type; 973 974 /** 975 * Indicates the data of the key info. 976 */ 977 union Rdb_KeyData { 978 /** 979 * Indicates uint64_t type of the data. 980 */ 981 uint64_t integer; 982 983 /** 984 * Indicates double type of the data. 985 */ 986 double real; 987 988 /** 989 * Indicates const char * type of the data. 990 */ 991 const char *text; 992 } *data; 993 } Rdb_KeyInfo; 994 995 /** 996 * @brief Indicates version of {@link Rdb_ChangeInfo} 997 * 998 * @since 11 999 */ 1000 #define DISTRIBUTED_CHANGE_INFO_VERSION 1 1001 1002 /** 1003 * @brief Describes the notify info of data change. 1004 * 1005 * @since 11 1006 */ 1007 typedef struct Rdb_ChangeInfo { 1008 /** 1009 * The version used to uniquely identify the Rdb_ChangeInfo struct. 1010 */ 1011 int version; 1012 1013 /** 1014 * The name of changed table. 1015 */ 1016 const char *tableName; 1017 1018 /** 1019 * The {@link Rdb_ChangeType} of changed table. 1020 */ 1021 int ChangeType; 1022 1023 /** 1024 * The {@link Rdb_KeyInfo} of inserted rows. 1025 */ 1026 Rdb_KeyInfo inserted; 1027 1028 /** 1029 * The {@link Rdb_KeyInfo} of updated rows. 1030 */ 1031 Rdb_KeyInfo updated; 1032 1033 /** 1034 * The {@link Rdb_KeyInfo} of deleted rows. 1035 */ 1036 Rdb_KeyInfo deleted; 1037 } Rdb_ChangeInfo; 1038 1039 /** 1040 * @brief Indicates the subscribe type. 1041 * 1042 * @since 11 1043 */ 1044 typedef enum Rdb_SubscribeType { 1045 /** 1046 * @brief Subscription to cloud data changes. 1047 */ 1048 RDB_SUBSCRIBE_TYPE_CLOUD, 1049 1050 /** 1051 * @brief Subscription to cloud data change details. 1052 */ 1053 RDB_SUBSCRIBE_TYPE_CLOUD_DETAILS, 1054 1055 /** 1056 * @brief Subscription to local data change details. 1057 * @since 12 1058 */ 1059 RDB_SUBSCRIBE_TYPE_LOCAL_DETAILS, 1060 } Rdb_SubscribeType; 1061 1062 /** 1063 * @brief The callback function of cloud data change event. 1064 * 1065 * @param context Represents the context of data observer. 1066 * @param values Indicates the cloud accounts that changed. 1067 * @param count The count of changed cloud accounts. 1068 * @see OH_VObject. 1069 * @since 11 1070 */ 1071 typedef void (*Rdb_BriefObserver)(void *context, const char *values[], uint32_t count); 1072 1073 /** 1074 * @brief The callback function of cloud data change details event. 1075 * 1076 * @param context Represents the context of data observer. 1077 * @param changeInfo Indicates the {@link Rdb_ChangeInfo} of changed tables. 1078 * @param count The count of changed tables. 1079 * @see Rdb_ChangeInfo. 1080 * @since 11 1081 */ 1082 typedef void (*Rdb_DetailsObserver)(void *context, const Rdb_ChangeInfo **changeInfo, uint32_t count); 1083 1084 /** 1085 * @brief Indicates the callback functions. 1086 * 1087 * @since 11 1088 */ 1089 typedef union Rdb_SubscribeCallback { 1090 /** 1091 * The callback function of cloud data change details event. 1092 */ 1093 Rdb_DetailsObserver detailsObserver; 1094 1095 /** 1096 * The callback function of cloud data change event. 1097 */ 1098 Rdb_BriefObserver briefObserver; 1099 } Rdb_SubscribeCallback; 1100 1101 /** 1102 * @brief Indicates the observer of data. 1103 * 1104 * @since 11 1105 */ 1106 typedef struct Rdb_DataObserver { 1107 /** 1108 * The context of data observer. 1109 */ 1110 void *context; 1111 1112 /** 1113 * The callback of data observer. 1114 */ 1115 Rdb_SubscribeCallback callback; 1116 } Rdb_DataObserver; 1117 1118 /** 1119 * @brief Registers an observer for the database. 1120 * When data in the distributed database changes, the callback will be invoked. 1121 * 1122 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1123 * @param type Indicates the subscription type, which is defined in {@link Rdb_SubscribeType}. 1124 * @param observer The {@link Rdb_DataObserver} of change events in the database. 1125 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1126 * {@link RDB_OK} - success. 1127 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1128 * @see OH_Rdb_Store. 1129 * @see Rdb_DataObserver. 1130 * @since 11 1131 */ 1132 int OH_Rdb_Subscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer); 1133 1134 /** 1135 * @brief Remove specified observer of specified type from the database. 1136 * 1137 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1138 * @param type Indicates the subscription type, which is defined in {@link Rdb_SubscribeType}. 1139 * @param observer The {@link Rdb_DataObserver} of change events in the database. 1140 * If this is nullptr, remove all observers of the type. 1141 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1142 * {@link RDB_OK} - success. 1143 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1144 * @see OH_Rdb_Store. 1145 * @see Rdb_DataObserver. 1146 * @since 11 1147 */ 1148 int OH_Rdb_Unsubscribe(OH_Rdb_Store *store, Rdb_SubscribeType type, const Rdb_DataObserver *observer); 1149 1150 /** 1151 * @brief Indicates the database synchronization mode. 1152 * 1153 * @since 11 1154 */ 1155 typedef enum Rdb_SyncMode { 1156 /** 1157 * @brief Indicates that data is synchronized from the end with the closest modification time 1158 * to the end with a more distant modification time. 1159 */ 1160 RDB_SYNC_MODE_TIME_FIRST, 1161 /** 1162 * @brief Indicates that data is synchronized from local to cloud. 1163 */ 1164 RDB_SYNC_MODE_NATIVE_FIRST, 1165 /** 1166 * @brief Indicates that data is synchronized from cloud to local. 1167 */ 1168 RDB_SYNC_MODE_CLOUD_FIRST 1169 } Rdb_SyncMode; 1170 1171 /** 1172 * @brief Describes the statistic of the cloud sync process. 1173 * 1174 * @since 11 1175 */ 1176 typedef struct Rdb_Statistic { 1177 /** 1178 * Describes the total number of data to sync. 1179 */ 1180 int total; 1181 1182 /** 1183 * Describes the number of successfully synced data. 1184 */ 1185 int successful; 1186 1187 /** 1188 * Describes the number of data failed to sync. 1189 */ 1190 int failed; 1191 1192 /** 1193 * Describes the number of data remained to sync. 1194 */ 1195 int remained; 1196 } Rdb_Statistic; 1197 1198 /** 1199 * @brief Describes the {@link Rdb_Statistic} details of the table. 1200 * 1201 * @since 11 1202 */ 1203 typedef struct Rdb_TableDetails { 1204 /** 1205 * Indicates the name of changed table. 1206 */ 1207 const char *table; 1208 1209 /** 1210 * Describes the {@link Rdb_Statistic} details of the upload process. 1211 */ 1212 Rdb_Statistic upload; 1213 1214 /** 1215 * Describes the {@link Rdb_Statistic} details of the download process. 1216 */ 1217 Rdb_Statistic download; 1218 } Rdb_TableDetails; 1219 1220 /** 1221 * The cloud sync progress 1222 * 1223 * @since 11 1224 */ 1225 typedef enum Rdb_Progress { 1226 /** 1227 * @brief Means the sync process begin. 1228 */ 1229 RDB_SYNC_BEGIN, 1230 1231 /** 1232 * @brief Means the sync process is in progress 1233 */ 1234 RDB_SYNC_IN_PROGRESS, 1235 1236 /** 1237 * @brief Means the sync process is finished 1238 */ 1239 RDB_SYNC_FINISH 1240 } Rdb_Progress; 1241 1242 /** 1243 * Describes the status of cloud sync progress. 1244 * 1245 * @since 11 1246 */ 1247 typedef enum Rdb_ProgressCode { 1248 /** 1249 * @brief Means the status of progress is success. 1250 */ 1251 RDB_SUCCESS, 1252 1253 /** 1254 * @brief Means the progress meets unknown error. 1255 */ 1256 RDB_UNKNOWN_ERROR, 1257 1258 /** 1259 * @brief Means the progress meets network error. 1260 */ 1261 RDB_NETWORK_ERROR, 1262 1263 /** 1264 * @brief Means cloud is disabled. 1265 */ 1266 RDB_CLOUD_DISABLED, 1267 1268 /** 1269 * @brief Means the progress is locked by others. 1270 */ 1271 RDB_LOCKED_BY_OTHERS, 1272 1273 /** 1274 * @brief Means the record exceeds the limit. 1275 */ 1276 RDB_RECORD_LIMIT_EXCEEDED, 1277 1278 /** 1279 * Means the cloud has no space for the asset. 1280 */ 1281 RDB_NO_SPACE_FOR_ASSET 1282 } Rdb_ProgressCode; 1283 1284 /** 1285 * @brief Indicates version of {@link Rdb_ProgressDetails} 1286 * 1287 * @since 11 1288 */ 1289 #define DISTRIBUTED_PROGRESS_DETAIL_VERSION 1 1290 1291 /** 1292 * @brief Describes detail of the cloud sync progress. 1293 * 1294 * @since 11 1295 */ 1296 typedef struct Rdb_ProgressDetails { 1297 /** 1298 * The version used to uniquely identify the Rdb_ProgressDetails struct. 1299 */ 1300 int version; 1301 1302 /** 1303 * Describes the status of data sync progress. Defined in {@link Rdb_Progress}. 1304 */ 1305 int schedule; 1306 1307 /** 1308 * Describes the code of data sync progress. Defined in {@link Rdb_ProgressCode}. 1309 */ 1310 int code; 1311 1312 /** 1313 * Describes the length of changed tables in data sync progress. 1314 */ 1315 int32_t tableLength; 1316 } Rdb_ProgressDetails; 1317 1318 /** 1319 * @brief Get table details from progress details. 1320 * 1321 * @param progress Represents a pointer to an {@link Rdb_ProgressDetails} instance. 1322 * @param version Indicates the version of current {@link Rdb_ProgressDetails}. 1323 * @return If the operation is successful, a pointer to the instance of the {@link Rdb_TableDetails} 1324 * structure is returned.If get details is failed, nullptr is returned. 1325 * @see Rdb_ProgressDetails 1326 * @see Rdb_TableDetails 1327 * @since 11 1328 */ 1329 Rdb_TableDetails *OH_Rdb_GetTableDetails(Rdb_ProgressDetails *progress, int32_t version); 1330 1331 /** 1332 * @brief The callback function of progress. 1333 * 1334 * @param progressDetails The details of the sync progress. 1335 * @see Rdb_ProgressDetails. 1336 * @since 11 1337 */ 1338 typedef void (*Rdb_ProgressCallback)(void *context, Rdb_ProgressDetails *progressDetails); 1339 1340 /** 1341 * @brief The callback function of sync. 1342 * 1343 * @param progressDetails The details of the sync progress. 1344 * @see Rdb_ProgressDetails. 1345 * @since 11 1346 */ 1347 typedef void (*Rdb_SyncCallback)(Rdb_ProgressDetails *progressDetails); 1348 1349 /** 1350 * @brief The observer of progress. 1351 * 1352 * @since 11 1353 */ 1354 typedef struct Rdb_ProgressObserver { 1355 /** 1356 * The context of progress observer. 1357 */ 1358 void *context; 1359 1360 /** 1361 * The callback function of progress observer. 1362 */ 1363 Rdb_ProgressCallback callback; 1364 } Rdb_ProgressObserver; 1365 1366 /** 1367 * @brief Sync data to cloud. 1368 * 1369 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1370 * @param mode Represents the {@link Rdb_SyncMode} of sync progress. 1371 * @param tables Indicates the names of tables to sync. 1372 * @param count The count of tables to sync. If value equals 0, sync all tables of the store. 1373 * @param observer The {@link Rdb_ProgressObserver} of cloud sync progress. 1374 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1375 * {@link RDB_OK} - success. 1376 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1377 * @see OH_Rdb_Store. 1378 * @see Rdb_ProgressObserver. 1379 * @since 11 1380 */ 1381 int OH_Rdb_CloudSync(OH_Rdb_Store *store, Rdb_SyncMode mode, const char *tables[], uint32_t count, 1382 const Rdb_ProgressObserver *observer); 1383 1384 /** 1385 * @brief Subscribes to the automatic synchronization progress of an RDB store. 1386 * A callback will be invoked when there is a notification of the automatic synchronization progress. 1387 * 1388 * @param store Indicates the pointer to the target {@Link OH_Rdb_Store} instance. 1389 * @param observer The {@link Rdb_SyncObserver} for the automatic synchronization progress 1390 * Indicates the callback invoked to return the automatic synchronization progress. 1391 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1392 * {@link RDB_OK} - success. 1393 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1394 * @see OH_Rdb_Store. 1395 * @see Rdb_ProgressObserver. 1396 * @since 11 1397 */ 1398 int OH_Rdb_SubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer); 1399 1400 /** 1401 * @brief Unsubscribes from the automatic synchronization progress of an RDB store. 1402 * 1403 * @param store Indicates the pointer to the target {@Link OH_Rdb_Store} instance. 1404 * @param observer Indicates the {@link Rdb_SyncObserver} callback for the automatic synchronization progress. 1405 * If it is a null pointer, all callbacks for the automatic synchronization progress will be unregistered. 1406 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1407 * {@link RDB_OK} - success. 1408 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1409 * @see OH_Rdb_Store. 1410 * @see Rdb_ProgressObserver. 1411 * @since 11 1412 */ 1413 int OH_Rdb_UnsubscribeAutoSyncProgress(OH_Rdb_Store *store, const Rdb_ProgressObserver *observer); 1414 1415 /** 1416 * @brief Lock data from the database based on specified conditions. 1417 * 1418 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1419 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1420 * Indicates the specified lock condition. 1421 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1422 * {@link RDB_OK} - success. 1423 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1424 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 1425 * @since 12 1426 */ 1427 int OH_Rdb_LockRow(OH_Rdb_Store *store, OH_Predicates *predicates); 1428 1429 /** 1430 * @brief Unlock data from the database based on specified conditions. 1431 * 1432 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1433 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1434 * Indicates the specified unlock condition. 1435 * @return Returns the status code of the execution. See {@link OH_Rdb_ErrCode}. 1436 * {@link RDB_OK} - success. 1437 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1438 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 1439 * @since 12 1440 */ 1441 int OH_Rdb_UnlockRow(OH_Rdb_Store *store, OH_Predicates *predicates); 1442 1443 /** 1444 * @brief Queries locked data in the database based on specified conditions. 1445 * 1446 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1447 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 1448 * Indicates the specified query condition. 1449 * @param columnNames Indicates the columns to query. If the value is empty array, the query applies to all columns. 1450 * @param length Indicates the length of columnNames. 1451 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 1452 * If Get store failed or resultSet is nullptr, nullptr is returned. 1453 * @see OH_Rdb_Store, OH_Predicates, OH_Cursor. 1454 * @since 12 1455 */ 1456 OH_Cursor *OH_Rdb_QueryLockedRow( 1457 OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length); 1458 1459 /** 1460 * @brief Creates an OH_Rdb_Transaction instance object. 1461 * 1462 * @param store Represents a pointer to an instance of OH_Rdb_Store. 1463 * @param options Represents a pointer to an instance of OH_RDB_TransOptions. 1464 * @param trans Represents a pointer to OH_Rdb_Transaction instance when the execution is successful. 1465 * Otherwise, nullptr is returned. The memory must be released through the OH_RdbTrans_Destroy 1466 * interface after the use is complete. 1467 * @return Returns the error code. 1468 * Returns {@link RDB_OK} if the execution is successful. 1469 * Returns {@link RDB_E_ERROR} database common error. 1470 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 1471 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 1472 * Returns {@link RDB_E_DATABASE_BUSY} database does not respond. 1473 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 1474 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 1475 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 1476 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 1477 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 1478 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 1479 * Returns {@link RDB_E_SQLITE_CANT_OPEN} SQLite: Unable to open the database file. 1480 * @see OH_RdbTrans_Destroy. 1481 * @since 16 1482 */ 1483 int OH_Rdb_CreateTransaction(OH_Rdb_Store *store, const OH_RDB_TransOptions *options, OH_Rdb_Transaction **trans); 1484 1485 /** 1486 * @brief Executes an SQL statement. 1487 * 1488 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1489 * @param sql Indicates the SQL statement to execute. 1490 * @param args Represents the values of the parameters in the SQL statement. 1491 * @param result Represents a pointer to OH_Data_Value instance when the execution is successful. 1492 * The memory must be released through the OH_Value_Destroy interface after the use is complete. 1493 * @return Returns the status code of the execution. 1494 * Returns {@link RDB_OK} if the execution is successful. 1495 * Returns {@link RDB_E_ERROR} database common error. 1496 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 1497 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 1498 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 1499 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 1500 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 1501 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 1502 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 1503 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 1504 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 1505 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 1506 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 1507 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 1508 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 1509 * @see OH_Value_Destroy. 1510 * @since 16 1511 */ 1512 int OH_Rdb_ExecuteV2(OH_Rdb_Store *store, const char *sql, const OH_Data_Values *args, OH_Data_Value **result); 1513 1514 /** 1515 * @brief Queries data in the database based on an SQL statement. 1516 * 1517 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1518 * @param sql Indicates the SQL statement to execute. 1519 * @param args Represents a pointer to an instance of OH_Data_Values and it is the selection arguments. 1520 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned. 1521 * If sql statement is invalid or the memory allocate failed, nullptr is returned. 1522 * @see OH_Rdb_Store. 1523 * @since 16 1524 */ 1525 OH_Cursor *OH_Rdb_ExecuteQueryV2(OH_Rdb_Store *store, const char *sql, const OH_Data_Values *args); 1526 1527 /** 1528 * @brief Attaches a database file to the currently linked database. 1529 * 1530 * @param store Represents a pointer to an OH_Rdb_Store instance. 1531 * @param config Represents a pointer to an OH_Rdb_ConfigV2 configuration of the database related to this RDB store. 1532 * @param attachName Represents the alias of the database. 1533 * @param waitTime Represents the maximum time allowed for attaching the database, valid range is 1 to 300. 1534 * @param attachedNumber Represents the number of attached databases, It is an output parameter. 1535 * @return Returns the status code of the execution. 1536 * Returns {@link RDB_OK} if the execution is successful. 1537 * Returns {@link RDB_E_ERROR} database common error. 1538 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 1539 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 1540 * Returns {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 1541 * Returns {@link RDB_E_DATABASE_BUSY} database does not respond. 1542 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 1543 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 1544 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 1545 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 1546 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 1547 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 1548 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 1549 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 1550 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 1551 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 1552 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 1553 * @since 20 1554 */ 1555 int OH_Rdb_Attach(OH_Rdb_Store *store, const OH_Rdb_ConfigV2 *config, const char *attachName, int64_t waitTime, 1556 size_t *attachedNumber); 1557 1558 /** 1559 * @brief Detaches a database from this database. 1560 * 1561 * @param store Represents a pointer to an OH_Rdb_Store instance. 1562 * @param attachName Represents the alias of the database. 1563 * @param waitTime Represents the maximum time allowed for detaching the database, valid range is 1 to 300. 1564 * @param attachedNumber Represents the number of attached databases, It is an output parameter. 1565 * @return Returns the status code of the execution. 1566 * Returns {@link RDB_OK} if the execution is successful. 1567 * Returns {@link RDB_E_ERROR} database common error. 1568 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 1569 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 1570 * Returns {@link RDB_E_NOT_SUPPORTED} - The error code for not support. 1571 * Returns {@link RDB_E_DATABASE_BUSY} database does not respond. 1572 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 1573 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 1574 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 1575 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 1576 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 1577 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 1578 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 1579 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 1580 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 1581 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 1582 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 1583 * @see OH_Rdb_Store, OH_Rdb_ErrCode. 1584 * @since 20 1585 */ 1586 int OH_Rdb_Detach(OH_Rdb_Store *store, const char *attachName, int64_t waitTime, size_t *attachedNumber); 1587 1588 /** 1589 * @brief Support for collations in different languages. 1590 * 1591 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 1592 * @param locale Language related to the locale, for example, zh. The value complies with the ISO 639 standard. 1593 * @return Returns a specific error code. 1594 * {@link RDB_OK} if the execution is successful. 1595 * {@link RDB_ERR} - Indicates that the function execution exception. 1596 * {@link RDB_E_INVALID_ARGS} - The error code for common invalid args. 1597 * {@link RDB_E_ALREADY_CLOSED} database already closed. 1598 * {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 1599 * {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 1600 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 1601 * @see OH_Rdb_Store. 1602 * @since 20 1603 */ 1604 int OH_Rdb_SetLocale(OH_Rdb_Store *store, const char *locale); 1605 1606 #ifdef __cplusplus 1607 }; 1608 #endif 1609 1610 #endif // RELATIONAL_STORE_H 1611