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 /** 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_predicates.h 30 * 31 * @brief Declared predicate related functions and enumerations. 32 * 33 * @kit ArkData 34 * @library libnative_rdb_ndk.so 35 * @syscap SystemCapability.DistributedDataManager.RelationalStore.Core 36 * @since 10 37 */ 38 39 #ifndef OH_PREDICATES_H 40 #define OH_PREDICATES_H 41 42 #ifdef __cplusplus 43 #include <cstdint> 44 #else 45 #include <stdint.h> 46 #endif 47 48 #include <stddef.h> 49 #include "database/rdb/oh_value_object.h" 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 /** 56 * @brief Result set sort type. 57 * 58 * @since 10 59 */ 60 typedef enum OH_OrderType { 61 /** 62 * Ascend order. 63 */ 64 ASC = 0, 65 /** 66 * Descend order. 67 */ 68 DESC = 1, 69 } OH_OrderType; 70 71 /** 72 * @brief Define the OH_Predicates structure type. 73 * 74 * @since 10 75 */ 76 typedef struct OH_Predicates OH_Predicates; 77 78 /** 79 * @brief Define the OH_Predicates structure type. 80 * 81 * @since 10 82 */ 83 struct OH_Predicates { 84 /** 85 * The id used to uniquely identify the OH_Predicates struct. 86 */ 87 int64_t id; 88 89 /** 90 * @brief Function pointer. Restricts the value of the field to be equal to the specified value to the predicates. 91 * 92 * This method is similar to = of the SQL statement. 93 * 94 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 95 * @param field Indicates the column name in the database table. 96 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 97 * @return Returns the self. 98 * @see OH_Predicates, OH_VObject. 99 * @since 10 100 */ 101 OH_Predicates *(*equalTo)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 102 103 /** 104 * @brief Function pointer. 105 * Restricts the value of the field to be not equal to the specified value to the predicates. 106 * 107 * This method is similar to != of the SQL statement. 108 * 109 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 110 * @param field Indicates the column name in the database table. 111 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 112 * @return Returns the self. 113 * @see OH_Predicates, OH_VObject. 114 * @since 10 115 */ 116 OH_Predicates *(*notEqualTo)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 117 118 /** 119 * @brief Function pointer. Add left parenthesis to predicate. 120 * 121 * This method is similar to ( of the SQL statement. 122 * 123 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 124 * @return Returns the self. 125 * @see OH_Predicates. 126 * @since 10 127 */ 128 OH_Predicates *(*beginWrap)(OH_Predicates *predicates); 129 130 /** 131 * @brief Function pointer. Add right parenthesis to predicate. 132 * 133 * This method is similar to ) of the SQL statement. 134 * 135 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 136 * @return Returns the self. 137 * @see OH_Predicates. 138 * @since 10 139 */ 140 OH_Predicates *(*endWrap)(OH_Predicates *predicates); 141 142 /** 143 * @brief Function pointer. Adds an or condition to the predicates. 144 * 145 * This method is similar to OR of the SQL statement. 146 * 147 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 148 * @return Returns the self. 149 * @see OH_Predicates. 150 * @since 10 151 */ 152 OH_Predicates *(*orOperate)(OH_Predicates *predicates); 153 154 /** 155 * @brief Function pointer. Adds an and condition to the predicates. 156 * 157 * This method is similar to AND of the SQL statement. 158 * 159 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 160 * @return Returns the self. 161 * @see OH_Predicates. 162 * @since 10 163 */ 164 OH_Predicates *(*andOperate)(OH_Predicates *predicates); 165 166 /** 167 * @brief Function pointer. Restricts the value of the field which is null to the predicates. 168 * 169 * This method is similar to IS NULL of the SQL statement. 170 * 171 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 172 * @param field Indicates the column name in the database table. 173 * @return Returns the self. 174 * @see OH_Predicates. 175 * @since 10 176 */ 177 OH_Predicates *(*isNull)(OH_Predicates *predicates, const char *field); 178 179 /** 180 * @brief Function pointer. Restricts the value of the field which is not null to the predicates. 181 * 182 * This method is similar to IS NOT NULL of the SQL statement. 183 * 184 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 185 * @param field Indicates the column name in the database table. 186 * @return Returns the self. 187 * @see OH_Predicates. 188 * @since 10 189 */ 190 OH_Predicates *(*isNotNull)(OH_Predicates *predicates, const char *field); 191 192 /** 193 * @brief Function pointer. Restricts the value of the field to be like the specified value to the predicates. 194 * 195 * This method is similar to LIKE of the SQL statement. 196 * 197 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 198 * @param field Indicates the column name in the database table. 199 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 200 * @return Returns the self. 201 * @see OH_Predicates, OH_VObject. 202 * @since 10 203 */ 204 OH_Predicates *(*like)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 205 206 /** 207 * @brief Function pointer. Restricts the value of the field to be between the specified value to the predicates. 208 * 209 * This method is similar to BETWEEN of the SQL statement. 210 * 211 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 212 * @param field Indicates the column name in the database table. 213 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 214 * @return Returns the self. 215 * @see OH_Predicates, OH_VObject. 216 * @since 10 217 */ 218 OH_Predicates *(*between)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 219 220 /** 221 * @brief Function pointer. 222 * Restricts the value of the field to be not between the specified value to the predicates. 223 * 224 * This method is similar to NOT BETWEEN of the SQL statement. 225 * 226 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 227 * @param field Indicates the column name in the database table. 228 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 229 * @return Returns the self. 230 * @see OH_Predicates, OH_VObject. 231 * @since 10 232 */ 233 OH_Predicates *(*notBetween)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 234 235 /** 236 * @brief Function pointer. 237 * Restricts the value of the field to be greater than the specified value to the predicates. 238 * 239 * This method is similar to > of the SQL statement. 240 * 241 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 242 * @param field Indicates the column name in the database table. 243 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 244 * @return Returns the self. 245 * @see OH_Predicates, OH_VObject. 246 * @since 10 247 */ 248 OH_Predicates *(*greaterThan)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 249 250 /** 251 * @brief Function pointer. 252 * Restricts the value of the field to be less than the specified value to the predicates. 253 * 254 * This method is similar to < of the SQL statement. 255 * 256 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 257 * @param field Indicates the column name in the database table. 258 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 259 * @return Returns the self. 260 * @see OH_Predicates, OH_VObject. 261 * @since 10 262 */ 263 OH_Predicates *(*lessThan)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 264 265 /** 266 * @brief Function pointer. 267 * Restricts the value of the field to be greater than or equal to the specified value to the predicates. 268 * 269 * This method is similar to >= of the SQL statement. 270 * 271 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 272 * @param field Indicates the column name in the database table. 273 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 274 * @return Returns the self. 275 * @see OH_Predicates, OH_VObject. 276 * @since 10 277 */ 278 OH_Predicates *(*greaterThanOrEqualTo)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 279 280 /** 281 * @brief Function pointer. 282 * Restricts the value of the field to be less than or equal to the specified value to the predicates. 283 * 284 * This method is similar to <= of the SQL statement. 285 * 286 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 287 * @param field Indicates the column name in the database table. 288 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 289 * @return Returns the self. 290 * @see OH_Predicates, OH_VObject. 291 * @since 10 292 */ 293 OH_Predicates *(*lessThanOrEqualTo)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 294 295 /** 296 * @brief Function pointer. Restricts the ascending or descending order of the return list. 297 * When there are several orders, the one close to the head has the highest priority. 298 * 299 * This method is similar ORDER BY the SQL statement. 300 * 301 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 302 * @param field Indicates the column name in the database table. 303 * @param type Indicates the sort {@link OH_OrderType} type. 304 * @return Returns the self. 305 * @see OH_Predicates, OH_OrderType. 306 * @since 10 307 */ 308 OH_Predicates *(*orderBy)(OH_Predicates *predicates, const char *field, OH_OrderType type); 309 310 /** 311 * @brief Function pointer. Configure predicates to filter duplicate records and retain only one of them. 312 * 313 * This method is similar DISTINCT the SQL statement. 314 * 315 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 316 * @return Returns the self. 317 * @see OH_Predicates. 318 * @since 10 319 */ 320 OH_Predicates *(*distinct)(OH_Predicates *predicates); 321 322 /** 323 * @brief Function pointer. Predicate for setting the maximum number of data records. 324 * 325 * This method is similar LIMIT the SQL statement. 326 * 327 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 328 * @param value Indicates the maximum number of records. 329 * @return Returns the self. 330 * @see OH_Predicates. 331 * @since 10 332 */ 333 OH_Predicates *(*limit)(OH_Predicates *predicates, unsigned int value); 334 335 /** 336 * @brief Function pointer. Configure the predicate to specify the starting position of the returned result. 337 * 338 * This method is similar OFFSET the SQL statement. 339 * 340 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 341 * @param rowOffset Indicates the number of rows to offset from the beginning. The value is a positive integer. 342 * @return Returns the self. 343 * @see OH_Predicates. 344 * @since 10 345 */ 346 OH_Predicates *(*offset)(OH_Predicates *predicates, unsigned int rowOffset); 347 348 /** 349 * @brief Function pointer. Configure predicates to group query results by specified columns. 350 * 351 * This method is similar GROUP BY the SQL statement. 352 * 353 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 354 * @param fields Indicates the column names that the grouping depends on. 355 * @param length Indicates the length of fields. 356 * @return Returns the self. 357 * @see OH_Predicates. 358 * @since 10 359 */ 360 OH_Predicates *(*groupBy)(OH_Predicates *predicates, char const *const *fields, int length); 361 362 /** 363 * @brief Function pointer. 364 * Configure the predicate to match the specified field and the value within the given array range. 365 * 366 * This method is similar IN the SQL statement. 367 * 368 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 369 * @param field Indicates the column name in the database table. 370 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 371 * @return Returns the self. 372 * @see OH_Predicates, OH_VObject. 373 * @since 10 374 */ 375 OH_Predicates *(*in)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 376 377 /** 378 * @brief Function pointer. 379 * Configure the predicate to match the specified field and the value not within the given array range. 380 * 381 * This method is similar NOT IN the SQL statement. 382 * 383 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 384 * @param field Indicates the column name in the database table. 385 * @param valueObject Represents a pointer to an {@link OH_VObject} instance. 386 * @return Returns the self. 387 * @see OH_Predicates, OH_VObject. 388 * @since 10 389 */ 390 OH_Predicates *(*notIn)(OH_Predicates *predicates, const char *field, OH_VObject *valueObject); 391 392 /** 393 * @brief Function pointer. Initialize OH_Predicates object. 394 * 395 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 396 * @return Returns the self. 397 * @see OH_Predicates. 398 * @since 10 399 */ 400 OH_Predicates *(*clear)(OH_Predicates *predicates); 401 402 /** 403 * @brief Destroy the {@link OH_Predicates} object and reclaim the memory occupied by the object. 404 * 405 * @param predicates Represents a pointer to an {@link OH_Predicates} instance. 406 * @return Returns the status code of the execution.. 407 * @see OH_Predicates. 408 * @since 10 409 */ 410 int (*destroy)(OH_Predicates *predicates); 411 }; 412 413 #ifdef __cplusplus 414 }; 415 #endif 416 417 /** @} */ 418 419 #endif // OH_PREDICATES_H 420