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