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 opitons 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 *opitons); 113 114 /** 115 * @brief Sets integer data to the opitons object. 116 * 117 * @param opitons 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 *opitons, 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 batch of data into the target table. 196 * 197 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 198 * @param table Represents the target table. 199 * @param rows Represents the rows data to be inserted into the table. 200 * @param resolution Represents the resolution when conflict occurs. 201 * @param changes Represents the number of successful insertions. 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 16 220 */ 221 int OH_RdbTrans_BatchInsert(OH_Rdb_Transaction *trans, const char *table, const OH_Data_VBuckets *rows, 222 Rdb_ConflictResolution resolution, int64_t *changes); 223 224 /** 225 * @brief Updates data in the database based on specified conditions. 226 * 227 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 228 * @param row Represents the row data to be updated into the table. 229 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 230 * @param changes Represents the number of successful insertions. 231 * @return Returns the status code of the execution. 232 * Returns {@link RDB_OK} if the execution is successful. 233 * Returns {@link RDB_E_ERROR} database common error. 234 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 235 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 236 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 237 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 238 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 239 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 240 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 241 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 242 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 243 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 244 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 245 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 246 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 247 * @since 16 248 */ 249 int OH_RdbTrans_Update(OH_Rdb_Transaction *trans, const OH_VBucket *row, const OH_Predicates *predicates, 250 int64_t *changes); 251 252 /** 253 * @brief Deletes data from the database based on specified conditions 254 * 255 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 256 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 257 * @param changes Represents the number of successfully Deleted. 258 * @return Returns the status code of the execution. 259 * Returns {@link RDB_OK} if the execution is successful. 260 * Returns {@link RDB_E_ERROR} database common error. 261 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 262 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 263 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 264 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 265 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 266 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 267 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 268 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 269 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 270 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 271 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 272 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 273 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 274 * @since 16 275 */ 276 int OH_RdbTrans_Delete(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, int64_t *changes); 277 278 /** 279 * @brief Queries data in the database based on specified conditions. 280 * 281 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 282 * @param predicates Represents the specified update condition by the instance object of OH_Predicates. 283 * @param columns Represents the columns to query. If the value is empty array, the query applies to all columns. 284 * @param len Represents the number of columns elements. 285 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 286 * If database has closed or the database does not respond, nullptr is returned. 287 * @since 16 288 */ 289 OH_Cursor *OH_RdbTrans_Query(OH_Rdb_Transaction *trans, const OH_Predicates *predicates, const char *columns[], 290 int len); 291 292 /** 293 * @brief Queries data in the database based on SQL statement. 294 * 295 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 296 * @param sql Represents the SQL statement to execute. 297 * @param args Represents a pointer to an instance of OH_Data_Values and it is the selection arguments. 298 * @return If the operation is successful, a pointer to the instance of the OH_Cursor structure is returned. 299 * If database has closed or the database does not respond, nullptr is returned. 300 * @since 16 301 */ 302 OH_Cursor *OH_RdbTrans_QuerySql(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args); 303 304 /** 305 * @brief Executes an SQL statement that contains specified parameters. 306 * 307 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 308 * @param sql Represents the SQL statement to execute. 309 * @param args Represents the values of the parameters in the SQL statement. 310 * @param result Represents a pointer to OH_Data_Value instance when the execution is successful. 311 * The memory must be released through the OH_Value_Destroy interface after the use is complete. 312 * @return Returns the status code of the execution. 313 * Returns {@link RDB_OK} if the execution is successful. 314 * Returns {@link RDB_E_ERROR} database common error. 315 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 316 * Returns {@link RDB_E_ALREADY_CLOSED} database already closed. 317 * Returns {@link RDB_E_WAL_SIZE_OVER_LIMIT} the WAL file size over default limit. 318 * Returns {@link RDB_E_SQLITE_FULL} SQLite: The database is full. 319 * Returns {@link RDB_E_SQLITE_CORRUPT} database corrupted. 320 * Returns {@link RDB_E_SQLITE_PERM} SQLite: Access permission denied. 321 * Returns {@link RDB_E_SQLITE_BUSY} SQLite: The database file is locked. 322 * Returns {@link RDB_E_SQLITE_LOCKED} SQLite: A table in the database is locked. 323 * Returns {@link RDB_E_SQLITE_NOMEM} SQLite: The database is out of memory. 324 * Returns {@link RDB_E_SQLITE_READONLY} SQLite: Attempt to write a readonly database. 325 * Returns {@link RDB_E_SQLITE_IOERR} SQLite: Some kind of disk I/O error occurred. 326 * Returns {@link RDB_E_SQLITE_TOO_BIG} SQLite: TEXT or BLOB exceeds size limit. 327 * Returns {@link RDB_E_SQLITE_MISMATCH} SQLite: Data type mismatch. 328 * @see OH_Value_Destroy. 329 * @since 16 330 */ 331 int OH_RdbTrans_Execute(OH_Rdb_Transaction *trans, const char *sql, const OH_Data_Values *args, OH_Data_Value **result); 332 333 /** 334 * @brief Destroys an OH_Rdb_Transaction instance object. 335 * 336 * @param trans Represents a pointer to an instance of OH_Rdb_Transaction. 337 * @return Returns the error code. 338 * Returns {@link RDB_OK} if the execution is successful. 339 * Returns {@link RDB_E_INVALID_ARGS} if invalid input parameter. 340 * @since 16 341 */ 342 int OH_RdbTrans_Destroy(OH_Rdb_Transaction *trans); 343 344 #ifdef __cplusplus 345 }; 346 #endif 347 #endif // OH_RDB_TRANSACTION_H 348 /** @} */ 349