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 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Describe the security level of the database. 51 * 52 * @since 10 53 */ 54 typedef enum OH_Rdb_SecurityLevel { 55 /** 56 * @brief Low-level security. Data leaks have a minor impact. 57 */ 58 S1 = 1, 59 /** 60 * @brief Medium-level security. Data leaks have a major impact. 61 */ 62 S2, 63 /** 64 * @brief High-level security. Data leaks have a severe impact. 65 */ 66 S3, 67 /** 68 * @brief Critical-level security. Data leaks have a critical impact. 69 */ 70 S4 71 } OH_Rdb_SecurityLevel; 72 73 /** 74 * @brief Manages relational database configurations. 75 * 76 * @since 10 77 */ 78 #pragma pack(1) 79 typedef struct { 80 /** 81 * Indicates the size of the {@link OH_Rdb_Config}. It is mandatory. 82 */ 83 int selfSize; 84 /** 85 * Indicates the directory of the database. 86 */ 87 const char *dataBaseDir; 88 /** 89 * Indicates the name of the database. 90 */ 91 const char *storeName; 92 /** 93 * Indicates the bundle name of the application. 94 */ 95 const char *bundleName; 96 /** 97 * Indicates the module name of the application. 98 */ 99 const char *moduleName; 100 /** 101 * Indicates whether the database is encrypted. 102 */ 103 bool isEncrypt; 104 /** 105 * Indicates the security level {@link OH_Rdb_SecurityLevel} of the database. 106 */ 107 int securityLevel; 108 } OH_Rdb_Config; 109 #pragma pack() 110 111 /** 112 * @brief Define OH_Rdb_Store type. 113 * 114 * @since 10 115 */ 116 typedef struct { 117 /** 118 * The id used to uniquely identify the OH_Rdb_Store struct. 119 */ 120 int64_t id; 121 } OH_Rdb_Store; 122 123 /** 124 * @brief Creates an {@link OH_VObject} instance. 125 * 126 * @return If the creation is successful, a pointer to the instance of the @link OH_VObject} structure is returned, 127 * otherwise NULL is returned. 128 * @see OH_VObject. 129 * @since 10 130 */ 131 OH_VObject *OH_Rdb_CreateValueObject(); 132 133 /** 134 * @brief Creates an {@link OH_VBucket} object. 135 * 136 * @return If the creation is successful, a pointer to the instance of the @link OH_VBucket} structure is returned, 137 * otherwise NULL is returned. 138 * @see OH_VBucket. 139 * @since 10 140 */ 141 OH_VBucket *OH_Rdb_CreateValuesBucket(); 142 143 /** 144 * @brief Creates an {@link OH_Predicates} instance. 145 * 146 * @param table Indicates the table name. 147 * @return If the creation is successful, a pointer to the instance of the @link OH_Predicates} structure is returned, 148 * otherwise NULL is returned. 149 * @see OH_Predicates. 150 * @since 10 151 */ 152 OH_Predicates *OH_Rdb_CreatePredicates(const char *table); 153 154 /** 155 * @brief Obtains an RDB store. 156 * 157 * You can set parameters of the RDB store as required. In general, 158 * this method is recommended to obtain a rdb store. 159 * 160 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 161 * Indicates the configuration of the database related to this RDB store. 162 * @param errCode This parameter is the output parameter, 163 * and the execution status of a function is written to this variable. 164 * @return If the creation is successful, a pointer to the instance of the @link OH_Rdb_Store} structure is returned, 165 * otherwise NULL is returned. 166 * @see OH_Rdb_Config, OH_Rdb_Store. 167 * @since 10 168 */ 169 OH_Rdb_Store *OH_Rdb_GetOrOpen(const OH_Rdb_Config *config, int *errCode); 170 171 /** 172 * @brief Close the {@link OH_Rdb_Store} object and reclaim the memory occupied by the object. 173 * 174 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 175 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 176 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 177 * @see OH_Rdb_Store, OH_Rdb_ErrCode. 178 * @since 10 179 */ 180 int OH_Rdb_CloseStore(OH_Rdb_Store *store); 181 182 /** 183 * @brief Deletes the database with a specified path. 184 * 185 * @param config Represents a pointer to an {@link OH_Rdb_Config} instance. 186 * Indicates the configuration of the database related to this RDB store. 187 * @return Returns the status code of the execution. Successful execution returns RDB_OK, 188 * while failure returns a specific error code. Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 189 * @see OH_Rdb_ErrCode. 190 * @since 10 191 */ 192 int OH_Rdb_DeleteStore(const OH_Rdb_Config *config); 193 194 /** 195 * @brief Inserts a row of data into the target table. 196 * 197 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 198 * @param table Indicates the target table. 199 * @param valuesBucket Indicates the row of data {@link OH_VBucket} to be inserted into the table. 200 * @return Returns the rowId if success, returns a specific error code. 201 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 202 * @see OH_Rdb_Store, OH_VBucket, OH_Rdb_ErrCode. 203 * @since 10 204 */ 205 int OH_Rdb_Insert(OH_Rdb_Store *store, const char *table, OH_VBucket *valuesBucket); 206 207 /** 208 * @brief Updates data in the database based on specified conditions. 209 * 210 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 211 * @param valuesBucket Indicates the row of data {@link OH__VBucket} to be updated in the database 212 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 213 * Indicates the specified update condition. 214 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 215 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 216 * @see OH_Rdb_Store, OH_Bucket, OH_Predicates, OH_Rdb_ErrCode. 217 * @since 10 218 */ 219 int OH_Rdb_Update(OH_Rdb_Store *store, OH_VBucket *valuesBucket, OH_Predicates *predicates); 220 221 /** 222 * @brief Deletes data from the database based on specified conditions. 223 * 224 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 225 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 226 * Indicates the specified delete condition. 227 * @return Returns the number of rows changed if success, otherwise, returns a specific error code. 228 * Specific error codes can be referenced {@link OH_Rdb_ErrCode}. 229 * @see OH_Rdb_Store, OH_Predicates, OH_Rdb_ErrCode. 230 * @since 10 231 */ 232 int OH_Rdb_Delete(OH_Rdb_Store *store, OH_Predicates *predicates); 233 234 /** 235 * @brief Queries data in the database based on specified conditions. 236 * 237 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 238 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 239 * Indicates the specified query condition. 240 * @param columnNames Indicates the columns to query. If the value is empty array, the query applies to all columns. 241 * @param length Indicates the length of columnNames. 242 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned, 243 * otherwise NULL is returned. 244 * @see OH_Rdb_Store, OH_Predicates, OH_Cursor. 245 * @since 10 246 */ 247 OH_Cursor *OH_Rdb_Query(OH_Rdb_Store *store, OH_Predicates *predicates, const char *const *columnNames, int length); 248 249 /** 250 * @brief Executes an SQL statement. 251 * 252 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 253 * @param sql Indicates the SQL statement to execute. 254 * @return Returns the status code of the execution. 255 * @see OH_Rdb_Store. 256 * @since 10 257 */ 258 int OH_Rdb_Execute(OH_Rdb_Store *store, const char *sql); 259 260 /** 261 * @brief Queries data in the database based on an SQL statement. 262 * 263 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 264 * @param sql Indicates the SQL statement to execute. 265 * @return If the query is successful, a pointer to the instance of the @link OH_Cursor} structure is returned, 266 * otherwise NULL is returned. 267 * @see OH_Rdb_Store. 268 * @since 10 269 */ 270 OH_Cursor *OH_Rdb_ExecuteQuery(OH_Rdb_Store *store, const char *sql); 271 272 /** 273 * @brief Begins a transaction in EXCLUSIVE mode. 274 * 275 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 276 * @return Returns the status code of the execution. 277 * @see OH_Rdb_Store. 278 * @since 10 279 */ 280 int OH_Rdb_BeginTransaction(OH_Rdb_Store *store); 281 282 /** 283 * @brief Rolls back a transaction in EXCLUSIVE mode. 284 * 285 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 286 * @return Returns the status code of the execution. 287 * @see OH_Rdb_Store. 288 * @since 10 289 */ 290 int OH_Rdb_RollBack(OH_Rdb_Store *store); 291 292 /** 293 * @brief Commits a transaction in EXCLUSIVE mode. 294 * 295 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 296 * @return Returns the status code of the execution. 297 * @see OH_Rdb_Store. 298 * @since 10 299 */ 300 int OH_Rdb_Commit(OH_Rdb_Store *store); 301 302 /** 303 * @brief Backs up a database on specified path. 304 * 305 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 306 * @param databasePath Indicates the database file path. 307 * @return Returns the status code of the execution. 308 * @see OH_Rdb_Store. 309 * @since 10 310 */ 311 int OH_Rdb_Backup(OH_Rdb_Store *store, const char *databasePath); 312 313 /** 314 * @brief Restores a database from a specified database file. 315 * 316 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 317 * @param databasePath Indicates the database file path. 318 * @return Returns the status code of the execution. 319 * @see OH_Rdb_Store. 320 * @since 10 321 */ 322 int OH_Rdb_Restore(OH_Rdb_Store *store, const char *databasePath); 323 324 /** 325 * @brief Gets the version of a database. 326 * 327 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 328 * @param version Indicates the version number. 329 * @return Returns the status code of the execution. 330 * @see OH_Rdb_Store. 331 * @since 10 332 */ 333 int OH_Rdb_GetVersion(OH_Rdb_Store *store, int *version); 334 335 /** 336 * @brief Sets the version of a database. 337 * 338 * @param store Represents a pointer to an {@link OH_Rdb_Store} instance. 339 * @param version Indicates the version number. 340 * @return Returns the status code of the execution. 341 * @see OH_Rdb_Store. 342 * @since 10 343 */ 344 int OH_Rdb_SetVersion(OH_Rdb_Store *store, int version); 345 346 #ifdef __cplusplus 347 }; 348 #endif 349 350 #endif // RELATIONAL_STORE_H 351