1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup RDB 18 * @{ 19 * 20 * @brief The relational database (RDB) store manages data based on relational models. 21 * With the underlying SQLite database, the RDB store provides a complete mechanism for managing local databases. 22 * To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations 23 * such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. 24 * 25 * @since 10 26 */ 27 28 /** 29 * @file oh_rdb_transaction.h 30 * 31 * @brief Provides database transaction related functions and enumerations. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.z.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * 37 * @since 16 38 */ 39 40 #ifndef OH_RDB_TRANSACTION_H 41 #define OH_RDB_TRANSACTION_H 42 #include "oh_cursor.h" 43 #include "oh_predicates.h" 44 #include "oh_data_values.h" 45 #include "oh_values_bucket.h" 46 #include "oh_data_values_buckets.h" 47 #include "oh_rdb_types.h" 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Indicates relation database transaction type. 54 * 55 * @since 16 56 */ 57 typedef enum OH_RDB_TransType { 58 /** 59 * @brief Indicates the transaction does not actually start until the database is first accessed. It's a default. 60 */ 61 RDB_TRANS_DEFERRED = 0, 62 /** 63 * @brief Indicates the database connection to start a new write immediately, without waiting for a write statement. 64 */ 65 RDB_TRANS_IMMEDIATE, 66 /** 67 * @brief Indicates it is similar to RDB_TRANS_IMMEDIATE in that a write transaction is started immediately. 68 * RDB_TRANS_EXCLUSIVE and RDB_TRANS_IMMEDIATE are the same in WAL mode, but in other journaling modes, 69 * EXCLUSIVE prevents other database connections from reading the database while the transaction is underway. 70 */ 71 RDB_TRANS_EXCLUSIVE, 72 /** 73 * The largest value for rdb transaction type. 74 */ 75 RDB_TRANS_BUTT, 76 } OH_RDB_TransType; 77 78 /** 79 * @brief Define the OH_RDB_TransOptions structure type. 80 * 81 * @since 16 82 */ 83 typedef struct OH_RDB_TransOptions OH_RDB_TransOptions; 84 85 /** 86 * @brief Define the OH_Rdb_Transaction structure type. 87 * 88 * @since 16 89 */ 90 typedef struct OH_Rdb_Transaction OH_Rdb_Transaction; 91 92 /** 93 * @brief Creates an OH_RDB_TransOptions instance object. 94 * 95 * @return Returns a pointer to OH_RDB_TransOptions instance when the execution is successful. 96 * Otherwise, nullptr is returned. The memory must be released through the OH_RdbTrans_DestroyOptions 97 * interface after the use is complete. 98 * @see OH_RdbTrans_DestroyOptions. 99 * @since 16 100 */ 101 OH_RDB_TransOptions *OH_RdbTrans_CreateOptions(void); 102 103 /** 104 * @brief Destroys an OH_RDB_TransOptions instance object. 105 * 106 * @param options Represents a pointer to an instance of OH_RDB_TransOptions. 107 * @return Returns the error code. 108 * Returns {@link RDB_OK} if the execution is successful. 109 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 110 * @since 16 111 */ 112 int OH_RdbTrans_DestroyOptions(OH_RDB_TransOptions *options); 113 114 /** 115 * @brief Sets integer data to the options object. 116 * 117 * @param options Represents a pointer to an instance of OH_RDB_TransOptions. 118 * @param type Represents relation database transaction type. 119 * @return Returns the error code. 120 * Returns {@link RDB_OK} if the execution is successful. 121 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 122 * @since 16 123 */ 124 int OH_RdbTransOption_SetType(OH_RDB_TransOptions *options, OH_RDB_TransType type); 125 126 /** 127 * @brief Commits a transaction of a relational database. 128 * 129 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 130 * @return Returns the status code of the execution. 131 * Returns {@link RDB_OK} if the execution is successful. 132 * Returns {@link RDB_E_ERROR} database common error. 133 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 134 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 135 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 136 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 137 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 138 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 139 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 140 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: SQLite: Attempt to write a readonly database. 141 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 142 * @since 16 143 */ 144 int OH_RdbTrans_Commit(OH_Rdb_Transaction *trans); 145 146 /** 147 * @brief Roll back a transaction of a relational database. 148 * 149 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 150 * @return Returns the status code of the execution. 151 * Returns {@link RDB_OK} if the execution is successful. 152 * Returns {@link RDB_E_ERROR} database common error. 153 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 154 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 155 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 156 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 157 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 158 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 159 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 160 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 161 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 162 * @since 16 163 */ 164 int OH_RdbTrans_Rollback(OH_Rdb_Transaction *trans); 165 166 /** 167 * @brief Inserts a row of data into the target table. 168 * 169 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 170 * @param table Represents the target table. 171 * @param row Represents the row data to be inserted into the table. 172 * @param rowId Represents row line number when insert successfully. 173 * @return Returns the status code of the execution. 174 * Returns {@link RDB_OK} if the execution is successful. 175 * Returns {@link RDB_E_ERROR} database common error. 176 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 177 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 178 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 179 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 180 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 181 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 182 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 183 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 184 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 185 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 186 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 187 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 188 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 189 190 * @since 16 191 */ 192 int OH_RdbTrans_Insert(OH_Rdb_Transaction *trans, const char *table, const OH_VBucket *row, int64_t *rowId); 193 194 /** 195 * @brief Inserts a row of data into the target table and support conflict resolution. 196 * 197 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 198 * @param table Represents the target table. 199 * @param row Represents the row data to be inserted into the table. 200 * @param resolution Represents the resolution when conflict occurs. 201 * @param rowId Represents row line number when insert successfully. 202 * @return Returns the status code of the execution. 203 * Returns {@link RDB_OK} if the execution is successful. 204 * Returns {@link RDB_E_ERROR} database common error. 205 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 206 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 207 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 208 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 209 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 210 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 211 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 212 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 213 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 214 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 215 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 216 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 217 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 218 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 219 * @since 20 220 */ 221 int OH_RdbTrans_InsertWithConflictResolution(OH_Rdb_Transaction *trans, const char *table, const OH_VBucket *row, 222 Rdb_ConflictResolution resolution, int64_t *rowId); 223 224 /** 225 * @brief Inserts a batch of data into the target table. 226 * 227 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 228 * @param table Represents the target table. 229 * @param rows Represents the rows data to be inserted into the table. 230 * @param resolution Represents the resolution when conflict occurs. 231 * @param changes Represents the number of successful insertions. 232 * @return Returns the status code of the execution. 233 * Returns {@link RDB_OK} if the execution is successful. 234 * Returns {@link RDB_E_ERROR} database common error. 235 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 236 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 237 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 238 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 239 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 240 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 241 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 242 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 243 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 244 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 245 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 246 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 247 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 248 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 249 * @since 16 250 */ 251 int OH_RdbTrans_BatchInsert(OH_Rdb_Transaction *trans, const char *table, const OH_Data_VBuckets *rows, 252 Rdb_ConflictResolution resolution, int64_t *changes); 253 254 /** 255 * @brief Updates data in the database based on specified conditions. 256 * 257 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 258 * @param row Represents the row data to be updated into the table. 259 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 260 * @param changes Represents the number of successful insertions. 261 * @return Returns the status code of the execution. 262 * Returns {@link RDB_OK} if the execution is successful. 263 * Returns {@link RDB_E_ERROR} database common error. 264 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 265 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 266 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 267 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 268 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 269 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 270 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 271 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 272 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 273 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 274 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 275 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 276 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 277 * @since 16 278 */ 279 int OH_RdbTrans_Update(OH_Rdb_Transaction *trans, const OH_VBucket *row, const OH_Predicates *predicates, 280 int64_t *changes); 281 /** 282 * @brief Updates data in the database based on specified conditions and support conflict resolution. 283 * 284 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 285 * @param row Represents the row data to be updated into the table. 286 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 287 * @param resolution Represents the resolution when conflict occurs. 288 * @param changes Represents the number of successful insertions. 289 * @return Returns the status code of the execution. 290 * Returns {@link RDB_OK} if the execution is successful. 291 * Returns {@link RDB_E_ERROR} database common error. 292 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 293 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 294 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 295 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 296 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 297 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 298 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 299 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 300 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 301 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 302 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 303 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 304 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 305 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 306 * @since 20 307 */ 308 int OH_RdbTrans_UpdateWithConflictResolution(OH_Rdb_Transaction *trans, const OH_VBucket *row, 309 const OH_Predicates *predicates, Rdb_ConflictResolution resolution, int64_t *changes); 310 311 /** 312 * @brief Deletes data from the database based on specified conditions 313 * 314 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 315 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 316 * @param changes Represents the number of successfully Deleted. 317 * @return Returns the status code of the execution. 318 * Returns {@link RDB_OK} if the execution is successful. 319 * Returns {@link RDB_E_ERROR} database common error. 320 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 321 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 322 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 323 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 324 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 325 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 326 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 327 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 328 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 329 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 330 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 331 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 332 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 333 * @since 16 334 */ 335 int OH_RdbTrans_Delete(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, int64_t *changes); 336 337 /** 338 * @brief Queries data in the database based on specified conditions. 339 * 340 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 341 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 342 * @param columns Represents the columns to query. If the value is empty array, the query applies to all columns. 343 * @param len Represents the number of columns elements. 344 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 345 * If database has closed or the database does not respond, nullptr is returned. 346 * @since 16 347 */ 348 OH_Cursor *OH_RdbTrans_Query(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, const char *columns[], 349 int len); 350 351 /** 352 * @brief Queries data in the database based on SQL statement. 353 * 354 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 355 * @param sql Represents the SQL statement to execute. 356 * @param args Represents a pointer to an instance of OH_Data_Values and it is the selection arguments. 357 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 358 * If database has closed or the database does not respond, nullptr is returned. 359 * @since 16 360 */ 361 OH_Cursor *OH_RdbTrans_QuerySql(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args); 362 363 /** 364 * @brief Executes an SQL statement that contains specified parameters. 365 * 366 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 367 * @param sql Represents the SQL statement to execute. 368 * @param args Represents the values of the parameters in the SQL statement. 369 * @param result Represents a pointer to OH_Data_Value instance when the execution is successful. 370 * The memory must be released through the OH_Value_Destroy interface after the use is complete. 371 * @return Returns the status code of the execution. 372 * Returns {@link RDB_OK} if the execution is successful. 373 * Returns {@link RDB_E_ERROR} database common error. 374 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 375 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 376 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 377 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 378 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 379 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 380 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 381 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 382 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 383 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 384 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 385 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 386 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 387 * @see OH_Value_Destroy. 388 * @since 16 389 */ 390 int OH_RdbTrans_Execute(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args, OH_Data_Value **result); 391 392 /** 393 * @brief Destroys an OH_Rdb_Transaction instance object. 394 * 395 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 396 * @return Returns the error code. 397 * Returns {@link RDB_OK} if the execution is successful. 398 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 399 * @since 16 400 */ 401 int OH_RdbTrans_Destroy(OH_Rdb_Transaction *trans); 402 403 #ifdef __cplusplus 404 }; 405 #endif 406 #endif // OH_RDB_TRANSACTION_H 407 /** @} */ 408