1 /* 2 * Copyright (C) 2009 - 2010 Murray Cumming <murrayc@murrayc.com> 3 * Copyright (C) 2009 - 2011 Vivien Malerba <malerba@gnome-db.org> 4 * Copyright (C) 2010 Jonh Wendell <jwendell@gnome.org> 5 * Copyright (C) 2011 Daniel Espinosa <despinosa@src.gnome.org> 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, write to the 19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 20 * Boston, MA 02110-1301, USA. 21 */ main(int,char **)22 23 #ifndef __GDA_SQL_BUILDER_H_ 24 #define __GDA_SQL_BUILDER_H_ 25 26 #include <glib-object.h> 27 #include <sql-parser/gda-sql-statement.h> 28 29 G_BEGIN_DECLS 30 31 #define GDA_TYPE_SQL_BUILDER (gda_sql_builder_get_type()) 32 #define GDA_SQL_BUILDER(obj) G_TYPE_CHECK_INSTANCE_CAST (obj, gda_sql_builder_get_type(), GdaSqlBuilder) 33 #define GDA_SQL_BUILDER_CLASS(klass) G_TYPE_CHECK_CLASS_CAST (klass, gda_sql_builder_get_type (), GdaSqlBuilderClass) 34 #define GDA_IS_SQL_BUILDER(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, gda_sql_builder_get_type ()) 35 #define GDA_SQL_BUILDER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GDA_TYPE_SQL_BUILDER, GdaSqlBuilderClass)) 36 37 typedef struct _GdaSqlBuilder GdaSqlBuilder; 38 typedef struct _GdaSqlBuilderClass GdaSqlBuilderClass; 39 typedef struct _GdaSqlBuilderPrivate GdaSqlBuilderPrivate; 40 41 /* error reporting */ 42 extern GQuark gda_sql_builder_error_quark (void); 43 #define GDA_SQL_BUILDER_ERROR gda_sql_builder_error_quark () 44 45 typedef enum { 46 GDA_SQL_BUILDER_WRONG_TYPE_ERROR, 47 GDA_SQL_BUILDER_MISUSE_ERROR 48 } GdaSqlBuilderError; 49 50 51 /* struct for the object's data */ 52 struct _GdaSqlBuilder 53 { 54 GObject object; 55 GdaSqlBuilderPrivate *priv; 56 }; 57 58 /* struct for the object's class */ 59 struct _GdaSqlBuilderClass 60 { 61 GObjectClass parent_class; 62 63 /*< private >*/ 64 /* Padding for future expansion */ 65 void (*_gda_reserved1) (void); 66 void (*_gda_reserved2) (void); 67 void (*_gda_reserved3) (void); 68 void (*_gda_reserved4) (void); 69 }; 70 71 typedef guint GdaSqlBuilderId; 72 73 /** 74 * SECTION:gda-sql-builder 75 * @short_description: Factory object for statements 76 * @title: GdaSqlBuilder 77 * @stability: Stable 78 * @see_also: #GdaSqlParser, #GdaSqlStatement and #GdaStatement 79 * 80 * The #GdaSqlBuilder can be used to build a #GdaStatement from its structural description, 81 * much in the same way a #GdaSqlParser can be used to build a #GdaStatement from an SQL 82 * string. 83 * 84 * The #GdaSqlBuilder internally constructs a #GdaSqlStatement and uses it when requested to produce 85 * a #GdaStatement (see gda_sql_builder_get_statement()), or a #GdaSqlStatement (see 86 * gda_sql_builder_get_sql_statement()). 87 * 88 * During the building process, some pieces of the statement are constructed, and assembled into the 89 * final statement. Each of these pieces can be reused anytime in the same #GdaSqlBuilder object, and each 90 * is identified using a single unsigned integer ID. That ID is dynamically allocated by the object. 91 * 92 * The following example builds the equivalent of the <![CDATA["name='joe' AND age >= ##ageparam::int"]]> expression: 93 * <programlisting><![CDATA[ 94 *GdaSqlBuilder *b=... 95 *guint id_field = gda_sql_builder_add_id (b, "name"); // build the "name" SQL identifier 96 *guint id_value = gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "joe"); // 'joe' expression 97 *guint id_cond1 = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_value, 0); // "name='joe'" 98 * 99 *guint id_cond2 = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_GT, 100 * gda_sql_builder_add_id (b, "age"), // build the "age" SQL identifier 101 * gda_sql_builder_add_param (b, "ageparam", G_TYPE_INT, FALSE), // parameter 102 * 0); 103 *guint id_cond_and = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_AND, id_cond1, id_cond2, 0); // whole expression 104 *]]></programlisting> 105 * 106 * For more examples, see the <link linkend="howto-sqlbuilder">Build statements without using a parser</link> section. 107 */ 108 109 GType gda_sql_builder_get_type (void) G_GNUC_CONST; 110 GdaSqlBuilder *gda_sql_builder_new (GdaSqlStatementType stmt_type); 111 GdaStatement *gda_sql_builder_get_statement (GdaSqlBuilder *builder, GError **error); 112 GdaSqlStatement *gda_sql_builder_get_sql_statement (GdaSqlBuilder *builder); 113 114 /* Expression API */ 115 GdaSqlBuilderId gda_sql_builder_add_id (GdaSqlBuilder *builder, const gchar *str); 116 GdaSqlBuilderId gda_sql_builder_add_field_id (GdaSqlBuilder *builder, const gchar *field_name, const gchar *table_name); 117 GdaSqlBuilderId gda_sql_builder_add_expr (GdaSqlBuilder *builder, GdaDataHandler *dh, GType type, ...); 118 GdaSqlBuilderId gda_sql_builder_add_expr_value (GdaSqlBuilder *builder, GdaDataHandler *dh, const GValue *value); 119 GdaSqlBuilderId gda_sql_builder_add_param (GdaSqlBuilder *builder, const gchar *param_name, GType type, gboolean nullok); 120 121 GdaSqlBuilderId gda_sql_builder_add_cond (GdaSqlBuilder *builder, GdaSqlOperatorType op, 122 GdaSqlBuilderId op1, GdaSqlBuilderId op2, GdaSqlBuilderId op3); 123 GdaSqlBuilderId gda_sql_builder_add_cond_v (GdaSqlBuilder *builder, GdaSqlOperatorType op, 124 const GdaSqlBuilderId *op_ids, gint op_ids_size); 125 GdaSqlBuilderId gda_sql_builder_add_function (GdaSqlBuilder *builder, const gchar *func_name, ...); 126 GdaSqlBuilderId gda_sql_builder_add_function_v (GdaSqlBuilder *builder, const gchar *func_name, 127 const GdaSqlBuilderId *args, gint args_size); 128 GdaSqlBuilderId gda_sql_builder_add_sub_select (GdaSqlBuilder *builder, GdaSqlStatement *sqlst); 129 GdaSqlBuilderId gda_sql_builder_add_case (GdaSqlBuilder *builder, GdaSqlBuilderId test_expr, GdaSqlBuilderId else_expr, ...); 130 GdaSqlBuilderId gda_sql_builder_add_case_v (GdaSqlBuilder *builder, GdaSqlBuilderId test_expr, GdaSqlBuilderId else_expr, 131 const GdaSqlBuilderId *when_array, const GdaSqlBuilderId *then_array, gint args_size); 132 133 134 /* General Statement API */ 135 void gda_sql_builder_add_field_value (GdaSqlBuilder *builder, const gchar *field_name, GType type, ...); 136 void gda_sql_builder_add_field_value_as_gvalue (GdaSqlBuilder *builder, const gchar *field_name, 137 const GValue *value); 138 void gda_sql_builder_add_field_value_id (GdaSqlBuilder *builder, GdaSqlBuilderId field_id, GdaSqlBuilderId value_id); 139 140 void gda_sql_builder_set_table (GdaSqlBuilder *builder, const gchar *table_name); 141 void gda_sql_builder_set_where (GdaSqlBuilder *builder, GdaSqlBuilderId cond_id); 142 143 /* SELECT Statement API */ 144 GdaSqlBuilderId gda_sql_builder_select_add_field (GdaSqlBuilder *builder, const gchar *field_name, 145 const gchar *table_name, const gchar *alias); 146 GdaSqlBuilderId gda_sql_builder_select_add_target (GdaSqlBuilder *builder, const gchar *table_name, const gchar *alias); 147 GdaSqlBuilderId gda_sql_builder_select_add_target_id (GdaSqlBuilder *builder, GdaSqlBuilderId table_id, const gchar *alias); 148 GdaSqlBuilderId gda_sql_builder_select_join_targets (GdaSqlBuilder *builder, 149 GdaSqlBuilderId left_target_id, GdaSqlBuilderId right_target_id, 150 GdaSqlSelectJoinType join_type, 151 GdaSqlBuilderId join_expr); 152 void gda_sql_builder_join_add_field (GdaSqlBuilder *builder, GdaSqlBuilderId join_id, const gchar *field_name); 153 void gda_sql_builder_select_order_by (GdaSqlBuilder *builder, GdaSqlBuilderId expr_id, 154 gboolean asc, const gchar *collation_name); 155 void gda_sql_builder_select_set_distinct (GdaSqlBuilder *builder, 156 gboolean distinct, GdaSqlBuilderId expr_id); 157 void gda_sql_builder_select_set_limit (GdaSqlBuilder *builder, 158 GdaSqlBuilderId limit_count_expr_id, GdaSqlBuilderId limit_offset_expr_id); 159 160 void gda_sql_builder_select_set_having (GdaSqlBuilder *builder, GdaSqlBuilderId cond_id); 161 void gda_sql_builder_select_group_by (GdaSqlBuilder *builder, GdaSqlBuilderId expr_id); 162 163 /* COMPOUND SELECT Statement API */ 164 void gda_sql_builder_compound_set_type (GdaSqlBuilder *builder, GdaSqlStatementCompoundType compound_type); 165 void gda_sql_builder_compound_add_sub_select (GdaSqlBuilder *builder, GdaSqlStatement *sqlst); 166 void gda_sql_builder_compound_add_sub_select_from_builder (GdaSqlBuilder *builder, GdaSqlBuilder *subselect); 167 168 /* import/Export API */ 169 GdaSqlExpr *gda_sql_builder_export_expression (GdaSqlBuilder *builder, GdaSqlBuilderId id); 170 GdaSqlBuilderId gda_sql_builder_import_expression (GdaSqlBuilder *builder, GdaSqlExpr *expr); 171 GdaSqlBuilderId gda_sql_builder_import_expression_from_builder (GdaSqlBuilder *builder, GdaSqlBuilder *query, GdaSqlBuilderId expr_id); 172 173 G_END_DECLS 174 175 #endif 176