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 18 38 */ 39 40 #ifndef OH_RDB_TRANSACTION_H 41 #define OH_RDB_TRANSACTION_H 42 43 #include "database/rdb/oh_cursor.h" 44 #include "database/rdb/oh_predicates.h" 45 #include "database/rdb/oh_values_bucket.h" 46 #include "database/rdb/oh_rdb_types.h" 47 #include "database/data/oh_data_values.h" 48 #include "database/data/oh_data_values_buckets.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @brief Indicates relation database transaction type. 56 * 57 * @since 18 58 */ 59 typedef enum OH_RDB_TransType { 60 /** 61 * @brief Indicates the transaction does not actually start until the database is first accessed. It's a default. 62 */ 63 RDB_TRANS_DEFERRED = 0, 64 /** 65 * @brief Indicates the database connection to start a new write immediately, without waiting for a write statement. 66 */ 67 RDB_TRANS_IMMEDIATE, 68 /** 69 * @brief Indicates it is similar to RDB_TRANS_IMMEDIATE in that a write transaction is started immediately. 70 * RDB_TRANS_EXCLUSIVE and RDB_TRANS_IMMEDIATE are the same in WAL mode, but in other journaling modes, 71 * EXCLUSIVE prevents other database connections from reading the database while the transaction is underway. 72 */ 73 RDB_TRANS_EXCLUSIVE, 74 /** 75 * The largest value for rdb transaction type. 76 */ 77 RDB_TRANS_BUTT, 78 } OH_RDB_TransType; 79 80 /** 81 * @brief Define the OH_RDB_TransOptions structure type. 82 * 83 * @since 18 84 */ 85 typedef struct OH_RDB_TransOptions OH_RDB_TransOptions; 86 87 /** 88 * @brief Define the OH_Rdb_Transaction structure type. 89 * 90 * @since 18 91 */ 92 typedef struct OH_Rdb_Transaction OH_Rdb_Transaction; 93 94 /** 95 * @brief Creates an OH_RDB_TransOptions instance object. 96 * 97 * @return Returns a pointer to OH_RDB_TransOptions instance when the execution is successful. 98 * Otherwise, nullptr is returned. The memory must be released through the OH_RdbTrans_DestroyOptions 99 * interface after the use is complete. 100 * @see OH_RdbTrans_DestroyOptions. 101 * @since 18 102 */ 103 OH_RDB_TransOptions *OH_RdbTrans_CreateOptions(void); 104 105 /** 106 * @brief Destroys an OH_RDB_TransOptions instance object. 107 * 108 * @param opitons Represents a pointer to an instance of OH_RDB_TransOptions. 109 * @return Returns the error code. 110 * Returns {@link RDB_OK} if the execution is successful. 111 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 112 * @since 18 113 */ 114 int OH_RdbTrans_DestroyOptions(OH_RDB_TransOptions *opitons); 115 116 /** 117 * @brief Sets integer data to the opitons object. 118 * 119 * @param opitons Represents a pointer to an instance of OH_RDB_TransOptions. 120 * @param type Represents relation database transaction type. 121 * @return Returns the error code. 122 * Returns {@link RDB_OK} if the execution is successful. 123 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 124 * @since 18 125 */ 126 int OH_RdbTransOption_SetType(OH_RDB_TransOptions *opitons, OH_RDB_TransType type); 127 128 /** 129 * @brief Commits a transaction of a relational database. 130 * 131 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 132 * @return Returns the status code of the execution. 133 * Returns {@link RDB_OK} if the execution is successful. 134 * Returns {@link RDB_E_ERROR} database common error. 135 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 136 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 137 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 138 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 139 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 140 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 141 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 142 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: SQLite: Attempt to write a readonly database. 143 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 144 * @since 18 145 */ 146 int OH_RdbTrans_Commit(OH_Rdb_Transaction *trans); 147 148 /** 149 * @brief Roll back a transaction of a relational database. 150 * 151 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 152 * @return Returns the status code of the execution. 153 * Returns {@link RDB_OK} if the execution is successful. 154 * Returns {@link RDB_E_ERROR} database common error. 155 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 156 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 157 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 158 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 159 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 160 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 161 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 162 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 163 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 164 * @since 18 165 */ 166 int OH_RdbTrans_Rollback(OH_Rdb_Transaction *trans); 167 168 /** 169 * @brief Inserts a row of data into the target table. 170 * 171 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 172 * @param table Represents the target table. 173 * @param row Represents the row data to be inserted into the table. 174 * @param rowId Represents row line number when insert successfully. 175 * @return Returns the status code of the execution. 176 * Returns {@link RDB_OK} if the execution is successful. 177 * Returns {@link RDB_E_ERROR} database common error. 178 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 179 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 180 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 181 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 182 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 183 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 184 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 185 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 186 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 187 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 188 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 189 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 190 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 191 192 * @since 18 193 */ 194 int OH_RdbTrans_Insert(OH_Rdb_Transaction *trans, const char *table, const OH_VBucket *row, int64_t *rowId); 195 196 /** 197 * @brief Inserts a batch of data into the target table. 198 * 199 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 200 * @param table Represents the target table. 201 * @param rows Represents the rows data to be inserted into the table. 202 * @param resolution Represents the resolution when conflict occurs. 203 * @param changes Represents the number of successful insertions. 204 * @return Returns the status code of the execution. 205 * Returns {@link RDB_OK} if the execution is successful. 206 * Returns {@link RDB_E_ERROR} database common error. 207 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 208 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 209 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 210 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 211 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 212 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 213 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 214 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 215 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 216 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 217 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 218 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 219 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 220 * Returns {@link RDB_E_SQLITE_CONSTRAINT} SQLite: Abort due to constraint violation. 221 * @since 18 222 */ 223 int OH_RdbTrans_BatchInsert(OH_Rdb_Transaction *trans, const char *table, const OH_Data_VBuckets *rows, 224 Rdb_ConflictResolution resolution, int64_t *changes); 225 226 /** 227 * @brief Updates data in the database based on specified conditions. 228 * 229 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 230 * @param row Represents the row data to be updated into the table. 231 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 232 * @param changes Represents the number of successful insertions. 233 * @return Returns the status code of the execution. 234 * Returns {@link RDB_OK} if the execution is successful. 235 * Returns {@link RDB_E_ERROR} database common error. 236 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 237 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 238 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 239 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 240 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 241 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 242 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 243 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 244 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 245 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 246 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 247 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 248 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 249 * @since 18 250 */ 251 int OH_RdbTrans_Update(OH_Rdb_Transaction *trans, const OH_VBucket *row, const OH_Predicates *predicates, 252 int64_t *changes); 253 254 /** 255 * @brief Deletes data from the database based on specified conditions 256 * 257 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 258 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 259 * @param changes Represents the number of successfully Deleted. 260 * @return Returns the status code of the execution. 261 * Returns {@link RDB_OK} if the execution is successful. 262 * Returns {@link RDB_E_ERROR} database common error. 263 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 264 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 265 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 266 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 267 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 268 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 269 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 270 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 271 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 272 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 273 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 274 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 275 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 276 * @since 18 277 */ 278 int OH_RdbTrans_Delete(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, int64_t *changes); 279 280 /** 281 * @brief Queries data in the database based on specified conditions. 282 * 283 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 284 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 285 * @param columns Represents the columns to query. If the value is empty array, the query applies to all columns. 286 * @param len Represents the number of columns elements. 287 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 288 * If database has closed or the database does not respond, nullptr is returned. 289 * @since 18 290 */ 291 OH_Cursor *OH_RdbTrans_Query(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, const char *columns[], 292 int len); 293 294 /** 295 * @brief Queries data in the database based on SQL statement. 296 * 297 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 298 * @param sql Represents the SQL statement to execute. 299 * @param args Represents a pointer to an instance of OH_Data_Values and it is the selection arguments. 300 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 301 * If database has closed or the database does not respond, nullptr is returned. 302 * @since 18 303 */ 304 OH_Cursor *OH_RdbTrans_QuerySql(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args); 305 306 /** 307 * @brief Executes an SQL statement that contains specified parameters. 308 * 309 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 310 * @param sql Represents the SQL statement to execute. 311 * @param args Represents the values of the parameters in the SQL statement. 312 * @param result Represents a pointer to OH_Data_Value instance when the execution is successful. 313 * The memory must be released through the OH_Value_Destroy interface after the use is complete. 314 * @return Returns the status code of the execution. 315 * Returns {@link RDB_OK} if the execution is successful. 316 * Returns {@link RDB_E_ERROR} database common error. 317 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 318 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 319 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 320 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 321 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 322 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 323 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 324 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 325 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 326 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 327 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 328 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 329 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 330 * @see OH_Value_Destroy. 331 * @since 18 332 */ 333 int OH_RdbTrans_Execute(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args, OH_Data_Value **result); 334 335 /** 336 * @brief Destroys an OH_Rdb_Transaction instance object. 337 * 338 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 339 * @return Returns the error code. 340 * Returns {@link RDB_OK} if the execution is successful. 341 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 342 * @since 18 343 */ 344 int OH_RdbTrans_Destroy(OH_Rdb_Transaction *trans); 345 346 #ifdef __cplusplus 347 }; 348 #endif 349 #endif // OH_RDB_TRANSACTION_H 350 /** @} */ 351