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
46extern "C" {
47#endif
48
49/**
50 * @brief Result set sort type.
51 *
52 * @since 10
53 */
54typedef 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 */
70typedef 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