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