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