[libgda/gtk3] Documentation: removed the tmpl/ dir used by GtkDoc
- From: Vivien Malerba <vivien src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libgda/gtk3] Documentation: removed the tmpl/ dir used by GtkDoc
- Date: Sun, 13 Mar 2011 14:49:28 +0000 (UTC)
commit af2191504a54db791f3594ed6106a73eaa3324b4
Author: Vivien Malerba <malerba gnome-db org>
Date: Sun Mar 13 15:48:41 2011 +0100
Documentation: removed the tmpl/ dir used by GtkDoc
doc/C/libgda-sections.txt | 3 +
doc/C/tmpl/.gitignore | 93 --
doc/C/tmpl/gda-attributes-manager.sgml | 194 ---
doc/C/tmpl/gda-batch.sgml | 115 --
doc/C/tmpl/gda-blob-op.sgml | 148 --
doc/C/tmpl/gda-column.sgml | 179 ---
doc/C/tmpl/gda-config.sgml | 262 ----
doc/C/tmpl/gda-connection-event.sgml | 128 --
doc/C/tmpl/gda-connection.sgml | 806 -----------
doc/C/tmpl/gda-data-access-wrapper.sgml | 60 -
doc/C/tmpl/gda-data-comparator.sgml | 131 --
doc/C/tmpl/gda-data-handler.sgml | 122 --
doc/C/tmpl/gda-data-model-array.sgml | 118 --
doc/C/tmpl/gda-data-model-bdb.sgml | 95 --
doc/C/tmpl/gda-data-model-dir.sgml | 90 --
doc/C/tmpl/gda-data-model-hash.sgml | 80 --
doc/C/tmpl/gda-data-model-import.sgml | 142 --
doc/C/tmpl/gda-data-model-iter.sgml | 203 ---
doc/C/tmpl/gda-data-model.sgml | 514 -------
doc/C/tmpl/gda-data-proxy.sgml | 512 -------
doc/C/tmpl/gda-data-select-priv.sgml | 220 ---
doc/C/tmpl/gda-data-select.sgml | 199 ---
doc/C/tmpl/gda-enum-types.sgml | 904 -------------
doc/C/tmpl/gda-export.sgml | 16 -
doc/C/tmpl/gda-field.sgml | 323 -----
doc/C/tmpl/gda-handler-bin.sgml | 52 -
doc/C/tmpl/gda-handler-boolean.sgml | 52 -
doc/C/tmpl/gda-handler-numerical.sgml | 52 -
doc/C/tmpl/gda-handler-string.sgml | 62 -
doc/C/tmpl/gda-handler-time.sgml | 84 --
doc/C/tmpl/gda-handler-type.sgml | 54 -
doc/C/tmpl/gda-holder.sgml | 393 ------
doc/C/tmpl/gda-lockable.sgml | 53 -
doc/C/tmpl/gda-log.sgml | 65 -
doc/C/tmpl/gda-meta-store.sgml | 275 ----
doc/C/tmpl/gda-meta-struct.sgml | 460 -------
doc/C/tmpl/gda-mutex.sgml | 77 --
doc/C/tmpl/gda-pstmt.sgml | 77 --
doc/C/tmpl/gda-quark-list.sgml | 111 --
doc/C/tmpl/gda-repetitive-statement.sgml | 73 -
doc/C/tmpl/gda-report-docbook-document.sgml | 57 -
doc/C/tmpl/gda-report-document.sgml | 70 -
doc/C/tmpl/gda-report-engine.sgml | 249 ----
doc/C/tmpl/gda-report-rml-document.sgml | 44 -
doc/C/tmpl/gda-row.sgml | 66 -
doc/C/tmpl/gda-server-operation-nodes.sgml | 117 --
doc/C/tmpl/gda-server-operation-sequences.sgml | 96 --
doc/C/tmpl/gda-server-operation.sgml | 315 -----
doc/C/tmpl/gda-server-provider.sgml | 368 -----
doc/C/tmpl/gda-set.sgml | 335 -----
doc/C/tmpl/gda-sql-builder.sgml | 430 ------
doc/C/tmpl/gda-sql-parser.sgml | 233 ----
doc/C/tmpl/gda-sql-statement.sgml | 1409 --------------------
doc/C/tmpl/gda-statement.sgml | 214 ---
doc/C/tmpl/gda-thread-connection.sgml | 45 -
doc/C/tmpl/gda-thread-wrapper.sgml | 212 ---
doc/C/tmpl/gda-transaction-status.sgml | 80 --
doc/C/tmpl/gda-transaction.sgml | 81 --
doc/C/tmpl/gda-tree-manager.sgml | 140 --
doc/C/tmpl/gda-tree-mgr-columns.sgml | 71 -
doc/C/tmpl/gda-tree-mgr-label.sgml | 43 -
doc/C/tmpl/gda-tree-mgr-schemas.sgml | 55 -
doc/C/tmpl/gda-tree-mgr-select.sgml | 69 -
doc/C/tmpl/gda-tree-mgr-tables.sgml | 65 -
doc/C/tmpl/gda-tree-node-dbio.sgml | 61 -
doc/C/tmpl/gda-tree-node.sgml | 149 --
doc/C/tmpl/gda-tree.sgml | 181 ---
doc/C/tmpl/gda-util.sgml | 160 ---
doc/C/tmpl/gda-value.sgml | 622 ---------
doc/C/tmpl/gda-vconnection-data-model.sgml | 136 --
doc/C/tmpl/gda-vconnection-hub.sgml | 92 --
doc/C/tmpl/gda-virtual-connection.sgml | 68 -
doc/C/tmpl/gda-virtual-provider.sgml | 28 -
doc/C/tmpl/gda-vprovider-data-model.sgml | 39 -
doc/C/tmpl/gda-vprovider-hub.sgml | 43 -
doc/C/tmpl/gda-xa-transaction.sgml | 166 ---
doc/C/tmpl/gdaui-basic-form.sgml | 345 -----
doc/C/tmpl/gdaui-cloud.sgml | 126 --
doc/C/tmpl/gdaui-combo.sgml | 87 --
doc/C/tmpl/gdaui-data-entry.sgml | 229 ----
doc/C/tmpl/gdaui-data-filter.sgml | 43 -
doc/C/tmpl/gdaui-data-proxy-info.sgml | 64 -
doc/C/tmpl/gdaui-data-proxy.sgml | 149 --
doc/C/tmpl/gdaui-data-selector.sgml | 110 --
doc/C/tmpl/gdaui-data-store.sgml | 125 --
doc/C/tmpl/gdaui-data-widget-filter.sgml | 39 -
doc/C/tmpl/gdaui-data-widget-info.sgml | 57 -
doc/C/tmpl/gdaui-data-widget.sgml | 192 ---
doc/C/tmpl/gdaui-easy.sgml | 32 -
doc/C/tmpl/gdaui-form.sgml | 57 -
doc/C/tmpl/gdaui-grid.sgml | 66 -
doc/C/tmpl/gdaui-login.sgml | 112 --
doc/C/tmpl/gdaui-plugins.sgml | 66 -
doc/C/tmpl/gdaui-provider-selector.sgml | 65 -
doc/C/tmpl/gdaui-raw-form.sgml | 43 -
doc/C/tmpl/gdaui-raw-grid.sgml | 102 --
doc/C/tmpl/gdaui-rt-editor.sgml | 103 --
doc/C/tmpl/gdaui-server-operation.sgml | 62 -
doc/C/tmpl/gdaui-set.sgml | 68 -
doc/C/tmpl/gdaui-tree-store.sgml | 105 --
doc/C/tmpl/libgda.sgml | 47 -
doc/C/tmpl/provider-support-sql.sgml | 133 --
doc/C/tmpl/provider-support.sgml | 480 -------
.../DocBook/gda-report-docbook-document.h | 16 +-
libgda-report/RML/gda-report-rml-document.h | 21 +-
libgda-report/engine/gda-report-engine.h | 153 +++-
libgda-report/gda-report-document.h | 16 +-
libgda-ui/gdaui-basic-form.h | 102 ++-
libgda-ui/gdaui-cloud.h | 22 +-
libgda-ui/gdaui-combo.h | 14 +-
libgda-ui/gdaui-data-entry.h | 26 +
libgda-ui/gdaui-data-filter.h | 18 +-
libgda-ui/gdaui-data-proxy-info.h | 30 +-
libgda-ui/gdaui-data-proxy.h | 36 +-
libgda-ui/gdaui-data-selector.h | 24 +-
libgda-ui/gdaui-data-store.h | 17 +-
libgda-ui/gdaui-easy.h | 13 +-
libgda-ui/gdaui-form.h | 15 +-
libgda-ui/gdaui-grid.h | 15 +-
libgda-ui/gdaui-login.h | 30 +-
libgda-ui/gdaui-plugin.h | 35 +-
libgda-ui/gdaui-provider-selector.h | 13 +-
libgda-ui/gdaui-raw-form.h | 18 +-
libgda-ui/gdaui-raw-grid.h | 18 +-
libgda-ui/gdaui-rt-editor.h | 32 +-
libgda-ui/gdaui-server-operation.h | 22 +-
libgda-ui/gdaui-tree-store.h | 14 +-
libgda/gda-attributes-manager.h | 72 +-
libgda/gda-batch.h | 19 +-
libgda/gda-blob-op.h | 73 +-
libgda/gda-column.h | 17 +-
libgda/gda-config.h | 44 +
libgda/gda-connection-event.h | 12 +
libgda/gda-connection.h | 41 +
libgda/gda-data-access-wrapper.h | 16 +-
libgda/gda-data-comparator.h | 27 +-
libgda/gda-data-handler.h | 27 +-
libgda/gda-data-model-array.h | 19 +-
libgda/gda-data-model-bdb.h | 25 +-
libgda/gda-data-model-dir.h | 27 +-
libgda/gda-data-model-import.h | 35 +-
libgda/gda-data-model-iter.h | 50 +-
libgda/gda-data-model.h | 43 +-
libgda/gda-data-proxy.h | 108 ++-
libgda/gda-data-select.h | 39 +-
libgda/gda-enums.h | 7 +
libgda/gda-holder.h | 19 +-
libgda/gda-lockable.h | 16 +-
libgda/gda-log.h | 14 +-
libgda/gda-meta-store.h | 36 +-
libgda/gda-meta-struct.h | 91 ++-
libgda/gda-mutex.h | 18 +-
libgda/gda-quark-list.h | 15 +-
libgda/gda-repetitive-statement.h | 25 +-
libgda/gda-row.h | 21 +-
libgda/gda-server-operation.h | 62 +
libgda/gda-server-provider-extra.h | 11 +
libgda/gda-server-provider.h | 95 ++-
libgda/gda-set.h | 16 +
libgda/gda-sql-builder.h | 41 +-
libgda/gda-statement-extra.h | 101 ++-
libgda/gda-statement.h | 62 +-
libgda/gda-transaction-status.h | 45 +-
libgda/gda-tree-manager.h | 24 +-
libgda/gda-tree-mgr-columns.h | 24 +-
libgda/gda-tree-mgr-label.h | 15 +-
libgda/gda-tree-mgr-schemas.h | 20 +-
libgda/gda-tree-mgr-select.h | 26 +-
libgda/gda-tree-mgr-tables.h | 24 +-
libgda/gda-tree-node.h | 19 +-
libgda/gda-tree.h | 19 +-
libgda/gda-util.h | 14 +-
libgda/gda-value.h | 82 ++-
libgda/gda-xa-transaction.h | 50 +-
libgda/handlers/gda-handler-bin.h | 16 +-
libgda/handlers/gda-handler-boolean.h | 16 +-
libgda/handlers/gda-handler-numerical.h | 16 +-
libgda/handlers/gda-handler-string.h | 16 +-
libgda/handlers/gda-handler-time.h | 16 +-
libgda/handlers/gda-handler-type.h | 16 +-
libgda/libgda.h.in | 12 +-
libgda/providers-support/gda-data-select-priv.h | 25 +-
libgda/providers-support/gda-pstmt.h | 33 +-
libgda/sql-parser/gda-sql-parser.h | 87 ++-
libgda/sql-parser/gda-sql-statement.h | 33 +-
libgda/sql-parser/gda-statement-struct-compound.h | 18 +-
libgda/sql-parser/gda-statement-struct-decl.h | 69 +-
libgda/sql-parser/gda-statement-struct-delete.h | 9 +-
libgda/sql-parser/gda-statement-struct-insert.h | 38 +-
libgda/sql-parser/gda-statement-struct-parts.h | 140 ++
libgda/sql-parser/gda-statement-struct-select.h | 17 +-
libgda/sql-parser/gda-statement-struct-trans.h | 15 +-
libgda/sql-parser/gda-statement-struct-unknown.h | 12 +-
libgda/sql-parser/gda-statement-struct-update.h | 12 +-
libgda/sql-parser/gda-statement-struct-util.c | 6 +-
libgda/sql-parser/gda-statement-struct.h | 12 +-
libgda/sqlite/virtual/gda-vconnection-data-model.h | 59 +-
libgda/sqlite/virtual/gda-vconnection-hub.h | 23 +-
libgda/sqlite/virtual/gda-virtual-connection.h | 14 +-
libgda/sqlite/virtual/gda-virtual-provider.h | 15 +-
libgda/sqlite/virtual/gda-vprovider-data-model.h | 18 +-
libgda/sqlite/virtual/gda-vprovider-hub.h | 21 +-
libgda/thread-wrapper/gda-thread-wrapper.h | 80 ++-
203 files changed, 3044 insertions(+), 17559 deletions(-)
---
diff --git a/doc/C/libgda-sections.txt b/doc/C/libgda-sections.txt
index a980816..837d53f 100644
--- a/doc/C/libgda-sections.txt
+++ b/doc/C/libgda-sections.txt
@@ -603,8 +603,11 @@ gda_virtual_connection_get_type
GdaVconnectionDataModel
GdaVconnectionDataModelFunc
GdaVconnectionDataModelSpec
+GdaVconnectionDataModelFilter
GdaVconnectionDataModelCreateColumnsFunc
GdaVconnectionDataModelCreateModelFunc
+GdaVconnectionDataModelParseFilterFunc
+GdaVconnectionDataModelCreateFModelFunc
gda_vconnection_data_model_add
gda_vconnection_data_model_add_model
gda_vconnection_data_model_remove
diff --git a/libgda-report/DocBook/gda-report-docbook-document.h b/libgda-report/DocBook/gda-report-docbook-document.h
index 942c6e7..e8244e9 100644
--- a/libgda-report/DocBook/gda-report-docbook-document.h
+++ b/libgda-report/DocBook/gda-report-docbook-document.h
@@ -1,5 +1,5 @@
-/* GDA
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaReportDocbookDocument {
struct _GdaReportDocbookDocumentClass {
GdaReportDocumentClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,8 +53,17 @@ struct _GdaReportDocbookDocumentClass {
void (*_gda_reserved4) (void);
};
-GType gda_report_docbook_document_get_type (void) G_GNUC_CONST;
+/**
+ * SECTION:gda-report-docbook-document
+ * @short_description: Report document based on the DocBook dialect
+ * @title: GdaReportDocbookDocument
+ * @stability: Stable
+ * @see_also: #GdaReportDocument
+ *
+ *
+ */
+GType gda_report_docbook_document_get_type (void) G_GNUC_CONST;
GdaReportDocument *gda_report_docbook_document_new (GdaReportEngine *engine);
G_END_DECLS
diff --git a/libgda-report/RML/gda-report-rml-document.h b/libgda-report/RML/gda-report-rml-document.h
index 0a85bed..ec4ac71 100644
--- a/libgda-report/RML/gda-report-rml-document.h
+++ b/libgda-report/RML/gda-report-rml-document.h
@@ -1,5 +1,5 @@
-/* GDA
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaReportRmlDocument {
struct _GdaReportRmlDocumentClass {
GdaReportDocumentClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,6 +53,22 @@ struct _GdaReportRmlDocumentClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-report-rml-document
+ * @short_description: Report document based on the RML dialect
+ * @title: GdaReportRmlDocument
+ * @stability: Stable
+ * @see_also: #GdaReportDocument
+ *
+ * The #GdaReportRmlDocument makes it easy to create reports based on a RML
+ * template file.
+ *
+ * RML (Report Markup Language) is an XML dialect which allows one to describe in a very precise way
+ * layouts which can then be converted to PDF. For more information, see the
+ * <ulink url="http://www.reportlab.org/";>ReportLab</ulink> or
+ * <ulink url="http://en.openreport.org/index.py/static/page/trml2pdf";>OpenReport</ulink> web pages.
+ */
+
GType gda_report_rml_document_get_type (void) G_GNUC_CONST;
GdaReportDocument *gda_report_rml_document_new (GdaReportEngine *engine);
diff --git a/libgda-report/engine/gda-report-engine.h b/libgda-report/engine/gda-report-engine.h
index d02d61b..3a29d39 100644
--- a/libgda-report/engine/gda-report-engine.h
+++ b/libgda-report/engine/gda-report-engine.h
@@ -1,5 +1,5 @@
-/* GDA
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,7 @@ struct _GdaReportEngine {
struct _GdaReportEngineClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -55,6 +56,154 @@ struct _GdaReportEngineClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-report-engine
+ * @short_description: Low level report generator based on XML
+ * @title: GdaReportEngine
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaReportEngine object generates a report based on a specifications file in any XML format. It browses
+ * through the XML file and replaces the parts of it which are <gda_report...> action nodes. The generated
+ * XML file may then need to be processed using other post-processor tools depending on the XML file format.
+ *
+ * The following "action" tags known are:
+ * <table frame="all">
+ * <tgroup cols="4" colsep="1" rowsep="1" align="justify">
+ * <thead>
+ * <row>
+ * <entry>Node name</entry>
+ * <entry>Description</entry>
+ * <entry>Attributes</entry>
+ * <entry><gda_report...> sub nodes</entry>
+ * </row>
+ * </thead>
+ * <tbody>
+ * <row>
+ * <entry><gda_report_section></entry>
+ * <entry>
+ * <para>Starts a section which runs a SELECT query to generate a data model (#GdaDataModel).
+ * </para>
+ * <para>
+ * A parameter named "<query_name>|?nrows" is created and is available in any sub node
+ * of the <gda_report_section> node, which contains the number of rows in the section's data model.
+ * </para>
+ * </entry>
+ * <entry>
+ * <itemizedlist>
+ * <listitem><para>"query_name": the name of a SELECT #GdaStatement to be run; using this attribute
+ * implies that a GdaStatement has
+ * already been created and that the query has been declared to the GdaReportEngine object
+ * with the "query_name "name.
+ * To define a query within the report spec., add a <gda_report_query>
+ * sub node instead
+ * </para></listitem>
+ * <listitem><para>"cnc_name": name of the connection to use (the #GdaConnection object has
+ * already been created and has been declared to the GdaReportEngine object with the "cnc_name" name)
+ * </para></listitem>
+ * </itemizedlist>
+ * </entry>
+ * <entry>
+ * <itemizedlist>
+ * <listitem><para><gda_report_query> to define the SELECT query which will be run. It is also
+ * possible to use a named query using the "query_name" attribute of the <gda_report_section> node
+ * </para></listitem>
+ * <listitem><para><gda_report_if_empty_section> to define the contents by which the <gda_report_section>
+ * node is replaced if the data model for the section contains no row.
+ * </para></listitem>
+ * </itemizedlist>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_iter></entry>
+ * <entry>
+ * <para>Repeats is list of children nodes for each row in the section's data model. Note that is that data
+ * model has no row, then the contents of the <gda_report_iter> node will not appear at all in the
+ * final result.
+ * </para>
+ * <para>
+ * For each column of the data model, several parameters are created, named
+ * <query_name>|@<column_name> (such as "customers|@@name" for the "name" column)
+ * and <query_name>|#<column_number>,
+ * (such as "customers|##0" for the first column).
+ * Those parameters can be used in any child node (recursively),
+ * and have their value updated for each row of the data model.
+ * For more information about the parameter's syntax,
+ * see the <link linkend="SQL_queries">GDA SQL query syntax</link>.
+ * </para>
+ * </entry>
+ * <entry/>
+ * <entry/>
+ * </row>
+ * <row>
+ * <entry><gda_report_query></entry>
+ * <entry>Specifies the SQL of the SELECT query in a <gda_report_section> section. The SQL should be
+ * in the contents of that node</entry>
+ * <entry><itemizedlist>
+ * <listitem><para>"query_name": name of the query</para></listitem>
+ * <listitem><para>"cnc_name": name of the connection to use (the #GdaConnection object has
+ * already been created and has been declared to the GdaReportEngine object with the "cnc_name" name)
+ * </para></listitem>
+ * </itemizedlist>
+ * </entry>
+ * <entry></entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_param_value></entry>
+ * <entry>Replace the node with the value of a parameter. The parameter can either by defined globally
+ * (and declared to the GdaReportEngine), or defined as part of a section</entry>
+ * <entry>
+ * <itemizedlist>
+ * <listitem><para>"param_name" specifies the name of the parameter</para></listitem>
+ * <listitem><para>"converter" optionnally specifies a conversion to apply to the parameter's
+ * contents (for now only "richtext::docbook" to convert text
+ * in <ulink url="http://txt2tags.org/";>rich text format</ulink> to
+ * the DocBook syntax)</para></listitem>
+ * </itemizedlist>
+ * </entry>
+ * <entry></entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_expr></entry>
+ * <entry>Replace the node with the evaluation of an expression. The expression can be any SQLite valid expression,
+ * and can contain any reference to any parameter. For example the node:
+ * <programlisting><![CDATA[
+ *<gda_report_expr>
+ *##customers|@col IS NULL
+ *</gda_report_expr>]]></programlisting>
+ * will return a TRUE value if the parameter named "customers|@@col" is not NULL. For more
+ * information about the parameter's syntax, see the <link linkend="SQL_queries">GDA SQL query syntax</link>.
+ * </entry>
+ * <entry></entry>
+ * <entry></entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_if></entry>
+ * <entry>Creates an "IF THEN ELSE" flow control, based on the evaluation of an expression (in the same way as for the
+ * <gda_report_expr> node). If the expression evaluates as TRUE, then the <gda_report_if> node will
+ * be replaced by the children nodes of the <gda_report_if_true> node if it exists, and otherwise by
+ * the children nodes of the <gda_report_if_false> node if it exists.</entry>
+ * <entry>"expr" to define the expression to evaluate</entry>
+ * <entry><gda_report_if_true> and <gda_report_if_false></entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_if_true></entry>
+ * <entry>Defines the contents to use when the expression of a <gda_report_if> is evaluated as TRUE</entry>
+ * <entry></entry>
+ * <entry></entry>
+ * </row>
+ * <row>
+ * <entry><gda_report_if_false></entry>
+ * <entry>Defines the contents to use when the expression of a <gda_report_if> is evaluated as FALSE</entry>
+ * <entry></entry>
+ * <entry></entry>
+ * </row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ */
+
+
GType gda_report_engine_get_type (void) G_GNUC_CONST;
GdaReportEngine *gda_report_engine_new (xmlNodePtr spec_node);
diff --git a/libgda-report/gda-report-document.h b/libgda-report/gda-report-document.h
index 16a9227..14961ee 100644
--- a/libgda-report/gda-report-document.h
+++ b/libgda-report/gda-report-document.h
@@ -1,5 +1,5 @@
-/* GDA
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -50,6 +50,7 @@ struct _GdaReportDocumentClass {
gboolean (*run_as_html) (GdaReportDocument *doc, const gchar *filename, GError **error);
gboolean (*run_as_pdf) (GdaReportDocument *doc, const gchar *filename, GError **error);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -57,6 +58,17 @@ struct _GdaReportDocumentClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-report-document
+ * @short_description: Report document
+ * @title: GdaReportDocument
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaReportDocument wraps the usage of a #GdaReportEngine for specific HTML or PDF targets. This class is
+ * abstract (no instance be created directly), and one of its subclasses has to be used.
+ */
+
GType gda_report_document_get_type (void) G_GNUC_CONST;
void gda_report_document_set_template (GdaReportDocument *doc, const gchar *file);
diff --git a/libgda-ui/gdaui-basic-form.h b/libgda-ui/gdaui-basic-form.h
index 3ed16dd..4f336fc 100644
--- a/libgda-ui/gdaui-basic-form.h
+++ b/libgda-ui/gdaui-basic-form.h
@@ -1,6 +1,5 @@
-/* gdaui-basic-form.h
- *
- * Copyright (C) 2002 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2002 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -57,9 +56,100 @@ struct _GdauiBasicFormClass
void (*layout_changed) (GdauiBasicForm *form);
};
-/*
- * Generic widget's methods
-*/
+/**
+ * SECTION:gdaui-basic-form
+ * @short_description: Form widget mapping the values contained in a #GdaSet
+ * @title: GdauiBasicForm
+ * @stability: Stable
+ * @Image: vi-basic-form.png
+ * @see_also:
+ *
+ * The #GdauiBasicForm widget is a form containing an entry for each #GdaHolder object
+ * contained in a #GdaSet (specified when the form is created). A typical usage is when the
+ * user is requested to enter a value which will be used in a statement (without any error checking for clarity):
+ * <programlisting>
+ * GdaStatement *stmt;
+ * GdaSet *params;
+ * stmt = gda_sql_parser_parse_string (parser, "SELECT * FROM customers where name LIKE ##name::string", NULL, NULL);
+ * gda_statement_get_parameters (stmt, &params, NULL);
+ *
+ * GtkWidget *form;
+ * gint result;
+ * form = gdaui_basic_form_new_in_dialog (params, NULL, "Customer search", "Enter Customer search expression");
+ * result = gtk_dialog_run (GTK_DIALOG (form));
+ * gtk_widget_destroy (form);
+ * if (result == GTK_RESPONSE_ACCEPT) {
+ * // execute statement
+ * GdaDataModel *model;
+ * model = gda_connection_statement_execute_select (cnc, stmt, params, NULL);
+ * [...]
+ * }
+ * g_object_unref (params);
+ * g_object_unref (stmt);
+ * </programlisting>
+ *
+ * The default layout within a #GdauiBasicForm is a vertical column: all the data entry widgets are aligned
+ * in a single column. This behaviour can be changed using the gdaui_basic_form_set_layout_from_file() method or
+ * setting the <link linkend="GdauiBasicForm--xml-layout">xml-layout</link> property.
+ *
+ * <anchor id="GdauiBasicFormXMLLayout"/>
+ * The #GdauiBasicForm class parses textual descriptions of XML layout which
+ * which can be described by the following DTD.
+ *
+ * <programlisting><![CDATA[
+ * <!ELEMENT gdaui_layouts (gdaui_form | gdaui_grid)>
+ *
+ * <!ELEMENT gdaui_form (gdaui_section | gdaui_column | gdaui_notebook)*>
+ * <!ATTLIST gdaui_form
+ * name CDATA #REQUIRED
+ * container (columns|rows|hpaned|vpaned) #IMPLIED>
+ *
+ * <!ELEMENT gdaui_section (gdaui_section | gdaui_column | gdaui_notebook)*>
+ * <!ATTLIST gdaui_section
+ * title CDATA #IMPLIED >
+ *
+ * <!ELEMENT gdaui_notebook (gdaui_section | gdaui_column | gdaui_notebook)*>
+ *
+ * <!ELEMENT gdaui_column (gdaui_entry | gdaui_placeholder)*>
+ *
+ * <!ELEMENT gdaui_entry EMPTY>
+ * <!ATTLIST gdaui_entry
+ * name CDATA #REQUIRED
+ * editable (true|false) #IMPLIED
+ * label CDATA #IMPLIED
+ * plugin CDATA #IMPLIED>
+ *
+ * <!ELEMENT gdaui_placeholder EMPTY>
+ * <!ATTLIST gdaui_placeholder
+ * id CDATA #REQUIRED
+ * label CDATA #IMPLIED>
+ * ]]></programlisting>
+ *
+ * <example>
+ * <title>A GdauiBasicForm layout example</title>
+ * <programlisting><![CDATA[
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <gdaui_layouts>
+ * <gdaui_form name="customers" container="hpaned">
+ * <gdaui_section title="Summary">
+ * <gdaui_column>
+ * <gdaui_entry name="id" editable="no"/>
+ * <gdaui_entry name="name"/>
+ * <gdaui_entry name="comments" plugin="text"/>
+ * <gdaui_entry name="total_orders" label="Total ordered" plugin="number:NB_DECIMALS=2;CURRENCY=â?¬"/>
+ * </gdaui_column>
+ * </gdaui_section>
+ * <gdaui_section title="Photo">
+ * <gdaui_column>
+ * <gdaui_entry name="photo" plugin="picture"/>
+ * </gdaui_column>
+ * </gdaui_section>
+ * </gdaui_form>
+ * </gdaui_layouts>
+ * ]]></programlisting>
+ * </example>
+ */
+
GType gdaui_basic_form_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_basic_form_new (GdaSet *data_set);
GtkWidget *gdaui_basic_form_new_in_dialog (GdaSet *data_set, GtkWindow *parent,
diff --git a/libgda-ui/gdaui-cloud.h b/libgda-ui/gdaui-cloud.h
index 9797996..8cdf006 100644
--- a/libgda-ui/gdaui-cloud.h
+++ b/libgda-ui/gdaui-cloud.h
@@ -1,6 +1,5 @@
-/* gdaui-cloud.h
- *
- * Copyright (C) 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2009 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -50,9 +49,22 @@ struct _GdauiCloudClass
void (* activate) (GdauiCloud *cloud, gint row);
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-cloud
+ * @short_description: Cloud widget
+ * @title: GdauiCloud
+ * @stability: Stable
+ * @Image: vi-cloud.png
+ * @see_also:
+ *
+ * The #GdauiCloud widget displays a string for each row in a #GdaDataModel for which the size
+ * is variable (determined either by some data in the data model, or by a function provided by
+ * the programmer).
+ *
+ * Depending on the selection mode of the widget, each string can be selected by the user and
+ * the "selection-changed" signal is emitted.
*/
+
GType gdaui_cloud_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_cloud_new (GdaDataModel *model, gint label_column, gint weight_column);
diff --git a/libgda-ui/gdaui-combo.h b/libgda-ui/gdaui-combo.h
index fcb4ff2..3f63cf6 100644
--- a/libgda-ui/gdaui-combo.h
+++ b/libgda-ui/gdaui-combo.h
@@ -1,6 +1,5 @@
-/* GNOME DB library
- *
- * Copyright (C) 1999 - 2009 The Free Software Foundation
+/*
+ * Copyright (C) 1999 - 2011 The Free Software Foundation
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -49,6 +48,15 @@ struct _GdauiComboClass {
GtkComboBoxClass parent_class;
};
+/**
+ * SECTION:gdaui-combo
+ * @short_description: Combo box to choose from the contents of a #GdaDataModel
+ * @title: GdauiCombo
+ * @stability: Stable
+ * @Image: vi-combo.png
+ * @see_also:
+ */
+
GType gdaui_combo_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_combo_new (void);
diff --git a/libgda-ui/gdaui-data-entry.h b/libgda-ui/gdaui-data-entry.h
index 74130e6..c2aba1a 100644
--- a/libgda-ui/gdaui-data-entry.h
+++ b/libgda-ui/gdaui-data-entry.h
@@ -73,6 +73,32 @@ struct _GdauiDataEntryIface
void (*_gdaui_reserved4) (void);
};
+/**
+ * SECTION:gdaui-data-entry
+ * @short_description: Data entry widget
+ * @title: GdauiDataEntry
+ * @stability: Stable
+ * @Image: vi-data-entry.png
+ * @see_also:
+ *
+ * The #GdaUiDataEntry is an interface for widgets (simple or complex)
+ * which lets the user view and/or modify a #GValue.
+ *
+ * This interface is implemented by widgets which feature data editing (usually composed of an editing
+ * area and a button to have some more control on the value being edited).
+ * The interface allows to control how the widget works and to query the value and the attributes
+ * of the data held by the widget.
+ *
+ * The widget can store the original value (to be able to tell if the value has been changed
+ * by the user) and a default value (which will be returned if the user explicitly forces the widget
+ * to be set to the default value).
+ * Control methods allow to set the type of value to be edited (the requested type must be
+ * compatible with what the widget can handle), set the value (which replaces the currently edited
+ * value), set the value and the original value (the value passed as argument is set and is also
+ * considered to be the original value).
+ *
+ * #GdaUiDataEntry widgets are normally created using the gdaui_new_data_entry() function.
+ */
diff --git a/libgda-ui/gdaui-data-filter.h b/libgda-ui/gdaui-data-filter.h
index a7bd160..1d86e8b 100644
--- a/libgda-ui/gdaui-data-filter.h
+++ b/libgda-ui/gdaui-data-filter.h
@@ -1,6 +1,5 @@
-/* gdaui-data-filter.h
- *
- * Copyright (C) 2007 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -51,9 +50,18 @@ struct _GdauiDataFilterClass
GtkVBoxClass parent_class;
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-data-filter
+ * @short_description: Entrer rules to filter the rows in a #GdauiDataProxy
+ * @title: GdauiDataFilter
+ * @stability: Stable
+ * @Image: vi-filter.png
+ * @see_also:
+ *
+ * The #GdauiDataFilter widget can be used as a standalone widget, but is also
+ * used internally by the #GdauiDataProxyInfo widget for its search option.
*/
+
GType gdaui_data_filter_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_data_filter_new (GdauiDataProxy *data_widget);
diff --git a/libgda-ui/gdaui-data-proxy-info.h b/libgda-ui/gdaui-data-proxy-info.h
index ddf146e..1529f60 100644
--- a/libgda-ui/gdaui-data-proxy-info.h
+++ b/libgda-ui/gdaui-data-proxy-info.h
@@ -1,6 +1,5 @@
-/* gdaui-data-proxy-info.h
- *
- * Copyright (C) 2006 Vivien Malerba
+/*
+ * Copyright (C) 2006 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -37,6 +36,15 @@ typedef struct _GdauiDataProxyInfo GdauiDataProxyInfo;
typedef struct _GdauiDataProxyInfoClass GdauiDataProxyInfoClass;
typedef struct _GdauiDataProxyInfoPriv GdauiDataProxyInfoPriv;
+/**
+ * GdauiDataProxyInfoFlag:
+ * @GDAUI_DATA_PROXY_INFO_NONE:
+ * @GDAUI_DATA_PROXY_INFO_CURRENT_ROW:
+ * @GDAUI_DATA_PROXY_INFO_ROW_MODIFY_BUTTONS:
+ * @GDAUI_DATA_PROXY_INFO_ROW_MOVE_BUTTONS:
+ * @GDAUI_DATA_PROXY_INFO_CHUNCK_CHANGE_BUTTONS:
+ * @GDAUI_DATA_PROXY_INFO_NO_FILTER:
+ */
typedef enum
{
GDAUI_DATA_PROXY_INFO_NONE = 0,
@@ -61,9 +69,21 @@ struct _GdauiDataProxyInfoClass
GtkHBoxClass parent_class;
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-data-proxy-info
+ * @short_description: Shows information & actions about a #GdauiDataProxy widget
+ * @title: GdauiDataProxyInfo
+ * @stability: Stable
+ * @Image: vi-info.png
+ * @see_also:
+ *
+ * The #GdauiDataProxyInfo widget is a container widget which, depending on how it is configured:
+ * <itemizedlist>
+ * <listitem><para>proposes action buttons to change the currently displayed row, add new row, ...</para></listitem>
+ * <listitem><para>displays information about the number of rows in a #GdauiDataProxy</para></listitem>
+ * </itemizedlist>
*/
+
GType gdaui_data_proxy_info_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_data_proxy_info_new (GdauiDataProxy *data_proxy, GdauiDataProxyInfoFlag flags);
diff --git a/libgda-ui/gdaui-data-proxy.h b/libgda-ui/gdaui-data-proxy.h
index 961e817..dba8957 100644
--- a/libgda-ui/gdaui-data-proxy.h
+++ b/libgda-ui/gdaui-data-proxy.h
@@ -1,6 +1,5 @@
-/* gdaui-data-proxy.h
- *
- * Copyright (C) 2004 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2004 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -35,11 +34,21 @@ G_BEGIN_DECLS
#define GDAUI_IS_DATA_PROXY(obj) G_TYPE_CHECK_INSTANCE_TYPE (obj, GDAUI_TYPE_DATA_PROXY)
#define GDAUI_DATA_PROXY_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GDAUI_TYPE_DATA_PROXY, GdauiDataProxyIface))
+/**
+ * GdauiDataProxyWriteMode:
+ * @GDAUI_DATA_PROXY_WRITE_ON_DEMAND: write only when explicitly requested
+ * @GDAUI_DATA_PROXY_WRITE_ON_ROW_CHANGE: write when the current selected row changes
+ * @GDAUI_DATA_PROXY_WRITE_ON_VALUE_ACTIVATED: write when user activates a value change
+ * @GDAUI_DATA_PROXY_WRITE_ON_VALUE_CHANGE: write when a parameters's value changes
+ *
+ * Defines when the data modifications held in the underlying #GdaDataProxy are written to the
+ * data model being proxied (using gda_data_proxy_apply_row_changes()).
+ */
typedef enum {
- GDAUI_DATA_PROXY_WRITE_ON_DEMAND = 0, /* write only when explicitly requested */
- GDAUI_DATA_PROXY_WRITE_ON_ROW_CHANGE = 1, /* write when the current selected row changes */
- GDAUI_DATA_PROXY_WRITE_ON_VALUE_ACTIVATED = 2, /* write when user activates a value change */
- GDAUI_DATA_PROXY_WRITE_ON_VALUE_CHANGE = 3 /* write when a parameters's value changes */
+ GDAUI_DATA_PROXY_WRITE_ON_DEMAND = 0,
+ GDAUI_DATA_PROXY_WRITE_ON_ROW_CHANGE = 1,
+ GDAUI_DATA_PROXY_WRITE_ON_VALUE_ACTIVATED = 2,
+ GDAUI_DATA_PROXY_WRITE_ON_VALUE_CHANGE = 3
} GdauiDataProxyWriteMode;
/* struct for the interface */
@@ -59,6 +68,19 @@ struct _GdauiDataProxyIface
void (* proxy_changed) (GdauiDataProxy *iface, GdaDataProxy *proxy);
};
+/**
+ * SECTION:gdaui-data-proxy
+ * @short_description: Displaying and modifying data in a #GdaDataProxy
+ * @title: GdauiDataProxy
+ * @stability: Stable
+ * @Image:
+ * @see_also: The #GdauiDataSelector interface which is usually also implemented by the widgets which implement the #GdauiDataProxy interface.
+ *
+ * The #GdauiDataProxy interface is implemented by widgets which allow modifications
+ * to a #GdaDataModel (through a #GdaDataProxy to actually proxy the changes before they
+ * are written to the data model).
+ */
+
GType gdaui_data_proxy_get_type (void) G_GNUC_CONST;
GdaDataProxy *gdaui_data_proxy_get_proxy (GdauiDataProxy *iface);
diff --git a/libgda-ui/gdaui-data-selector.h b/libgda-ui/gdaui-data-selector.h
index 27ebe65..988d7eb 100644
--- a/libgda-ui/gdaui-data-selector.h
+++ b/libgda-ui/gdaui-data-selector.h
@@ -1,6 +1,5 @@
-/* gdaui-data-selector.h
- *
- * Copyright (C) 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2009 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -55,6 +54,25 @@ struct _GdauiDataSelectorIface
void (* selection_changed) (GdauiDataSelector *iface);
};
+/**
+ * SECTION:gdaui-data-selector
+ * @short_description: Selecting data in a #GdaDataModel
+ * @title: GdauiDataSelector
+ * @stability: Stable
+ * @Image:
+ * @see_also:
+ *
+ * The #GdauiDataSelector interface is implemented by widgets which allow the user
+ * to select some data from a #GdaDataModel. Depending on the actual widget, the selection
+ * can be a single row or more than one row.
+ *
+ * This interface allows one to set and get the #GdaDataModel from which data is to be selected
+ * and offers a few other common behaviours.
+ *
+ * Please note that any row number in this interface is in reference to the #GdaDataModel returned by
+ * the gdaui_data_selector_get_model() method.
+ */
+
GType gdaui_data_selector_get_type (void) G_GNUC_CONST;
GdaDataModel *gdaui_data_selector_get_model (GdauiDataSelector *iface);
diff --git a/libgda-ui/gdaui-data-store.h b/libgda-ui/gdaui-data-store.h
index 52d6f19..af98431 100644
--- a/libgda-ui/gdaui-data-store.h
+++ b/libgda-ui/gdaui-data-store.h
@@ -1,6 +1,5 @@
-/* gdaui-data-store.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -58,6 +57,18 @@ struct _GdauiDataStoreClass
GObjectClass parent_class;
};
+/**
+ * SECTION:gdaui-data-store
+ * @short_description: Bridge between a #GdaDataModel and a #GtkTreeModel
+ * @title: GdauiDataStore
+ * @stability: Stable
+ * @Image:
+ * @see_also:
+ *
+ * The #GdauiDataStore object implements the #GtkTreeModel interface
+ * on top of a #GdaDataModel to be able to display its contents
+ * in a #GtkTreeView.
+ */
GType gdaui_data_store_get_type (void) G_GNUC_CONST;
GtkTreeModel *gdaui_data_store_new (GdaDataModel *model);
diff --git a/libgda-ui/gdaui-easy.h b/libgda-ui/gdaui-easy.h
index fe457b3..c4109c1 100644
--- a/libgda-ui/gdaui-easy.h
+++ b/libgda-ui/gdaui-easy.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -27,6 +27,15 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gdaui-easy
+ * @short_description: Set of UI related functions
+ * @title: UI Utility functions
+ * @stability: Stable
+ * @Image:
+ * @see_also:
+ */
+
GdauiDataEntry *gdaui_new_data_entry (GType type, const gchar *plugin_name);
GtkCellRenderer *_gdaui_new_cell_renderer (GType type, const gchar *plugin_name);
diff --git a/libgda-ui/gdaui-form.h b/libgda-ui/gdaui-form.h
index 895e378..1036e4f 100644
--- a/libgda-ui/gdaui-form.h
+++ b/libgda-ui/gdaui-form.h
@@ -1,6 +1,5 @@
-/* gdaui-form.h
- *
- * Copyright (C) 2002 - 2006 Vivien Malerba
+/*
+ * Copyright (C) 2002 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -50,9 +49,15 @@ struct _GdauiFormClass
GtkVBoxClass parent_class;
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-form
+ * @short_description: Form widget to manipulate data in a #GdaDataModel, with decorations
+ * @title: GdauiForm
+ * @stability: Stable
+ * @Image:
+ * @see_also: The #GdauiRawForm widget which is used by the #GdaForm widget.
*/
+
GType gdaui_form_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_form_new (GdaDataModel *model);
diff --git a/libgda-ui/gdaui-grid.h b/libgda-ui/gdaui-grid.h
index 5bfd585..5ab4152 100644
--- a/libgda-ui/gdaui-grid.h
+++ b/libgda-ui/gdaui-grid.h
@@ -1,6 +1,5 @@
-/* gdaui-grid.h
- *
- * Copyright (C) 2002 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2002 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -49,9 +48,15 @@ struct _GdauiGridClass
GtkVBoxClass parent_class;
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-grid
+ * @short_description: Grid widget to manipulate data in a #GdaDataModel, with decorations
+ * @title: GdauiGrid
+ * @stability: Stable
+ * @Image:
+ * @see_also: The #GdauiRawGrid widget which is used by the #GdaGrid widget.
*/
+
GType gdaui_grid_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_grid_new (GdaDataModel *model);
diff --git a/libgda-ui/gdaui-login.h b/libgda-ui/gdaui-login.h
index dc38783..7145f9f 100644
--- a/libgda-ui/gdaui-login.h
+++ b/libgda-ui/gdaui-login.h
@@ -1,5 +1,5 @@
-/* GNOME DB library
- * Copyright (C) 1999 - 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 1999 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -50,12 +50,38 @@ struct _GdauiLoginClass {
void (*changed) (GdauiLogin *login, gboolean is_valid);
};
+/**
+ * GdauiLoginMode:
+ * @GDA_UI_LOGIN_ENABLE_CONTROL_CENTRE_MODE:
+ * @GDA_UI_LOGIN_HIDE_DSN_SELECTION_MODE:
+ * @GDA_UI_LOGIN_HIDE_DIRECT_CONNECTION_MODE:
+ *
+ * Defines the aspect of the #GdauiLogin widget
+ */
typedef enum {
GDA_UI_LOGIN_ENABLE_CONTROL_CENTRE_MODE = 1 << 0,
GDA_UI_LOGIN_HIDE_DSN_SELECTION_MODE = 1 << 1,
GDA_UI_LOGIN_HIDE_DIRECT_CONNECTION_MODE = 1 << 2
} GdauiLoginMode;
+/**
+ * SECTION:gdaui-login
+ * @short_description: Connection opening widget
+ * @title: GdauiLogin
+ * @stability: Stable
+ * @Image: vi-login.png
+ * @see_also:
+ *
+ * The #GdauiLogin widget can be used when the user needs to enter
+ * data to open a connection. It can be customized in several ways:
+ * <itemizedlist>
+ * <listitem><para>data source (DSN) selection can be shown or hidden</para></listitem>
+ * <listitem><para>the button to launch the control center to declare new data sources can be
+ * shown or hidden</para></listitem>
+ * <listitem><para>the form to open a connection not using a DSN can be shown or hidden</para></listitem>
+ * </itemizedlist>
+ */
+
GType gdaui_login_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_login_new (const gchar *dsn);
void gdaui_login_set_mode (GdauiLogin *login, GdauiLoginMode mode);
diff --git a/libgda-ui/gdaui-plugin.h b/libgda-ui/gdaui-plugin.h
index 0bd60f2..321c6ff 100644
--- a/libgda-ui/gdaui-plugin.h
+++ b/libgda-ui/gdaui-plugin.h
@@ -1,6 +1,5 @@
-/* gdaui-plugin.h
- *
- * Copyright (C) 2006 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2006 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
@@ -26,7 +25,26 @@
#include <libgda-ui/gdaui-data-entry.h>
#include "gdaui-decl.h"
+/**
+ * GdauiEntryCreateFunc:
+ * @Param1:
+ * @Param2:
+ * @Param3:
+ * @Returns:
+ *
+ * Defines a function which creates a #GdauiDataEntry widget
+ */
typedef GdauiDataEntry *(*GdauiEntryCreateFunc)(GdaDataHandler *, GType, const gchar *);
+
+/**
+ * GdauiCellCreateFunc:
+ * @Param1:
+ * @Param2:
+ * @Param3:
+ * @Returns:
+ *
+ * Defines a function which creates a #GtkCellRenderer object
+ */
typedef GtkCellRenderer *(*GdauiCellCreateFunc) (GdaDataHandler *, GType, const gchar *);
@@ -61,6 +79,17 @@ typedef struct {
GdauiCellCreateFunc cell_create_func;
} GdauiPlugin;
+/**
+ * SECTION:gdaui-plugins
+ * @short_description:
+ * @title: UI plugins
+ * @stability: Stable
+ * @Image:
+ * @see_also:
+ *
+ * This section describes the functions used to declare UI plugins: data entry and cell renderers.
+ */
+
void gdaui_plugin_declare (const GdauiPlugin *plugin);
#endif
diff --git a/libgda-ui/gdaui-provider-selector.h b/libgda-ui/gdaui-provider-selector.h
index 5383a5a..d8f2fa8 100644
--- a/libgda-ui/gdaui-provider-selector.h
+++ b/libgda-ui/gdaui-provider-selector.h
@@ -1,5 +1,5 @@
-/* GNOME DB library
- * Copyright (C) 1999 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1999 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -47,6 +47,15 @@ struct _GdauiProviderSelectorClass {
GdauiComboClass parent_class;
};
+/**
+ * SECTION:gdaui-provider-selector
+ * @short_description: Select a database provider from a combo box
+ * @title: GdauiProviderSelector
+ * @stability: Stable
+ * @Image: vi-provider-selector.png
+ * @see_also:
+ */
+
GType gdaui_provider_selector_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_provider_selector_new (void);
diff --git a/libgda-ui/gdaui-raw-form.h b/libgda-ui/gdaui-raw-form.h
index bc1a5e0..8840d82 100644
--- a/libgda-ui/gdaui-raw-form.h
+++ b/libgda-ui/gdaui-raw-form.h
@@ -1,6 +1,5 @@
-/* gdaui-raw-form.h
- *
- * Copyright (C) 2002 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2002 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -51,9 +50,18 @@ struct _GdauiRawFormClass
GdauiBasicFormClass parent_class;
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-raw-form
+ * @short_description: Form widget to manipulate data in a #GdaDataModel
+ * @title: GdauiRawForm
+ * @stability: Stable
+ * @Image:
+ * @see_also: the #GdauiForm widget which uses the #GdauiRawForm and adds decorations such as information about data model size, and features searching.
+ *
+ * The #GdauiForm widget which uses the #GdauiRawForm and adds decorations such as
+ * information about data model size, and features searching.
*/
+
GType gdaui_raw_form_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_raw_form_new (GdaDataModel *model);
diff --git a/libgda-ui/gdaui-raw-grid.h b/libgda-ui/gdaui-raw-grid.h
index f751ecc..f3f7da2 100644
--- a/libgda-ui/gdaui-raw-grid.h
+++ b/libgda-ui/gdaui-raw-grid.h
@@ -1,6 +1,5 @@
-/* gdaui-raw-grid.h
- *
- * Copyright (C) 2002 - 2009 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2002 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -52,9 +51,18 @@ struct _GdauiRawGridClass
void (* populate_popup) (GdauiRawGrid *grid, GtkMenu *menu);
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-raw-grid
+ * @short_description: Grid widget to manipulate data in a #GdaDataModel
+ * @title: GdauiRawGrid
+ * @stability: Stable
+ * @Image: vi-raw-grid.png
+ * @see_also: the #GdauiGrid widget which uses the #GdauiRawGrid and adds decorations such as information about data model size, and features searching.
+ *
+ * The #GdauiGrid widget which uses the #GdauiRawGrid and adds decorations such as
+ * information about data model size, and features searching.
*/
+
GType gdaui_raw_grid_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_raw_grid_new (GdaDataModel *model);
diff --git a/libgda-ui/gdaui-rt-editor.h b/libgda-ui/gdaui-rt-editor.h
index 89926cb..b231e1b 100644
--- a/libgda-ui/gdaui-rt-editor.h
+++ b/libgda-ui/gdaui-rt-editor.h
@@ -1,6 +1,5 @@
-/* gdaui-rt-editor.h
- *
- * Copyright (C) 2010 Vivien Malerba <malerba gnome-db org>
+/*
+ * Copyright (C) 2010 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -52,9 +51,32 @@ struct _GdauiRtEditorClass
void (* changed) (GdauiRtEditor *editor);
};
-/*
- * Generic widget's methods
+/**
+ * SECTION:gdaui-rt-editor
+ * @short_description: Rich text editor which uses a subset of the <ulink url="http://www.txt2tags.org/markup.html";>txt2tags</ulink> markup.
+ * @title: GdauiRtEditor
+ * @stability: Stable
+ * @Image: vi-rte.png
+ * @see_also:
+ *
+ * The text entered in the editor can be formatted using bold, underline, title, ... attributes
+ * and then extracted using a subset of the <ulink url="http://www.txt2tags.org/markup.html";>txt2tags</ulink>
+ * markup. Use this widget to edit textual fields where some markup is desirable to organize the text.
+ *
+ * For example the real text used to obtain the formatting in the figure is:
+ * <programlisting>
+ *blah //italic// blah.
+ *and ** BOLD!//both italic and bold// Bold!**
+ *Nice Picture: [[[R2RrUAA...y8vLy8tYQwAA]]] Yes
+ *- List item --One--
+ *- List item **Two**
+ * - sub1
+ * - sub2</programlisting>
+ * where the picture's serialized data has been truncated here for readability
+ * (between the [[[ and ]]] markers). Pictures are usually inserted using the incorporated
+ * tollbar and not y hand (even though it's possible).
*/
+
GType gdaui_rt_editor_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_rt_editor_new (void);
diff --git a/libgda-ui/gdaui-server-operation.h b/libgda-ui/gdaui-server-operation.h
index 1e5ba01..63422ab 100644
--- a/libgda-ui/gdaui-server-operation.h
+++ b/libgda-ui/gdaui-server-operation.h
@@ -1,6 +1,5 @@
-/* gdaui-server-operation.h
- *
- * Copyright (C) 2006 Vivien Malerba
+/*
+ * Copyright (C) 2006 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -52,9 +51,20 @@ struct _GdauiServerOperationClass
GtkVBoxClass parent_class;
};
-/*
- * Generic widget's methods
-*/
+/**
+ * SECTION:gdaui-server-operation
+ * @short_description: Enter information to perform a DDL query
+ * @title: GdauiServerOperation
+ * @stability: Stable
+ * @Image:
+ * @see_also: See the #GdaServerOperation which actually holds the information to perform the action
+ *
+ * The #GdauiServerOperation widget allows the user to enter information to perform
+ * Data Definition queries (all queries which are not SELECT, INSERT, UPDATE or DELETE).
+ * For example the figure shows a #GdauiServerOperation widget set to create an index in an
+ * SQLite database.
+ */
+
GType gdaui_server_operation_get_type (void) G_GNUC_CONST;
GtkWidget *gdaui_server_operation_new (GdaServerOperation *op);
GtkWidget *gdaui_server_operation_new_in_dialog (GdaServerOperation *op, GtkWindow *parent,
diff --git a/libgda-ui/gdaui-tree-store.h b/libgda-ui/gdaui-tree-store.h
index ac15664..0a536d6 100644
--- a/libgda-ui/gdaui-tree-store.h
+++ b/libgda-ui/gdaui-tree-store.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2009 Vivien Malerba <malerba gnome-db org>
+ * Copyright (C) 2009 - 2011 Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -56,6 +56,18 @@ struct _GdauiTreeStoreClass
gboolean (*drag_delete) (GdauiTreeStore *store, const gchar *path);
};
+/**
+ * SECTION:gdaui-tree-store
+ * @short_description: Bridge between a #GdaTree and a #GtkTreeModel
+ * @title: GdauiTreeStore
+ * @stability: Stable
+ * @Image:
+ * @see_also: #GdaTree
+ *
+ * The #GdauiTreeStore implements the #GtkTreeModel interface required
+ * to display data from a #GdaTree in a #GtkTreeView widget.
+ */
+
GType gdaui_tree_store_get_type (void) G_GNUC_CONST;
GtkTreeModel *gdaui_tree_store_new (GdaTree *tree, guint n_columns, ...);
diff --git a/libgda/gda-attributes-manager.h b/libgda/gda-attributes-manager.h
index ee6e564..55a30a1 100644
--- a/libgda/gda-attributes-manager.h
+++ b/libgda/gda-attributes-manager.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -49,12 +49,68 @@ void gda_attributes_manager_foreach (GdaAttributesManager *
/* possible predefined attribute names for gda_holder_get_attribute() or gda_column_get_attribute() */
-#define GDA_ATTRIBUTE_DESCRIPTION "__gda_attr_descr" /* G_TYPE_STRING */
-#define GDA_ATTRIBUTE_NAME "__gda_attr_name" /* G_TYPE_STRING */
-#define GDA_ATTRIBUTE_NUMERIC_PRECISION "__gda_attr_numeric_precision" /* G_TYPE_INT */
-#define GDA_ATTRIBUTE_NUMERIC_SCALE "__gda_attr_numeric_scale" /* G_TYPE_INT */
-#define GDA_ATTRIBUTE_AUTO_INCREMENT "__gda_attr_autoinc" /* G_TYPE_BOOLEAN */
-#define GDA_ATTRIBUTE_IS_DEFAULT "__gda_attr_is_default" /* G_TYPE_BOOLEAN */
+/**
+ * GDA_ATTRIBUTE_DESCRIPTION:
+ * The corresponding attribute is the description of the object it refers to (value has a G_TYPE_STRING type).
+ */
+#define GDA_ATTRIBUTE_DESCRIPTION "__gda_attr_descr"
+
+/**
+ * GDA_ATTRIBUTE_NAME:
+ * The corresponding attribute is the name of the object it refers to (value has a G_TYPE_STRING type).
+ */
+#define GDA_ATTRIBUTE_NAME "__gda_attr_name"
+
+/**
+ * GDA_ATTRIBUTE_NUMERIC_PRECISION:
+ * The corresponding attribute is the number of significant digits of the object it refers to (value has a G_TYPE_INT type).
+ */
+#define GDA_ATTRIBUTE_NUMERIC_PRECISION "__gda_attr_numeric_precision"
+
+/**
+ * GDA_ATTRIBUTE_NUMERIC_SCALE:
+ * The corresponding attribute is the number of significant digits to the right of the decimal point of the object it refers to (value has a G_TYPE_INT type).
+ */
+#define GDA_ATTRIBUTE_NUMERIC_SCALE "__gda_attr_numeric_scale"
+
+/**
+ * GDA_ATTRIBUTE_AUTO_INCREMENT:
+ * The corresponding attribute specifies if the object it refers to is auto incremented (value has a G_TYPE_BOOLEAN type).
+ */
+#define GDA_ATTRIBUTE_AUTO_INCREMENT "__gda_attr_autoinc"
+
+/**
+ * GDA_ATTRIBUTE_IS_DEFAULT:
+ * The corresponding attribute specifies if the object it refers to has its value to default (value has a G_TYPE_BOOLEAN type).
+ */
+#define GDA_ATTRIBUTE_IS_DEFAULT "__gda_attr_is_default"
+
+
+/**
+ * SECTION:gda-attributes-manager
+ * @short_description: Manager for lists of attributes
+ * @title: Attributes manager
+ * @stability: Stable
+ *
+ * he #GdaAttributesManager manages lists of named values (attributes) for the benefit of
+ * others (objects or resources for which only a pointer is known). It is used internally by &LIBGDA;
+ * whenever an object or a simple structure may have several attributes.
+ *
+ * The features are similar to those of the <link linkend="g-object-set-data">g_object_set_data()</link> and similar
+ * but with the following major differences:
+ * <itemizedlist>
+ * <listitem><para>it works with GObject objects and also with simple pointers to data</para></listitem>
+ * <listitem><para>attributes names are considered static (they are not copied) and so they must either be static strings or allocated strings which exist (unchanged) while an attribute uses it as name</para></listitem>
+ * <listitem><para>it is possible to iterate through the attributes</para></listitem>
+ * <listitem><para>the associated values are expected to be #GValue values</para></listitem>
+ * </itemizedlist>
+ *
+ * Attibute names can be any string, but &LIBGDA; reserves some for its own usage, see below.
+ *
+ * The #GdaAttributesManager implements its own locking mechanism so it is thread-safe.
+ *
+ *
+ */
G_END_DECLS
diff --git a/libgda/gda-batch.h b/libgda/gda-batch.h
index 8462336..8617476 100644
--- a/libgda/gda-batch.h
+++ b/libgda/gda-batch.h
@@ -1,6 +1,5 @@
-/* gda-batch.h
- *
- * Copyright (C) 2007 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -55,6 +54,7 @@ struct _GdaBatchClass
/* signals */
void (*changed) (GdaBatch *batch, GdaStatement *changed_stmt);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -62,6 +62,19 @@ struct _GdaBatchClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-batch
+ * @short_description: Multiple SQL statements grouped together.
+ * @title: GdaBatch
+ * @stability: Stable
+ * @see_also: #GdaStatement
+ *
+ * The #GdaBatch object represents one or more SQL statements (as #GdaStatement objects) in a single object.
+ *
+ * A #GdaBatch can either be built "manually" by assembling together several #GdaStatement objects,
+ * or from an SQL string using a #GdaSqlParser object.
+ */
+
GType gda_batch_get_type (void) G_GNUC_CONST;
GdaBatch *gda_batch_new (void);
GdaBatch *gda_batch_copy (GdaBatch *orig);
diff --git a/libgda/gda-blob-op.h b/libgda/gda-blob-op.h
index 01b2e2c..57b38bf 100644
--- a/libgda/gda-blob-op.h
+++ b/libgda/gda-blob-op.h
@@ -1,5 +1,5 @@
-/* GDA Common Library
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* Authors:
* Vivien Malerba <malerba gnome-db org>
@@ -52,6 +52,7 @@ struct _GdaBlobOpClass {
glong (* write) (GdaBlobOp *op, GdaBlob *blob, glong offset);
gboolean (* write_all) (GdaBlobOp *op, GdaBlob *blob);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -59,6 +60,74 @@ struct _GdaBlobOpClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-blob-op
+ * @short_description: Binary data and BLOBs handling
+ * @title: Blobs
+ * @stability: Stable
+ * @see_also:
+ *
+ * This object is a base class for individual database providers which support BLOB types. It supports
+ * operations to read and write data in a BLOB value (of type GDA_BLOB_TYPE).
+ *
+ * Libgda offers two methods to manipulate binary values as two containers: <link linkend="GdaBinary">GdaBinary</link>
+ * and <link linkend="GdaBlob">GdaBlob</link>:
+ * <itemizedlist>
+ * <listitem><para>When reading from a data model returned by &LIBGDA; binary data will often be in a GdaBlob
+ * object, and the associated <link linkend="GdaBlobOp">GdaBlobOp</link> object can be used to manipulate the
+ * binary object (in a database for example)</para></listitem>
+ * <listitem><para>When the binary value is created by the user, then there is no point in using a GdaBlob as
+ * there can not be any <link linkend="GdaBlobOp">GdaBlobOp</link> object, so the GdaBinary container is
+ * enough.</para></listitem>
+ * </itemizedlist>
+ *
+ * Note that a <link linkend="GdaBlob">GdaBlob</link> value (the "data" attribute) will often not contain any data
+ * (or only some part of the actual BLOB)
+ * and that it's up to the user to use the associated <link linkend="GdaBlobOp">GdaBlobOp</link> object to
+ * "load" the data into the container (into the actual process heap).
+ *
+ * For example to load the 1st 40 bytes of a blob:
+ * <programlisting>
+ *GValue *blob_value = ...
+ *GdaBlob *blob;
+ *
+ *blob = (GdaBlob*) gda_value_get_blob (blob_value);
+ *gda_blob_op_read (blob->op, blob, 0, 40);
+ * </programlisting>
+ *
+ * Another example is to write the contents of a blob to a file on disk, using a special
+ * <link linkend="GdaBlobOp">GdaBlobOp</link> object (internal to &LIBGDA; which interfaces
+ * with a file in a filesystem):
+ * <programlisting>
+ *GValue *blob_value; // value to copy from
+ *GValue *tmp_value;
+ *GdaBlob *file_blob;
+ *
+ *GValue *blob_value = ...
+ *tmp_value = gda_value_new_blob_from_file ("MyFile.bin");
+ *file_blob = (GdaBlob*) gda_value_get_blob (tmp_value);
+ *
+ *if (! gda_blob_op_write_all (file_blob->op, gda_value_get_blob (blob_value))) {
+ * // error
+ *}
+ *else {
+ * gsize size;
+ * size = gda_blob_op_get_length (file_blob->op);
+ * g_print ("Wrote %s, size = %d\n", filename, size);
+ *}
+ *gda_value_free (tmp_value);
+ * </programlisting>
+ *
+ * For further information, see:
+ * <itemizedlist>
+ * <listitem><para>the section about <link linkend="gen_blobs">Binary large objects (BLOBs)</link>'s
+ * abstraction</para></listitem>
+ * <listitem><para><link linkend="libgda-provider-blobop">Virtual methods for Blob operations</link>
+ * section for more information
+ * about how to implement the virtual methods when creating a database provider</para></listitem>
+ * </itemizedlist>
+ */
+
GType gda_blob_op_get_type (void) G_GNUC_CONST;
glong gda_blob_op_get_length (GdaBlobOp *op);
diff --git a/libgda/gda-column.h b/libgda/gda-column.h
index 175189c..6764127 100644
--- a/libgda/gda-column.h
+++ b/libgda/gda-column.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 1998 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -51,6 +51,7 @@ struct _GdaColumnClass {
void (* name_changed) (GdaColumn *column, const gchar *old_name);
void (* g_type_changed) (GdaColumn *column, GType old_type, GType new_type);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -58,6 +59,16 @@ struct _GdaColumnClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-column
+ * @short_description: Management of #GdaDataModel column attributes
+ * @title: GdaDataModel columns
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaColumn object represents a #GdaDataModel's column and handle all its properties.
+ */
+
GType gda_column_get_type (void) G_GNUC_CONST;
GdaColumn *gda_column_new (void);
GdaColumn *gda_column_copy (GdaColumn *column);
@@ -91,7 +102,7 @@ void gda_column_set_attribute (GdaColumn *column, const gchar *a
GDestroyNotify destroy);
/**
- * gda_column_set_attribute_static
+ * gda_column_set_attribute_static:
* @holder: a #GdaHolder
* @attribute: attribute's name
* @value: the value to set the attribute to, or %NULL
diff --git a/libgda/gda-config.h b/libgda/gda-config.h
index cf5e86d..55b8d77 100644
--- a/libgda/gda-config.h
+++ b/libgda/gda-config.h
@@ -123,6 +123,50 @@ struct _GdaConfigClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-config
+ * @short_description: Access/Management of libgda configuration
+ * @title: Configuration
+ * @stability: Stable
+ * @see_also:
+ *
+ * The functions in this section allow applications an easy access to libgda's
+ * configuration (the list of data sources and database providers).
+ *
+ * As soon as a <link linkend="GdaConfig">GdaConfig</link> is needed (for example when requesting information
+ * about a data source or about a server provider), a single instance object is created,
+ * and no other will need to be created. A pointer to this object can be obtained with
+ * <link linkend="gda-config-get">gda_config_get()</link>. Of course one can (right after having called
+ * <link linkend="gda-init">gda_init()</link>) force the creation of a GdaConfig object with some
+ * specific properties set, using a simple call like:
+ * <programlisting>
+ *g_object_new (GDA_TYPE_CONFIG, "user-filename", "my_file", NULL);
+ * </programlisting>
+ * Please note that after that call, the caller has a reference to the newly created object, and should technically
+ * call <link linkend="g-object-unref">g_object_unref()</link> when finished using it. It is safe to do this
+ * but also pointless since that object should not be destroyed (as no other will be created) as &LIBGDA; also
+ * keeps a reference for itself.
+ *
+ *Data sources are defined in a per-user configuration file which is by default <filename>${HOME}/.libgda/config</filename> and
+ * in a system wide configuration file which is by default <filename>${prefix}/etc/libgda-4.0/config</filename>. Those
+ * filenames can be modified by setting the <link linkend="GdaConfig--user-file">user-file</link> and
+ * <link linkend="GdaConfig--system-file">system-file</link> properties for the single <link linkend="GdaConfig">GdaConfig</link>
+ * instance. Note that setting either of these properties to <literal>NULL</literal> will disable using the corresponding
+ * configuration file (DSN will exist only in memory and their definition will be lost when the application finishes).
+ *
+ * The #GdaConfig object implements its own locking mechanism so it is thread-safe.
+ *
+ * Note about localization: when the #GdaConfig loads configuration files, it filters the
+ * contents based on the current locale, so for example if your current locale is "de" then
+ * all the loaded strings (for the ones which are translated) will be in the German language.
+ * Changing the locale afterwards will have no effect on the #GdaConfig and the already loaded
+ * configuration.
+ * The consequence is that you should first call setlocale() youself in your code before using
+ * a #GdaConfig object. As a side note you should also call gtk_init() before gdaui_init() because
+ * gtk_init() calls setlocale().
+ */
+
+
GType gda_config_get_type (void) G_GNUC_CONST;
GdaConfig* gda_config_get (void);
diff --git a/libgda/gda-connection-event.h b/libgda/gda-connection-event.h
index 35f209a..31706f0 100644
--- a/libgda/gda-connection-event.h
+++ b/libgda/gda-connection-event.h
@@ -86,6 +86,18 @@ typedef enum
#define GDA_SQLSTATE_NO_ERROR "00000"
#define GDA_SQLSTATE_GENERAL_ERROR "HY000"
+/**
+ * SECTION:gda-connection-event
+ * @short_description: Any event which has occurred on a #GdaConnection
+ * @title: GdaConnectionEvent
+ * @stability: Stable
+ * @see_also: #GdaConnection
+ *
+ * Events occurring on a connection are each represented as a #GdaConnectionEvent object. Each #GdaConnection
+ * is responsible for keeping a list of past events; that list can be consulted using the
+ * gda_connection_get_events() function.
+ */
+
GType gda_connection_event_get_type (void) G_GNUC_CONST;
void gda_connection_event_set_event_type (GdaConnectionEvent *event, GdaConnectionEventType type);
diff --git a/libgda/gda-connection.h b/libgda/gda-connection.h
index 3f4562c..cd7c76f 100644
--- a/libgda/gda-connection.h
+++ b/libgda/gda-connection.h
@@ -62,6 +62,47 @@ typedef enum {
#define GDA_CONNECTION_NONEXIST_DSN_ERROR GDA_CONNECTION_DSN_NOT_FOUND_ERROR
+/**
+ * SECTION:gda-connection
+ * @short_description: A connection to a database
+ * @title: GdaConnection
+ * @stability: Stable
+ *
+ * Each connection to a database is represented by a #GdaConnection object. A connection is created (and opened)
+ * using gda_connection_open_from_dsn() if a data source has been defined, or gda_connection_open_from_string()
+ * otherwise. It is not recommended to create a #GdaConnection object using g_object_new() as the results are
+ * unpredictable (some parts won't correctly be initialized).
+ *
+ * Use the connection object to execute statements, use transactions, get meta data information, ...
+ *
+ * If supported by the database provider being used, statements can be executed asynchronously instead of
+ * blocking the execution thread untill the execution of a statement is finished. Each database provider
+ * is free to implement this feature as it wishes (using the API or using threads). The steps involved to
+ * execute a statement are then:
+ * <itemizedlist>
+ * <listitem><para>Request the statement execution using
+ * <link linkend="gda-connection-async-statement-execute">gda_connection_async_statement_execute() which returns an
+ * execution ID to be used to identify a specific request</link></para></listitem>
+ * <listitem><para>Do some useful things (that is why async. statements' excution are for)</para></listitem>
+ * <listitem><para>Use one or more times
+ * <link linkend="gda-connection-async-fetch-result">gda_connection_async_fetch_result()</link> to see
+ * if the execution is finished, using the request ID</para></listitem>
+ * <listitem><para>Use <link linkend="gda-connection-async-cancel">gda_connection_async_cancel()</link> to cancel
+ * the execution of a statement</para></listitem>
+ * </itemizedlist>
+ *
+ * The #GdaConnection object implements its own locking mechanism so it is thread-safe. However ad some database
+ * providers rely on an API which does not support threads or supports it only partially, the connections
+ * opened using those providers will only be accessible from the thread which created them (any other thread will
+ * be blocked trying to access the connection, use the
+ * <link linkend="gda-lockable-try-lock">gda_lockable_try_lock()</link> method to check it the connection
+ * is usable from a thread).
+ *
+ * If a connection really needs to be accessed by several threads at once, then it is possible to pass the
+ * #GDA_CONNECTION_OPTIONS_THREAD_SAFE flag when opening it. This flag requests that the real connection
+ * be created and really accessed in a <emphasis>private</emphasis> sub thread.
+ */
+
struct _GdaConnection {
GObject object;
GdaConnectionPrivate *priv;
diff --git a/libgda/gda-data-access-wrapper.h b/libgda/gda-data-access-wrapper.h
index 2b55a64..7aee7d1 100644
--- a/libgda/gda-data-access-wrapper.h
+++ b/libgda/gda-data-access-wrapper.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2006 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2006 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaDataAccessWrapper {
struct _GdaDataAccessWrapperClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,6 +53,17 @@ struct _GdaDataAccessWrapperClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-access-wrapper
+ * @short_description: Offers a random access on top of a cursor-only access data model
+ * @title: GdaDataAccessWrapper
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataAccessWrapper object simply wraps around another #GdaDataModel data model object
+ * and allows data to be accessed in a random way while remaining memory efficient as much as possible.
+ */
+
GType gda_data_access_wrapper_get_type (void) G_GNUC_CONST;
GdaDataModel *gda_data_access_wrapper_new (GdaDataModel *model);
diff --git a/libgda/gda-data-comparator.h b/libgda/gda-data-comparator.h
index 0001530..2b22f72 100644
--- a/libgda/gda-data-comparator.h
+++ b/libgda/gda-data-comparator.h
@@ -1,6 +1,5 @@
-/* gda-data-comparator.h
- *
- * Copyright (C) 2008 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2008 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -75,6 +74,7 @@ struct _GdaDataComparatorClass
GObjectClass parent_class;
gboolean (* diff_computed) (GdaDataComparator *comp, GdaDiff *diff);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -82,6 +82,27 @@ struct _GdaDataComparatorClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-comparator
+ * @short_description: Simple data model's contents comparison
+ * @title: GdaDataComparator
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataComparator is a simple object which takes two #GdaDataModel objects and compare them.
+ * Actual comparison is performed when the gda_data_comparator_compute_diff() is called; for each
+ * difference found, the <link linkend="GdaDataComparator-diff-computed">diff-computed</link> signal
+ * is emitted (any user installed signal handler which returns FALSE stops the computing process).
+ *
+ * There are some limitations to this object:
+ * <itemizedlist>
+ * <listitem><para>The data models compared must have the same number and type of columns</para></listitem>
+ * <listitem><para>The comparison is done column-for-column: one cannot omit columns in the comparison, nor compare
+ * columns with different positions</para></listitem>
+ * </itemizedlist>
+ */
+
+
GType gda_data_comparator_get_type (void) G_GNUC_CONST;
GObject *gda_data_comparator_new (GdaDataModel *old_model, GdaDataModel *new_model);
void gda_data_comparator_set_key_columns (GdaDataComparator *comp, const gint *col_numbers, gint nb_cols);
diff --git a/libgda/gda-data-handler.h b/libgda/gda-data-handler.h
index 6d38061..b1cad67 100644
--- a/libgda/gda-data-handler.h
+++ b/libgda/gda-data-handler.h
@@ -1,6 +1,5 @@
-/* gda-data-handler.h
- *
- * Copyright (C) 2003 - 2006 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -51,6 +50,28 @@ struct _GdaDataHandlerIface
};
+/**
+ * SECTION:gda-data-handler
+ * @short_description: Interface which provides data handling (conversions) capabilities
+ * @title: GdaDataHandler
+ * @stability: Stable
+ * @see_also:
+ *
+ * Because data types vary a lot from a DBMS to another, the #GdaDataHandler interface helps
+ * managing data in its various representations, and converting from one to another:
+ * <itemizedlist>
+ * <listitem><para>as a #GValue which is a generic value container for the C language</para></listitem>
+ * <listitem><para>as a human readable string</para></listitem>
+ * <listitem><para>as an SQL string (a string which can be used in SQL statements)</para></listitem>
+ * </itemizedlist>
+ *
+ * For each data type, a corresponding #GdaDataHandler object can be requested using the
+ * <link linkend="gda-data-handler-get-default">gda_data_handler_get_default()</link> function. However, when working
+ * with a specific database provider, it's better to use a #GdaDataHandler which may be specific to the
+ * database provider which will correctly handle each database specifics using
+ * <link linkend="gda-server-provider-get-data-handler-g-type">gda_server_provider_get_data_handler_g_type()</link> or
+ * <link linkend="gda-server-provider-get-data-handler-dbms">gda_server_provider_get_data_handler_dbms()</link>.
+ */
GType gda_data_handler_get_type (void) G_GNUC_CONST;
diff --git a/libgda/gda-data-model-array.h b/libgda/gda-data-model-array.h
index 38f0a79..c57839f 100644
--- a/libgda/gda-data-model-array.h
+++ b/libgda/gda-data-model-array.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 1998 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -47,6 +47,7 @@ struct _GdaDataModelArray {
struct _GdaDataModelArrayClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -54,6 +55,20 @@ struct _GdaDataModelArrayClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-model-array
+ * @short_description: An implementation of #GdaDataModel based on a #GArray
+ * @title: GdaDataModelArray
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataModelArray object is a data model which internally uses a #GArray to index all its rows (represented
+ * as #GdaRow objects). In this data model, all the data is stored in memory, which can be a memory limitation if the number
+ * of rows is huge.
+ * This type of data model is easy to use to store some temporary data, and has a random access mode (any value can be accessed
+ * at any time without the need for an iterator).
+ */
+
GType gda_data_model_array_get_type (void) G_GNUC_CONST;
GdaDataModel *gda_data_model_array_new_with_g_types (gint cols, ...);
GdaDataModel *gda_data_model_array_new (gint cols);
diff --git a/libgda/gda-data-model-bdb.h b/libgda/gda-data-model-bdb.h
index 49e191f..6591b06 100644
--- a/libgda/gda-data-model-bdb.h
+++ b/libgda/gda-data-model-bdb.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -49,6 +49,7 @@ struct _GdaDataModelBdbClass {
GSList *(*create_key_columns) (GdaDataModelBdb *model);
GSList *(*create_data_columns) (GdaDataModelBdb *model);
GValue *(*get_key_part) (GdaDataModelBdb *model,
+
gpointer data, gint length, gint part);
GValue *(*get_data_part) (GdaDataModelBdb *model,
gpointer data, gint length, gint part);
@@ -58,7 +59,7 @@ struct _GdaDataModelBdbClass {
gboolean (*update_data_part) (GdaDataModelBdb *model,
gpointer data, gint length, gint part,
const GValue *value, GError **error);
-
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -66,6 +67,24 @@ struct _GdaDataModelBdbClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-model-bdb
+ * @short_description: GdaDataModel to access Berkeley DB database contents
+ * @title: GdaDataModelBdb
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataModelBdb object allows to access the contents of a Berkeley DB database as a
+ * #GdaDataModel object.
+ *
+ * By default the resulting GdaDataModel contains only two columns (named "key" and "data") of type
+ * GDA_TYPE_BINARY, but this object can be subclassed to convert the key or data part of a BDB record
+ * into several columns (implement the create_key_columns(), create_data_columns(), get_key_part(), and get_data_part()
+ * virtual methods).
+ *
+ * Note: this type of data model is available only if the Berkeley DB library was found at compilation time.
+ */
+
GType gda_data_model_bdb_get_type (void) G_GNUC_CONST;
GdaDataModel *gda_data_model_bdb_new (const gchar *filename, const gchar *db_name);
diff --git a/libgda/gda-data-model-dir.h b/libgda/gda-data-model-dir.h
index b3290a5..60fe792 100644
--- a/libgda/gda-data-model-dir.h
+++ b/libgda/gda-data-model-dir.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaDataModelDir {
struct _GdaDataModelDirClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,6 +53,28 @@ struct _GdaDataModelDirClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-model-dir
+ * @short_description: GdaDataModel to list files in filesystem
+ * @title: GdaDataModelDir
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataModelDir object lists files on a filesystem which are located
+ * below a "basedir" directory, one file per row. The data model has the following columns:
+ * <itemizedlist>
+ * <listitem><para>the "dir_name" column (G_TYPE_STRING): contains the dirname part of the file</para></listitem>
+ * <listitem><para>the "file_name" column (G_TYPE_STRING): contains the file name part of the file</para></listitem>
+ * <listitem><para>the "size" column (G_TYPE_UINT): contains the size in bytes of the file</para></listitem>
+ * <listitem><para>the "mime_type" column (G_TYPE_STRING): contains the mime type of the file (if GnomeVFS has been found, and NULL otherwise)</para></listitem>
+ * <listitem><para>the "md5sum" column (G_TYPE_STRING): contains the MD5 hash of each file (if LibGCrypt has been found, and NULL otherwise)</para></listitem>
+ * <listitem><para>the "data" column (GDA_TYPE_BLOB): contains the contents of each file</para></listitem>
+ * </itemizedlist>
+ *
+ * Note that the actual values of the "mime_type", "md5sum" and "data" columns are computed only when they
+ * are requested to help with performances.
+ */
+
GType gda_data_model_dir_get_type (void) G_GNUC_CONST;
GdaDataModel *gda_data_model_dir_new (const gchar *basedir);
diff --git a/libgda/gda-data-model-import.h b/libgda/gda-data-model-import.h
index 2334213..6c13b7a 100644
--- a/libgda/gda-data-model-import.h
+++ b/libgda/gda-data-model-import.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2006 - 2010 The GNOME Foundation.
+/*
+ * Copyright (C) 2006 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -55,6 +55,37 @@ struct _GdaDataModelImportClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-model-import
+ * @short_description: Importing data from a string or a file
+ * @title: GdaDataModelImport
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * The #GdaDataModelImport data model imports data from a string or a file. The data can either be
+ * in a CSV (comma separated values) format or in an XML format as described by the libgda-array.dtd DTD (as a side
+ * way it is also possible to import data from an already-build XML tree validated against that DTD).
+ *
+ * The caller must decide, upon construction, if the new #GdaDataModelImport must support random access or simply
+ * a cursor based access. Random access makes it easier to use the resulting data model but consumes more memory as
+ * all the data is copied in memory, and is thus not suitable for large data sets. Note that importing from an
+ * already-build XML tree will always result in a random access data model.
+ *
+ * Various import options can be specified using parameters in a #GdaParameterList object. The available options
+ * depend on the format of the imported data listed here:
+ * <itemizedlist>
+ * <listitem><para>"SEPARATOR" (string, CVS import only): specifies the separator to consider</para></listitem>
+ * <listitem><para>"ESCAPE_CHAR" (string, CVS import only): specifies the character used to "escape" the strings
+ * contained between two separators</para></listitem>
+ * <listitem><para>"ENCODING" (string, CVS import only): specifies the character set used in the imported data</para></listitem>
+ * <listitem><para>"TITLE_AS_FIRST_LINE" (boolean, CVS import only): TRUE to specify that the first line of the
+ * imported data contains the column names</para></listitem>
+ * <listitem><para>"G_TYPE_<col number>" (GType, CVS import only): specifies the requested GType type for the column
+ * numbered "col number"</para></listitem>
+ * </itemizedlist>
+ */
+
+
GType gda_data_model_import_get_type (void) G_GNUC_CONST;
GdaDataModel *gda_data_model_import_new_file (const gchar *filename, gboolean random_access, GdaSet *options);
GdaDataModel *gda_data_model_import_new_mem (const gchar *data, gboolean random_access, GdaSet *options);
diff --git a/libgda/gda-data-model-iter.h b/libgda/gda-data-model-iter.h
index cf19457..dfae94d 100644
--- a/libgda/gda-data-model-iter.h
+++ b/libgda/gda-data-model-iter.h
@@ -1,6 +1,5 @@
-/* gda-data-model-iter.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -58,6 +57,7 @@ struct _GdaDataModelIterClass
void (* row_changed) (GdaDataModelIter *iter, gint row);
void (* end_of_data) (GdaDataModelIter *iter);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -65,6 +65,50 @@ struct _GdaDataModelIterClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-model-iter
+ * @short_description: Data model iterator
+ * @title: GdaDataModelIter
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * A #GdaDataModelIter object is used to iterate through the rows of a #GdaDataModel. If the data model is accessible
+ * in a random access way then any number of #GdaDataModelIter objects can be created on the same data model, and
+ * if the data model only supports a cursor based access then only one #GdaDataModelIter can be created. In any case
+ * creating a #GdaDataModelIter should be done using the gda_data_model_create_iter() method. Note that if
+ * the data model only supports a cursor based access, then calling this method several times will always return
+ * the same #GdaDataModelIter, but with its reference count increased by 1 (so you should call g_object_unref() when
+ * finished with it).
+ *
+ * When a #GdaDataModelIter is valid (that is when it points to an existing row in the data model it iterates through),
+ * the individual values (corresponding to each column of the data model, at the pointer row) can be accessed
+ * using the gda_data_model_iter_get_value_at() or gda_data_model_iter_get_value_for_field() methods
+ * (or in the same way #GdaSet's values are accessed as #GdaDataModelIter inherits the #GdaSet).
+ *
+ * Right after being created, a #GdaDataModelIter is invalid (does not point to any row of its data model). To read the
+ * first row of the data model, use the gda_data_model_iter_move_next() method. Calling this method several times will
+ * move the iterator forward, up to when the data model has no more rows and the #GdaDataModelIter will be declared invalid
+ * (and gda_data_model_iter_move_next() has returned FALSE). Note that at this point, the number of rows in the data
+ * model will be known.
+ *
+ * If the data model supports it, a #GdaDataModelIter can be moved backwards using the gda_data_model_iter_move_prev()
+ * method. However if the iterator is invalid, moving backwards will not be possible (on the contrary to
+ * gda_data_model_iter_move_next() which moves to the first row).
+ *
+ * The gda_data_model_iter_move_to_row() method, if the iterator can be moved both forward and backwards, can move the
+ * iterator to a specific row (sometimes faster than moving it forward or backwards a number of times).
+ *
+ * The following figure illustrates the #GdaDataModelIter usage:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="GdaDataModelIter.png" format="PNG" contentwidth="190mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataModelIter's usage</phrase>
+ * </textobject>
+ * </mediaobject>
+ */
+
GType gda_data_model_iter_get_type (void) G_GNUC_CONST;
const GValue *gda_data_model_iter_get_value_at (GdaDataModelIter *iter, gint col);
diff --git a/libgda/gda-data-model.h b/libgda/gda-data-model.h
index 2695fdc..b7622b7 100644
--- a/libgda/gda-data-model.h
+++ b/libgda/gda-data-model.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -119,6 +119,45 @@ struct _GdaDataModelIface {
void (* reset) (GdaDataModel *model);
};
+/**
+ * SECTION:gda-data-model
+ * @short_description: Data model interface
+ * @title: GdaDataModel
+ * @stability: Stable
+ * @see_also: #GdaDataModelIter
+ *
+ * A #GdaDataModel represents an array of values organized in rows and columns. All the data in the same
+ * column have the same type, and all the data in each row have the same semantic meaning. The #GdaDataModel is
+ * actually an interface implemented by other objects to support various kinds of data storage and operations.
+ *
+ * Depending on the real implementation, the contents of data models may be modified by the user using functions
+ * provided by the model. The actual operations a data model permits can be known using the
+ * gda_data_model_get_access_flags() method.
+ *
+ * Again, depending on the real implementation, data retrieving can be done either accessing direct random
+ * values located by their row and column, or using a cursor, or both. Use the gda_data_model_get_access_flags()
+ * method to know how the data model can be accessed.
+ * <itemizedlist>
+ * <listitem><para>Random access to a data model's contents is done using gda_data_model_get_value_at(), or using
+ * one or more #GdaDataModelIter object(s);</para></listitem>
+ * <listitem><para>Cursor access to a data model's contents is done using a #GdaDataModelIter object (only one can be created),
+ * it is <emphasis>not possible</emphasis> to use gda_data_model_get_value_at() in this mode.</para></listitem>
+ * </itemizedlist>
+ *
+ * Random access data models are easier to use since picking a value is very simple using the gda_data_model_get_value_at(),
+ * but consume more memory since all the accessible values must generally be present in memory even if they are not used.
+ * Thus if a data model must handle large quantities of data, it is generally wiser to use a data model which can be
+ * only accessed using a cursor.
+ *
+ * As a side note there are also data models which wrap other data models such as:
+ * <itemizedlist>
+ * <listitem><para>The #GdaDataProxy data model which stores temporary modifications and shows only some
+ * parts of the wrapped data model</para></listitem>
+ * <listitem><para>The #GdaDataAccessWrapper data model which offers a memory efficient random access on top of a
+ * wrapped cursor based access data model</para></listitem>
+ * </itemizedlist>
+ */
+
GType gda_data_model_get_type (void) G_GNUC_CONST;
GdaDataModelAccessFlags gda_data_model_get_access_flags (GdaDataModel *model);
diff --git a/libgda/gda-data-proxy.h b/libgda/gda-data-proxy.h
index f1c7fe2..516a62d 100644
--- a/libgda/gda-data-proxy.h
+++ b/libgda/gda-data-proxy.h
@@ -1,6 +1,5 @@
-/* gda-data-proxy.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -70,6 +69,7 @@ struct _GdaDataProxyClass
void (* filter_changed) (GdaDataProxy *proxy);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -77,6 +77,108 @@ struct _GdaDataProxyClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-proxy
+ * @short_description: Proxy to hold modifications for any #GdaDataModel, providing the #GdaDataModel interface itself
+ * @title: GdaDataProxy
+ * @stability: Stable
+ * @see_also: #GdaDataModel
+ *
+ * This object stores modifications to be made to a #GdaDataModel object which is proxied until the modifications are actually
+ * written to the #GdaDataModel, it can also filter the proxied data model to show only a subset (a defined number of continuous
+ * rows or by a filter to apply).
+ *
+ * Specifically, for a proxied data model having <varname>nb_cols</varname> columns and <varname>nb_rows</varname> rows,
+ * the #GdaDataProxy object has the following attributes:
+ * <itemizedlist>
+ * <listitem>
+ * <para><varname>2 * nb_cols</varname> columns:
+ * <itemizedlist>
+ * <listitem><para>the first (>= 0) <varname>nb_cols</varname> columns are the current values stored in the
+ * proxy (which correspond to the values of the proxied data model if the considered row has not been
+ * changed). The associated values are writable.</para></listitem>
+ * <listitem><para>the last <varname>nb_cols</varname> columns are the values stored in the proxied data model,
+ * at column <varname>col - nb_cols</varname></para></listitem>
+ * </itemizedlist>
+ * </para>
+ * </listitem>
+ * <listitem><para>a variable number of rows depending on the following attributes:
+ * <itemizedlist>
+ * <listitem><para>if the proxy is configured to have an empty row as the first row</para></listitem>
+ * <listitem><para>if the proxy only displays parts of the proxied data model</para></listitem>
+ * <listitem><para>if new rows have been added to the proxy</para></listitem>
+ * </itemizedlist>
+ * </para></listitem>
+ * </itemizedlist>
+ * This situation is illustrated in the following schema, where there is a direct mapping between the proxy's
+ * rows and the proxied data model's rows:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="data_proxy1.png" format="PNG" contentwidth="170mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataProxy's values mapping regarding the proxied data model</phrase>
+ * </textobject>
+ * </mediaobject>
+ *
+ * Note that unless explicitly mentioned, the columns are read-only.
+ *
+ * The following figures illustrate row mappings between the data proxy and the proxied data model in
+ * several situations (which can be combined, but are shown alone for simplicity):
+ * <itemizedlist>
+ * <listitem><para>situation where rows 1 and 5 have been marked as deleted from the data proxy, using
+ * <link linkend="gda-data-proxy-delete">gda_data_proxy_delete()</link> method, the data
+ * proxy has 2 rows less than the proxied data model:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="data_proxy2.png" format="PNG" contentwidth="100mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataProxy with 2 rows marked as deleted</phrase>
+ * </textobject>
+ * </mediaobject>
+ * </para></listitem>
+ * <listitem><para>situation where the data proxy only shows a sample of the proxied data model
+ * at any given time, using the
+ * <link linkend="gda-data-proxy-set-sample-size">gda_data_proxy_set_sample_size()</link> method
+ * (the sample here is 4 rows wide, and starts at row 3):
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="data_proxy3.png" format="PNG" contentwidth="100mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataProxy with a sample size of 4</phrase>
+ * </textobject>
+ * </mediaobject>
+ * </para></listitem>
+ * <listitem><para>situation where the data proxy shows a row of NULL values, using the
+ * <link linkend="GdaDataproxy-prepend-null-entry">"prepend-null-entry"</link> property:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="data_proxy4.png" format="PNG" contentwidth="100mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataProxy with an extra row of NULL values</phrase>
+ * </textobject>
+ * </mediaobject>
+ * </para></listitem>
+ * <listitem><para>situation where a row has been added to the data proxy, using for example the
+ * <link linkend="gda-data-model-append-row">gda_data_model_append_row()</link> method:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="data_proxy5.png" format="PNG" contentwidth="100mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataProxy where a row has been added</phrase>
+ * </textobject>
+ * </mediaobject>
+ * </para></listitem>
+ * </itemizedlist>
+ *
+ * The #GdaDataProxy objects are thread safe, which means any proxy object can be used from
+ * any thread at the same time as they implement their own locking mechanisms.
+ */
+
GType gda_data_proxy_get_type (void) G_GNUC_CONST;
GObject *gda_data_proxy_new (GdaDataModel *model);
diff --git a/libgda/gda-data-select.h b/libgda/gda-data-select.h
index a25f65a..d748b4a 100644
--- a/libgda/gda-data-select.h
+++ b/libgda/gda-data-select.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2008 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -62,6 +62,7 @@ struct _GdaDataSelect {
gint nb_stored_rows; /* number of GdaRow objects currently stored */
gint advertized_nrows; /* set when the number of rows becomes known, -1 untill then */
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
@@ -94,6 +95,7 @@ struct _GdaDataSelectClass {
gboolean (*fetch_prev) (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
gboolean (*fetch_at) (GdaDataSelect *model, GdaRow **prow, gint rownum, GError **error);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -101,6 +103,39 @@ struct _GdaDataSelectClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-data-select
+ * @short_description: Base class for data models returned by the execution of a SELECT statement
+ * @title: GdaDataSelect
+ * @stability: Stable
+ * @see_also: #GdaDataModel and the <link linkend="data-select">Advanced GdaDataSelect usage</link> section.
+ *
+ * This data model implements the <link linkend="GdaDataModel">GdaDataModel</link> interface and is the required
+ * base object when database providers implement a data model returned when a SELECT statement has been executed.
+ * As the <link linkend="GdaDataModel">GdaDataModel</link> interface is implemented, consult the API
+ * to access and modify the data held in a <link linkend="GdaDataSelect">GdaDataSelect</link> object.
+ *
+ * The default behaviour however is to disallow modifications, and this section documents how to characterize
+ * a <link linkend="GdaDataSelect">GdaDataSelect</link> to allow modifications. Once this is done, any modification
+ * done to the data model will be propagated to the modified table in the database using INSERT, UPDATE or DELETE
+ * statements.
+ *
+ * After any modification, it is still possible to read values from the data model (even values for rows which have
+ * been modified or inserted). The data model might then execute some SELECT statement to fetch some actualized values.
+ * Note: there is a corner case where a modification made to a row would make the row not selected at first in the data model
+ * (for example is the original SELECT statement included a clause <![CDATA["WHERE id < 100"]]> and the modification sets the
+ * <![CDATA["id"]]> value to 110), then the row will still be in the data model even though it would not be if the SELECT statement
+ * which execution created the data model in the first place was re-run. This is illustrated in the schema below:
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="writable_data_model.png" format="PNG" contentwidth="100mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaDataSelect data model's contents after some modifications</phrase>
+ * </textobject>
+ * </mediaobject>
+ */
+
GType gda_data_select_get_type (void) G_GNUC_CONST;
gboolean gda_data_select_set_row_selection_condition (GdaDataSelect *model, GdaSqlExpr *expr, GError **error);
diff --git a/libgda/gda-enums.h b/libgda/gda-enums.h
index 543f817..0765f98 100644
--- a/libgda/gda-enums.h
+++ b/libgda/gda-enums.h
@@ -46,6 +46,13 @@ typedef enum {
} GdaValueAttribute;
/* how SQL identifiers are represented */
+/**
+ * GdaSqlIdentifierStyle
+ * @GDA_SQL_IDENTIFIERS_LOWER_CASE: case insensitive SQL identifiers are represented in lower case (meaning that any SQL identifier which has a non lower case character is case sensitive)
+ * @GDA_SQL_IDENTIFIERS_UPPER_CASE: case insensitive SQL identifiers are represented in upper case (meaning that any SQL identifier which has a non upper case character is case sensitive)
+ *
+ * Specifies how SQL identifiers are represented by a specific database
+ */
typedef enum {
GDA_SQL_IDENTIFIERS_LOWER_CASE = 1 << 0,
GDA_SQL_IDENTIFIERS_UPPER_CASE = 1 << 1
diff --git a/libgda/gda-holder.h b/libgda/gda-holder.h
index 3ead1a6..b78dc3a 100644
--- a/libgda/gda-holder.h
+++ b/libgda/gda-holder.h
@@ -1,6 +1,5 @@
-/* gda-holder.h
- *
- * Copyright (C) 2003 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -67,6 +66,20 @@ struct _GdaHolderClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-holder
+ * @short_description: Container for a single #GValue
+ * @title: GdaHolder
+ * @stability: Stable
+ * @see_also: The #GdaSet object which "groups" several #GdaHolder objects
+ *
+ * The #GdaHolder is a container for a single #GValue value. It also specifies various attributes
+ * of the contained value (default value, ...)
+ *
+ * The type of a #GdaHolder has to be set and cannot be modified, except if it's initialized
+ * with a GDA_TYPE_NULL GType (representing NULL values) where it can be changed once to a real GType.
+ */
+
GType gda_holder_get_type (void) G_GNUC_CONST;
GdaHolder *gda_holder_new (GType type);
GdaHolder *gda_holder_new_inline (GType type, const gchar *id, ...);
diff --git a/libgda/gda-lockable.h b/libgda/gda-lockable.h
index a803729..da82d06 100644
--- a/libgda/gda-lockable.h
+++ b/libgda/gda-lockable.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,18 @@ struct _GdaLockableIface {
void (* i_unlock) (GdaLockable *lock);
};
+/**
+ * SECTION:gda-lockable
+ * @short_description: Interface for locking objects in a multi threaded environment
+ * @title: GdaLockable
+ * @stability: Stable
+ * @see_also: #GdaMutex and #GMutex
+ *
+ * This interface is implemented by objects which are thread safe (ie. can be used by several threads at
+ * the same time). Before using an object from a thread, one has to call gda_lockable_lock() or
+ * gda_lockable_trylock() and call gda_lockable_unlock() when the object is not used anymore.
+ */
+
GType gda_lockable_get_type (void) G_GNUC_CONST;
void gda_lockable_lock (GdaLockable *lockable);
diff --git a/libgda/gda-log.h b/libgda/gda-log.h
index 87c9e04..f9711cf 100644
--- a/libgda/gda-log.h
+++ b/libgda/gda-log.h
@@ -1,5 +1,5 @@
-/* GDA Common Library
- * Copyright (C) 1998 - 2002 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -25,6 +25,16 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gda-log
+ * @short_description: Log functions
+ * @title: Logging
+ * @stability: Stable
+ * @see_also:
+ *
+ * Logging functions.
+ */
+
/*
* For application generating logs
*/
diff --git a/libgda/gda-meta-store.h b/libgda/gda-meta-store.h
index 8523e48..816d9a4 100644
--- a/libgda/gda-meta-store.h
+++ b/libgda/gda-meta-store.h
@@ -1,5 +1,4 @@
-/* gda-meta-store.h
- *
+/*
* Copyright (C) 2008 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
@@ -69,7 +68,17 @@ typedef struct {
* value = a GValue pointer */
} GdaMetaStoreChange;
-/* suggestion */
+/**
+ * GdaMetaContext:
+ * @table_name: the name of the table <emphasis>in the GdaMetaStore's internal database</emphasis>
+ * @size: the size of the @column_names and @column_values arrays
+ * @column_names: an array of column names (columns of the @table_name table)
+ * @column_values: an array of values, one for each column named in @column_names
+ *
+ * The <structname>GdaMetaContext</structname> represents a meta data modification
+ * context: the <emphasis>how</emphasis> when used with gda_meta_store_modify_with_context(),
+ * and the <emphasis>what</emphasis> when used with gda_connection_update_meta_store().
+ */
typedef struct {
gchar *table_name;
gint size;
@@ -103,6 +112,27 @@ struct _GdaMetaStoreClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-meta-store
+ * @short_description: Dictionary object
+ * @title: GdaMetaStore
+ * @stability: Stable
+ * @see_also: #GdaMetaStruct
+ *
+ * Previous versions of &LIBGDA; relied on an XML based file to store dictionary information, such as
+ * the database's schema (tables, views, etc) and various other information. The problems were that it was
+ * difficult for an application to integrate its own data into the dictionary and that there were some
+ * performances problems as the XML file needed to be parsed (and converted into its own in-memory structure)
+ * before any data could be read out of it.
+ *
+ * The new dictionary now relies on a database structure to store its data (see the
+ * <link linkend="information_schema">database schema</link> section for a detailed description). The actual database can be a
+ * single file (using an SQLite database), an entirely in memory database (also using an SQLite database), or
+ * a more conventional backend such as a PostgreSQL database for a shared dictionary on a server.
+ *
+ * The #GdaMetaStore object is thread safe.
+ */
+
GType gda_meta_store_get_type (void) G_GNUC_CONST;
GdaMetaStore *gda_meta_store_new_with_file (const gchar *file_name);
GdaMetaStore *gda_meta_store_new (const gchar *cnc_string);
diff --git a/libgda/gda-meta-struct.h b/libgda/gda-meta-struct.h
index 7ff5b7c..59d768b 100644
--- a/libgda/gda-meta-struct.h
+++ b/libgda/gda-meta-struct.h
@@ -1,5 +1,4 @@
-/* gda-meta-struct.h
- *
+/*
* Copyright (C) 2008 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
@@ -82,6 +81,15 @@ typedef enum {
/*
* Controls which features are computed about database objects
*/
+/**
+ * GdaMetaStructFeature:
+ * @GDA_META_STRUCT_FEATURE_NONE: database objects only have their own attributes
+ * @GDA_META_STRUCT_FEATURE_FOREIGN_KEYS: foreign keys are computed for tables
+ * @GDA_META_STRUCT_FEATURE_VIEW_DEPENDENCIES: for views, the tables they use are also computed
+ * @GDA_META_STRUCT_FEATURE_ALL: all the features are computed
+ *
+ * Controls which features are computed about database objects.
+ */
typedef enum {
GDA_META_STRUCT_FEATURE_NONE = 0,
GDA_META_STRUCT_FEATURE_FOREIGN_KEYS = 1 << 0,
@@ -398,6 +406,85 @@ typedef struct {
*/
#define GDA_META_TABLE_FOREIGN_KEY_IS_DECLARED(fk) (((GdaMetaTableForeignKey*)(fk))->declared)
+/**
+ * SECTION:gda-meta-struct
+ * @short_description: In memory representation of some database objects
+ * @title: GdaMetaStruct
+ * @stability: Stable
+ * @see_also: #GdaMetaStore
+ *
+ * The #GdaMetaStruct object reads data from a #GdaMetaStore object and
+ * creates an easy to use in memory representation for some database objects. For example one can easily
+ * analyze the columns of a table (or its foreign keys) using a #GdaMetaStruct.
+ *
+ * When created, the new #GdaMetaStruct object is empty (it does not have any information about any database object).
+ * Information about database objects is computed upon request using the gda_meta_struct_complement() method. Information
+ * about individual database objects is represented by #GdaMetaDbObject structures, which can be obtained using
+ * gda_meta_struct_get_db_object() or gda_meta_struct_get_all_db_objects().
+ *
+ * Note that the #GdaMetaDbObject structures may change or may be removed or replaced by others, so it not
+ * advised to keep pointers to these structures: pointers to these structures should be considered valid
+ * as long as gda_meta_struct_complement() and other similar functions have not been called.
+ *
+ * In the following code sample, one prints the columns names and types of a table:
+ * <programlisting>
+ *GdaMetaStruct *mstruct;
+ *GdaMetaDbObject *dbo;
+ *GValue *catalog, *schema, *name;
+ *
+ * // Define name (and optionnally catalog and schema)
+ *[...]
+ *
+ *mstruct = gda_meta_struct_new ();
+ *gda_meta_struct_complement (mstruct, store, GDA_META_DB_TABLE, catalog, schema, name, NULL);
+ *dbo = gda_meta_struct_get_db_object (mstruct, catalog, schema, name);
+ *if (!dbo)
+ * g_print ("Table not found\n");
+ *else {
+ * GSList *list;
+ * for (list = GDA_META_TABLE (dbo)->columns; list; list = list->next) {
+ * GdaMetaTableColumn *tcol = GDA_META_TABLE_COLUMN (list->data);
+ * g_print ("COLUMN: %s (%s)\n", tcol->column_name, tcol->column_type);
+ * }
+ *}
+ *gda_meta_struct_free (mstruct);
+ * </programlisting>
+ * If now the database object type is not known, one can use the following code:
+ * <programlisting>
+ *GdaMetaStruct *mstruct;
+ *GdaMetaDbObject *dbo;
+ *GValue *catalog, *schema, *name;
+ *
+ * // Define name (and optionnally catalog and schema)
+ *[...]
+ *
+ *mstruct = gda_meta_struct_new ();
+ *gda_meta_struct_complement (mstruct, store, GDA_META_DB_UNKNOWN, catalog, schema, name, NULL);
+ *dbo = gda_meta_struct_get_db_object (mstruct, catalog, schema, name);
+ *if (!dbo)
+ * g_print ("Object not found\n");
+ *else {
+ * if ((dbo->obj_type == GDA_META_DB_TABLE) || (dbo->obj_type == GDA_META_DB_VIEW)) {
+ * if (dbo->obj_type == GDA_META_DB_TABLE)
+ * g_print ("Is a table\n");
+ * else if (dbo->obj_type == GDA_META_DB_VIEW) {
+ * g_print ("Is a view, definition is:\n");
+ * g_print ("%s\n", GDA_META_VIEW (dbo)->view_def);
+ * }
+ *
+ * GSList *list;
+ * for (list = GDA_META_TABLE (dbo)->columns; list; list = list->next) {
+ * GdaMetaTableColumn *tcol = GDA_META_TABLE_COLUMN (list->data);
+ * g_print ("COLUMN: %s (%s)\n", tcol->column_name, tcol->column_type);
+ * }
+ * }
+ * else
+ * g_print ("Not a table or a view\n");
+ *}
+ *gda_meta_struct_free (mstruct);
+ * </programlisting>
+ */
+
GType gda_meta_struct_get_type (void) G_GNUC_CONST;
GdaMetaStruct *gda_meta_struct_new (GdaMetaStore *store, GdaMetaStructFeature features);
GdaMetaDbObject *gda_meta_struct_complement (GdaMetaStruct *mstruct, GdaMetaDbObjectType type,
diff --git a/libgda/gda-mutex.h b/libgda/gda-mutex.h
index 402c3f5..65ec6e7 100644
--- a/libgda/gda-mutex.h
+++ b/libgda/gda-mutex.h
@@ -1,4 +1,4 @@
-/* GDA library
+/*
* Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
@@ -29,6 +29,22 @@ G_BEGIN_DECLS
typedef struct _GdaMutex GdaMutex;
+/**
+ * SECTION:gda-mutex
+ * @short_description: Recursive mutex implementation
+ * @title: GdaMutex
+ * @stability: Stable
+ * @see_also: #GdaLockable and #GMutex
+ *
+ * #GdaMutex implements a recursive mutex (unlike the #GMutex implementation which offers no
+ * guarantee about recursiveness). A recursive mutex is a mutex which can be locked several
+ * times by the same thread (and needs to be unlocked the same number of times before
+ * another thread can lock it).
+ *
+ * A #GdaMutex can safely be used even in a non multi-threaded environment in which case
+ * it does nothing.
+ */
+
GdaMutex* gda_mutex_new (void);
void gda_mutex_lock (GdaMutex *mutex);
gboolean gda_mutex_trylock (GdaMutex *mutex);
diff --git a/libgda/gda-quark-list.h b/libgda/gda-quark-list.h
index 8ea2757..2c7b302 100644
--- a/libgda/gda-quark-list.h
+++ b/libgda/gda-quark-list.h
@@ -1,5 +1,5 @@
-/* GDA Common Library
- * Copyright (C) 1998 - 2006 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* Authors:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -33,6 +33,17 @@ typedef struct _GdaQuarkList GdaQuarkList;
#define GDA_TYPE_QUARK_LIST (gda_quark_list_get_type())
+/**
+ * SECTION:gda-quark-list
+ * @short_description: Manages lists of KEY=VALUE pairs
+ * @title: Quark list
+ * @stability: Stable
+ * @see_also:
+ *
+ * This object is used mainly by database provider's implementation to parse connection
+ * strings into lists of KEY=VALUE pairs.
+ */
+
GType gda_quark_list_get_type (void) G_GNUC_CONST;
GdaQuarkList *gda_quark_list_new (void);
GdaQuarkList *gda_quark_list_new_from_string (const gchar *string);
diff --git a/libgda/gda-repetitive-statement.h b/libgda/gda-repetitive-statement.h
index 355362f..a6fac0c 100644
--- a/libgda/gda-repetitive-statement.h
+++ b/libgda/gda-repetitive-statement.h
@@ -1,6 +1,9 @@
-/* GDA library
- *
- * Copyright (C) Daniel Espinosa Ortiz 2008 <esodan gmail com>
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
+ *
+ * Authors:
+ * Daniel Espinosa Ortiz <esodan gmail com>
+ * Vivien Malerba <malerba gnome-db org>
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -43,6 +46,20 @@ struct _GdaRepetitiveStatement
GObject parent_instance;
};
+/**
+ * SECTION:gda-repetitive-statement
+ * @short_description: Execute the same statement several times with different values
+ * @title: GdaRepetitiveStatement
+ * @stability: Stable
+ * @see_also: #GdaStatement, #GdaBatch and #GdaConnection
+ *
+ * The #GdaRepetitiveStatement object allows one to specify a statement to be executed
+ * several times using different variables' values sets for each execution. Using the object
+ * has almost no interrest at all if the statement to be executed several times has no parameter.
+ *
+ * Use the gda_connection_repetitive_statement_execute() method to execute the repetitive statement.
+ */
+
GType gda_repetitive_statement_get_type (void) G_GNUC_CONST;
GdaRepetitiveStatement* gda_repetitive_statement_new (GdaStatement *stmt);
@@ -52,4 +69,4 @@ gboolean gda_repetitive_statement_append_set (GdaRepetitive
G_END_DECLS
-#endif /* _GDA_REPETITIVE_STATEMENT_H_ */
+#endif
diff --git a/libgda/gda-row.h b/libgda/gda-row.h
index 0857228..86349f6 100644
--- a/libgda/gda-row.h
+++ b/libgda/gda-row.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 1998 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -48,6 +48,7 @@ struct _GdaRow {
struct _GdaRowClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -55,6 +56,20 @@ struct _GdaRowClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-row
+ * @short_description: Individual row of a #GdaDataModelArray object
+ * @title: GdaRow
+ * @stability: Stable
+ * @see_also: #GdaDataModelArray
+ *
+ * The #GdaDataModelArray object uses #GdaRow to store each row of data. Each #GdaRow has the same
+ * number of #GValue values (equal to the number of columns of the data model).
+ *
+ * As a side note, the #GdaRow object is also used internally by the implementation of the data models returned
+ * when executing a SELECT statement.
+ */
+
GType gda_row_get_type (void) G_GNUC_CONST;
GdaRow *gda_row_new (gint count);
@@ -65,8 +80,6 @@ GValue *gda_row_get_value (GdaRow *row, gint num);
void gda_row_invalidate_value (GdaRow *row, GValue *value);
gboolean gda_row_value_is_valid (GdaRow *row, GValue *value);
-
-
G_END_DECLS
#endif
diff --git a/libgda/gda-server-operation.h b/libgda/gda-server-operation.h
index 9b21a02..86c0f94 100644
--- a/libgda/gda-server-operation.h
+++ b/libgda/gda-server-operation.h
@@ -104,6 +104,38 @@ typedef enum {
GDA_SERVER_OPERATION_STATUS_UNKNOWN
} GdaServerOperationNodeStatus;
+/**
+ * SECTION:gda-server-operation-sequences
+ * @short_description: Manipulating sequences
+ * @title: GdaServerOperation: sequences
+ * @stability: Stable
+ * @see_also: #GdaServerOperation
+ *
+ * The #GdaServerOperation object can contain sequences of templates. For example when creating a table,
+ * one can specify several foreign keys where for each foreign key, one must define the column(s) on which the
+ * foreign key applies, the referenced table and the corresponding columns of the referenced table (plus some
+ * additional information). In this case the foreign keys are defined as a sequence of templates (the foreign key
+ * definition): there can be zero or more foreign keys.
+ */
+
+/**
+ * SECTION:gda-server-operation-nodes
+ * @short_description: Getting information about parts (nodes) composing a path
+ * @title: GdaServerOperation: individual nodes
+ * @stability: Stable
+ * @see_also: #GdaServerOperation
+ *
+ * To each part of a path is associated a node (as a #GdaServerOperationNode structure). For example the
+ * "/TABLE_DEF_P/TABLE_NAME" path has two nodes, one associated to "/TABLE_DEF_P" and one to
+ * "/TABLE_DEF_P/TABLE_NAME". For more information about the path's format, see the
+ * gda_server_operation_set_value_at()'s documentation.
+ *
+ * This API is designed to get information about all the nodes present in a #GdaServerOperation object (refer to the
+ * gda_server_operation_get_root_nodes() function) and about each node of a path, and allows inspection
+ * of its contents. It is mainly reserved for database provider's implementations but can have its purpose
+ * outside of this scope.
+ */
+
typedef struct _GdaServerOperationNode {
GdaServerOperationNodeType type;
GdaServerOperationNodeStatus status;
@@ -127,6 +159,7 @@ struct _GdaServerOperationClass {
void (*seq_item_added) (GdaServerOperation *op, const gchar *seq_path, gint item_index);
void (*seq_item_remove) (GdaServerOperation *op, const gchar *seq_path, gint item_index);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -134,6 +167,35 @@ struct _GdaServerOperationClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-server-operation
+ * @short_description: Handles any DDL query in an abstract way
+ * @title: GdaServerOperation
+ * @stability: Stable
+ * @see_also:
+ *
+ * This object is basically just a data store: it can store named values, the values being
+ * organized hierarchically by their name which are similar to a Unix file path. For example a value can be read from its path
+ * using the gda_server_operation_get_value_at() method, or set using the gda_server_operation_set_value_at() method.
+ *
+ * Each #GdaServerOperation contains some structure which is usually defined by a database provider to implement
+ * a specific operation. The structure is composed of the following building blocks:
+ * <itemizedlist>
+ * <listitem><para>Named values (internally represented as a #GdaHolder object)</para></listitem>
+ * <listitem><para>Named values in a vector (internally represented as a #GdaSet object)</para></listitem>
+ * <listitem><para>Values in an array (internally represented as a #GdaDataModel object)</para></listitem>
+ * <listitem><para>Sequences of one or more of the previous blocks. A sequence can contain any number of
+ * instances of the template block (there may be lower and upper boundaries to the number of instances)</para></listitem>
+ * </itemizedlist>
+ *
+ * <emphasis>Important note:</emphasis> #GdaServerOperation objects are usually not created
+ * manually using gda_server_operation_new(), but
+ * using a #GdaServerProvider object with gda_server_provider_create_operation().
+ * See the <link linkend="DDLIntro">global introduction about DDL</link> for more information.
+ * Alternatively one can use the <link linkend="libgda-40-Convenience-functions">Convenience functions</link>
+ * which internally manipulate #GdaServerOperation objects.
+ */
+
GType gda_server_operation_get_type (void) G_GNUC_CONST;
GdaServerOperation *gda_server_operation_new (GdaServerOperationType op_type, const gchar *xml_file);
GdaServerOperationType gda_server_operation_get_op_type (GdaServerOperation *op);
diff --git a/libgda/gda-server-provider-extra.h b/libgda/gda-server-provider-extra.h
index 6e4c994..622a1fd 100644
--- a/libgda/gda-server-provider-extra.h
+++ b/libgda/gda-server-provider-extra.h
@@ -26,6 +26,17 @@
G_BEGIN_DECLS
+/**
+ * SECTION:provider-support
+ * @short_description: Methods dedicated to implementing providers
+ * @title: Misc API for database providers
+ * @stability: Stable
+ * @see_also:
+ *
+ * The methods mentioned in this section are reserved for database providers implementations and should
+ * not bu used by developers outside that scope.
+ */
+
/*
* GdaSqlParser associated to each provider
*/
diff --git a/libgda/gda-server-provider.h b/libgda/gda-server-provider.h
index 1b0e8d9..3c31f31 100644
--- a/libgda/gda-server-provider.h
+++ b/libgda/gda-server-provider.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 1998 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -66,6 +66,60 @@ struct _GdaServerProvider {
GdaServerProviderPrivate *priv;
};
+
+/**
+ * GdaServerProviderMeta:
+ * @_info:
+ * @_btypes:
+ * @_udt:
+ * @udt:
+ * @_udt_cols:
+ * @udt_cols:
+ * @_enums:
+ * @enums:
+ * @_domains:
+ * @domains:
+ * @_constraints_dom:
+ * @constraints_dom:
+ * @_el_types:
+ * @el_types:
+ * @_collations:
+ * @collations:
+ * @_character_sets:
+ * @character_sets:
+ * @_schemata:
+ * @schemata:
+ * @_tables_views:
+ * @tables_views:
+ * @_columns:
+ * @columns:
+ * @_view_cols:
+ * @view_cols:
+ * @_constraints_tab:
+ * @constraints_tab:
+ * @_constraints_ref:
+ * @constraints_ref:
+ * @_key_columns:
+ * @key_columns:
+ * @_check_columns:
+ * @check_columns:
+ * @_triggers:
+ * @triggers:
+ * @_routines:
+ * @routines:
+ * @_routine_col:
+ * @routine_col:
+ * @_routine_par:
+ * @routine_par:
+ * @_indexes_tab:
+ * @indexes_tab:
+ * @_index_cols:
+ * @index_cols:
+ *
+ * These methods must be implemented by providers to update a connection's associated metadata (in a
+ * #GdaMetaStore object), see the <link linkend="prov-metadata">Virtual methods for providers/Methods - metadata</link>
+ * for more information.
+ */
typedef struct {
/* _information_schema_catalog_name */
gboolean (*_info) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **);
@@ -189,6 +243,7 @@ typedef struct {
gboolean (*index_cols) (GdaServerProvider *, GdaConnection *, GdaMetaStore *, GdaMetaContext *, GError **,
const GValue *table_catalog, const GValue *table_schema, const GValue *table_name, const GValue *index_name);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved5) (void);
void (*_gda_reserved6) (void);
@@ -218,8 +273,30 @@ typedef struct {
GList *(*xa_recover) (GdaServerProvider *, GdaConnection *, GError **);
} GdaServerProviderXa;
+/**
+ * GdaServerProviderAsyncCallback:
+ * @provider:
+ * @cnc:
+ * @task_id:
+ * @result_status:
+ * @error:
+ * @data:
+ *
+ * Function to be called by Libgda when the associated asynchronous method invoked finishes.
+ */
typedef void (*GdaServerProviderAsyncCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id,
gboolean result_status, const GError *error, gpointer data);
+/**
+ * GdaServerProviderExecCallback:
+ * @provider:
+ * @cnc:
+ * @task_id:
+ * @result_obj:
+ * @error:
+ * @data:
+ *
+ * Function to be called by Libgda when the associated asynchronous method invoked finishes
+ */
typedef void (*GdaServerProviderExecCallback) (GdaServerProvider *provider, GdaConnection *cnc, guint task_id,
GObject *result_obj, const GError *error, gpointer data);
@@ -322,6 +399,20 @@ struct _GdaServerProviderClass {
void (*_gda_reserved6) (void);
};
+/**
+ * SECTION:gda-server-provider
+ * @short_description: Base class for all the DBMS providers
+ * @title: GdaServerProvider
+ * @stability: Stable
+ * @see_also: #GdaConnection
+ *
+ * The #GdaServerProvider class is a virtual class which all the DBMS providers
+ * must inherit, and implement its virtual methods.
+ *
+ * See the <link linkend="libgda-provider-class">Virtual methods for providers</link> section for more information
+ * about how to implement the virtual methods.
+ */
+
GType gda_server_provider_get_type (void) G_GNUC_CONST;
/* provider information */
diff --git a/libgda/gda-set.h b/libgda/gda-set.h
index 54a5b2f..08cf7d3 100644
--- a/libgda/gda-set.h
+++ b/libgda/gda-set.h
@@ -116,6 +116,22 @@ struct _GdaSetClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-set
+ * @short_description: Container for several values
+ * @title: GdaSet
+ * @stability: Stable
+ * @see_also: #GdaHolder
+ *
+ * The #GdaSet object is a container for several values (as #GdaHolder objects). The list of #GdaHolder objects is
+ * publicly accessible (and should not be modified), using the "holders" attribute. Each #GdaSet object also
+ * maintains some publicly accessible information about the #GdaHolder objects, through the #GdaSetNode, #GdaSetSource and
+ * #GdaSetGroup structures (see gda_set_get_node(), gda_set_get_source() and gda_set_get_group()).
+ *
+ * It is possible to control the values a #GdaHolder can have in the #GdaSet by connecting to the
+ * <link linkend="GdaSet-before-holder-change">"before-holder-change"</link> signal.
+ */
+
GType gda_set_get_type (void) G_GNUC_CONST;
GdaSet *gda_set_new (GSList *holders);
GdaSet *gda_set_copy (GdaSet *set);
diff --git a/libgda/gda-sql-builder.h b/libgda/gda-sql-builder.h
index 90d6eb3..8d0bdd5 100644
--- a/libgda/gda-sql-builder.h
+++ b/libgda/gda-sql-builder.h
@@ -1,6 +1,5 @@
-/* gda-sql-builder.h
- *
- * Copyright (C) 2009 - 2010 Vivien Malerba
+/*
+ * Copyright (C) 2009 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -68,6 +67,42 @@ struct _GdaSqlBuilderClass
typedef guint GdaSqlBuilderId;
+/**
+ * SECTION:gda-sql-builder
+ * @short_description: Factory object for statements
+ * @title: GdaSqlBuilder
+ * @stability: Stable
+ * @see_also: #GdaSqlParser, #GdaSqlStatement and #GdaStatement
+ *
+ * The #GdaSqlBuilder can be used to build a #GdaStatement from its structural description,
+ * much in the same way a #GdaSqlParser can be used to build a #GdaStatement from an SQL
+ * string.
+ *
+ * The #GdaSqlBuilder internally constructs a #GdaSqlStatement and uses it when requested to produce
+ * a #GdaStatement (see gda_sql_builder_get_statement()), or a #GdaSqlStatement (see
+ * gda_sql_builder_get_sql_statement()).
+ *
+ * During the building process, some pieces of the statement are constructed, and assembled into the
+ * final statement. Each of these pieces can be reused anytime in the same #GdaSqlBuilder object, and each
+ * is identified using a single unsigned integer ID. That ID is dynamically allocated by the object.
+ *
+ * The following example builds the equivalent of the <![CDATA["name='joe' AND age >= ##ageparam::int"]]> expression:
+ * <programlisting><![CDATA[
+ *GdaSqlBuilder *b=...
+ *guint id_field = gda_sql_builder_add_id (b, "name"); // build the "name" SQL identifier
+ *guint id_value = gda_sql_builder_add_expr (b, NULL, G_TYPE_STRING, "joe"); // 'joe' expression
+ *guint id_cond1 = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_EQ, id_field, id_value, 0); // "name='joe'"
+ *
+ *guint id_cond2 = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_GT,
+ * gda_sql_builder_add_id (b, "age"), // build the "age" SQL identifier
+ * gda_sql_builder_add_param (b, "ageparam", G_TYPE_INT, FALSE), // parameter
+ * 0);
+ *guint id_cond_and = gda_sql_builder_add_cond (b, GDA_SQL_OPERATOR_TYPE_AND, id_cond1, id_cond2, 0); // whole expression
+ *]]></programlisting>
+ *
+ * For more examples, see the <link linkend="howto-sqlbuilder">Build statements without using a parser</link> section.
+ */
+
GType gda_sql_builder_get_type (void) G_GNUC_CONST;
GdaSqlBuilder *gda_sql_builder_new (GdaSqlStatementType stmt_type);
GdaStatement *gda_sql_builder_get_statement (GdaSqlBuilder *builder, GError **error);
diff --git a/libgda/gda-statement-extra.h b/libgda/gda-statement-extra.h
index 53e6790..6307d57 100644
--- a/libgda/gda-statement-extra.h
+++ b/libgda/gda-statement-extra.h
@@ -1,6 +1,5 @@
-/* gda-statement-extra.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -28,17 +27,94 @@ G_BEGIN_DECLS
/* private information to implement custom
* SQL renderers for GdaStatement objects
*/
-
typedef struct _GdaSqlRenderingContext GdaSqlRenderingContext;
+
+/**
+ * GdaSqlRenderingFunc:
+ * @node: a #GdaSqlAnyPart pointer, to be cast to the correct type depending on which part the function has to render
+ * @context: the rendering context
+ * @error: a place to store errors, or %NULL
+ * @Returns: a new string, or %NULL if an error occurred
+ *
+ * Function to render any #GdaSqlAnyPart.
+ */
typedef gchar *(*GdaSqlRenderingFunc) (GdaSqlAnyPart *node, GdaSqlRenderingContext *context, GError **error);
+
+/**
+ * GdaSqlRenderingExpr:
+ * @expr: #GdaSqlExpr to render
+ * @context: the rendering context
+ * @is_default: pointer to a #gboolean which is set to TRUE if value should be considered as a default value
+ * @is_null: pointer to a #gboolean which is set to TRUE if value should be considered as NULL
+ * @error: a place to store errors, or %NULL
+ * @Returns: a new string, or %NULL if an error occurred
+ *
+ * Rendering function type to render a #GdaSqlExpr
+ */
typedef gchar *(*GdaSqlRenderingExpr) (GdaSqlExpr *expr, GdaSqlRenderingContext *context,
gboolean *is_default, gboolean *is_null,
GError **error);
+
+/**
+ * GdaSqlRenderingPSpecFunc:
+ * @pspec: #GdaSqlParamSpec to render
+ * @expr: #GdaSqlExpr which may hold the default value for the parameter, or %NULL
+ * @context: the rendering context
+ * @is_default: pointer to a #gboolean which is set to TRUE if value should be considered as a default value
+ * @is_null: pointer to a #gboolean which is set to TRUE if value should be considered as NULL
+ * @error: a place to store errors, or %NULL
+ * @Returns: a new string, or %NULL if an error occurred
+ *
+ * Rendering function type to render a #GdaSqlParamSpec
+ */
typedef gchar *(*GdaSqlRenderingPSpecFunc) (GdaSqlParamSpec *pspec, GdaSqlExpr *expr, GdaSqlRenderingContext *context,
gboolean *is_default, gboolean *is_null,
GError **error);
+
+/**
+ * GdaSqlRenderingValue:
+ * @value: the #GValue to render
+ * @context: the rendering context
+ * @error: a place to store errors, or %NULL
+ * @Returns: a new string, or %NULL if an error occurred
+ *
+ * Rendering function type to render a #GValue
+ */
typedef gchar *(*GdaSqlRenderingValue) (const GValue *value, GdaSqlRenderingContext *context, GError **error);
+/**
+ * GdaSqlRenderingContext:
+ * @flags: Global rendering options
+ * @params: Parameters to be used while doing the rendering
+ * @params_used: When rendering is complete, contains the ordered list of parameters which have been used while doing the rendering
+ * @provider: Pointer to the server provider to be used
+ * @cnc: Pointer to the connection to be used
+ * @render_value: function to render a #GValue
+ * @render_param_spec: function to render a #GdaSqlParamSpec
+ * @render_expr: function to render a #GdaSqlExpr
+ * @render_unknown: function to render a #GdaSqlStatementUnknown
+ * @render_begin: function to render a BEGIN #GdaSqlStatementTransaction
+ * @render_rollback: function to render a ROLLBACK #GdaSqlStatementTransaction
+ * @render_commit: function to render a COMMIT #GdaSqlStatementTransaction
+ * @render_savepoint: function to render a ADD SAVEPOINT #GdaSqlStatementTransaction
+ * @render_rollback_savepoint: function to render a ROLBACK SAVEPOINT #GdaSqlStatementTransaction
+ * @render_delete_savepoint: function to render a DELETE SAVEPOINT #GdaSqlStatementTransaction
+ * @render_select: function to render a #GdaSqlStatementSelect
+ * @render_insert: function to render a #GdaSqlStatementInsert
+ * @render_delete: function to render a #GdaSqlStatementDelete
+ * @render_update: function to render a #GdaSqlStatementUpdate
+ * @render_compound: function to render a #GdaSqlStatementCompound
+ * @render_field: function to render a #GdaSqlField
+ * @render_table: function to render a #GdaSqlTable
+ * @render_function: function to render a #GdaSqlFunction
+ * @render_operation: function to render a #GdaSqlOperation
+ * @render_case: function to render a #GdaSqlCase
+ * @render_select_field: function to render a #GdaSqlSelectField
+ * @render_select_target: function to render a #GdaSqlSelectTarget
+ * @render_select_join: function to render a #GdaSqlSelectJoin
+ * @render_select_from: function to render a #GdaSqlSelectFrom
+ * @render_select_order: function to render a #GdaSqlSelectOrder
+ */
struct _GdaSqlRenderingContext {
GdaStatementSqlFlag flags;
GdaSet *params;
@@ -77,6 +153,7 @@ struct _GdaSqlRenderingContext {
GdaSqlRenderingFunc render_select_from;
GdaSqlRenderingFunc render_select_order;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -88,6 +165,22 @@ struct _GdaSqlRenderingContext {
void (*_gda_reserved8) (void);
};
+/**
+ * SECTION:provider-support-sql
+ * @short_description: Adapting the SQL to the database's own SQL dialect
+ * @title: SQL rendering API
+ * @stability: Stable
+ * @see_also:
+ *
+ * &LIBGDA; is able to render a #GdaStatement statement to SQL in a generic way (as close as possible to the SQL
+ * standard). However as each database has ultimately its own SQL dialect, some parts of the rendering has
+ * to be specialized.
+ *
+ * Customization is achieved by providing custom implementations of SQL rendering functions for each kind of
+ * part in a #GdaSqlStatement structure, all packed in a #GdaSqlRenderingContext context structure. Functions
+ * which are not customized will be implemented by the default ones.
+ */
+
gchar *gda_statement_to_sql_real (GdaStatement *stmt, GdaSqlRenderingContext *context, GError **error);
G_END_DECLS
diff --git a/libgda/gda-statement.h b/libgda/gda-statement.h
index 1612d75..167eadf 100644
--- a/libgda/gda-statement.h
+++ b/libgda/gda-statement.h
@@ -1,6 +1,5 @@
-/* gda-statement.h
- *
- * Copyright (C) 2007 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -36,6 +35,16 @@ G_BEGIN_DECLS
extern GQuark gda_statement_error_quark (void);
#define GDA_STATEMENT_ERROR gda_statement_error_quark ()
+/**
+ * GdaStatementError:
+ * @GDA_STATEMENT_PARSE_ERROR:
+ * @GDA_STATEMENT_SYNTAX_ERROR:
+ * @GDA_STATEMENT_NO_CNC_ERROR:
+ * @GDA_STATEMENT_CNC_CLOSED_ERROR:
+ * @GDA_STATEMENT_EXEC_ERROR:
+ * @GDA_STATEMENT_PARAM_TYPE_ERROR:
+ * @GDA_STATEMENT_PARAM_ERROR:
+ */
typedef enum
{
GDA_STATEMENT_PARSE_ERROR,
@@ -47,6 +56,16 @@ typedef enum
GDA_STATEMENT_PARAM_ERROR
} GdaStatementError;
+/**
+ * GdaStatementModelUsage:
+ * @GDA_STATEMENT_MODEL_RANDOM_ACCESS: access to the data model will be random (usually this will result in a data model completely stored in memory)
+ * @GDA_STATEMENT_MODEL_CURSOR_FORWARD: access to the data model will be done using a cursor moving forward
+ * @GDA_STATEMENT_MODEL_CURSOR_BACKWARD: access to the data model will be done using a cursor moving backward
+ * @GDA_STATEMENT_MODEL_CURSOR: access to the data model will be done using a cursor (moving both forward and backward)
+ * @GDA_STATEMENT_MODEL_ALLOW_NOPARAM: specifies that the data model should be executed even if some parameters required to execute it are invalid (in this case the data model will have no row, and will automatically be re-run when the missing parameters are once again valid)
+ *
+ * These flags specify how the #GdaDataModel returned when executing a #GdaStatement will be used
+ */
typedef enum {
GDA_STATEMENT_MODEL_RANDOM_ACCESS = 1 << 0,
GDA_STATEMENT_MODEL_CURSOR_FORWARD = 1 << 1,
@@ -55,6 +74,19 @@ typedef enum {
GDA_STATEMENT_MODEL_ALLOW_NOPARAM = 1 << 3
} GdaStatementModelUsage;
+/**
+ * GdaStatementSqlFlag:
+ * @GDA_STATEMENT_SQL_PARAMS_AS_VALUES: rendering will replace parameters with their values
+ * @GDA_STATEMENT_SQL_PRETTY: rendering will include newlines and indentation to make it easy to read
+ * @GDA_STATEMENT_SQL_PARAMS_LONG: parameters will be rendered using the "/* name:<param_name> ... */" syntax
+ * @GDA_STATEMENT_SQL_PARAMS_SHORT: parameters will be rendered using the "##<param_name>..." syntax
+ * @GDA_STATEMENT_SQL_PARAMS_AS_COLON: parameters will be rendered using the ":<param_name>" syntax
+ * @GDA_STATEMENT_SQL_PARAMS_AS_DOLLAR: parameters will be rendered using the "$<param_number>" syntax where parameters are numbered starting from 1
+ * @GDA_STATEMENT_SQL_PARAMS_AS_QMARK: parameters will be rendered using the "?<param_number>" syntax where parameters are numbered starting from 1
+ * @GDA_STATEMENT_SQL_PARAMS_AS_UQMARK: parameters will be rendered using the "?" syntax
+ *
+ * Specifies rendering options
+ */
typedef enum {
GDA_STATEMENT_SQL_PARAMS_AS_VALUES = 0,
GDA_STATEMENT_SQL_PRETTY = 1 << 0,
@@ -82,6 +114,7 @@ struct _GdaStatementClass
void (*checked) (GdaStatement *stmt, GdaConnection *cnc, gboolean checked);
void (*reset) (GdaStatement *stmt);
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -89,6 +122,29 @@ struct _GdaStatementClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-statement
+ * @short_description: Single SQL statement
+ * @title: GdaStatement
+ * @stability: Stable
+ * @see_also: #GdaBatch
+ *
+ * The #GdaStatement represents a single SQL statement (multiple statements can be grouped in a #GdaBatch object).
+ *
+ * A #GdaStatement can either be built by describing its constituing parts using a #GdaSqlBuilder object,
+ * or from an SQL statement using a #GdaSqlParser object.
+ *
+ * A #GdaConnection can use a #GdaStatement to:
+ * <itemizedlist>
+ * <listitem><para>prepare it for a future execution, the preparation step involves converting the #GdaStatement
+ * object into a structure used by the database's own API, see gda_connection_statement_prepare()</para></listitem>
+ * <listitem><para>execute it using gda_connection_statement_execute_select() if it is known that the statement is a
+ * selection statement, gda_connection_statement_execute_non_select() if it is not a selection statement, or
+ * gda_connection_statement_execute() when the type of expected result is unknown.</para></listitem>
+ * </itemizedlist>
+ * Note that it is possible to use the same #GdaStatement object at the same time with several #GdaConnection objects.
+ */
+
GType gda_statement_get_type (void) G_GNUC_CONST;
GdaStatement *gda_statement_new (void);
GdaStatement *gda_statement_copy (GdaStatement *orig);
diff --git a/libgda/gda-transaction-status.h b/libgda/gda-transaction-status.h
index 5cda17e..56ca211 100644
--- a/libgda/gda-transaction-status.h
+++ b/libgda/gda-transaction-status.h
@@ -1,5 +1,5 @@
-/* GDA client library
- * Copyright (C) 1998 - 2006 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -41,17 +41,34 @@ typedef struct _GdaTransactionStatus GdaTransactionStatus;
typedef struct _GdaTransactionStatusClass GdaTransactionStatusClass;
typedef struct _GdaTransactionStatusEvent GdaTransactionStatusEvent;
+/**
+ * GdaTransactionStatusEventType:
+ * @GDA_TRANSACTION_STATUS_EVENT_SAVEPOINT:
+ * @GDA_TRANSACTION_STATUS_EVENT_SQL:
+ * @GDA_TRANSACTION_STATUS_EVENT_SUB_TRANSACTION:
+ */
typedef enum {
GDA_TRANSACTION_STATUS_EVENT_SAVEPOINT,
GDA_TRANSACTION_STATUS_EVENT_SQL,
GDA_TRANSACTION_STATUS_EVENT_SUB_TRANSACTION
} GdaTransactionStatusEventType;
+/**
+ * GdaTransactionStatusState:
+ * @GDA_TRANSACTION_STATUS_STATE_OK:
+ * @GDA_TRANSACTION_STATUS_STATE_FAILED:
+ */
typedef enum {
GDA_TRANSACTION_STATUS_STATE_OK,
GDA_TRANSACTION_STATUS_STATE_FAILED
} GdaTransactionStatusState;
+/**
+ * GdaTransactionStatusEvent:
+ * @trans:
+ * @type:
+ * @conn_event:
+ */
struct _GdaTransactionStatusEvent {
GdaTransactionStatus *trans;
GdaTransactionStatusEventType type;
@@ -62,6 +79,7 @@ struct _GdaTransactionStatusEvent {
} pl;
GdaConnectionEvent *conn_event;
+ /*< private >*/
gpointer _gda_reserved1;
gpointer _gda_reserved2;
};
@@ -74,6 +92,7 @@ struct _GdaTransactionStatus {
GdaTransactionStatusState state;
GList *events;
+ /*< private >*/
gpointer _gda_reserved1;
gpointer _gda_reserved2;
};
@@ -81,6 +100,7 @@ struct _GdaTransactionStatus {
struct _GdaTransactionStatusClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -88,6 +108,27 @@ struct _GdaTransactionStatusClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-transaction-status
+ * @short_description: Keeps track of the transaction status of a connection
+ * @title: GdaTransactionStatus
+ * @stability: Stable
+ * @see_also: #GdaConnection
+ *
+ * On any connection (as a #GdaConnection object), if the database provider used by the connection
+ * supports it, transactions may be started, committed or rolledback, or savepoints added, removed or rolledback.
+ * These operations can be performed using Libgda's API (such as gda_connection_begin_transaction()), or directly
+ * using some SQL on the connection (usually a "BEGIN;" command). The #GdaTransactionStatus's aim is to
+ * make it easy to keep track of all the commands which have been issued on a connection regarding transactions.
+ *
+ * One #GdaTransactionStatus object is automatically attached to a #GdaConnection when a transaction is started, and
+ * is destroyed when the transaction is finished. A pointer to this object can be fetched using
+ * gda_connection_get_transaction_status() (beware that it should then not be modified). The end user is not
+ * supposed to instantiate #GdaTransactionStatus objects
+ *
+ * #GdaTransactionStatus's attributes are directly accessible using the public members of the object.
+ */
+
GType gda_transaction_status_get_type (void) G_GNUC_CONST;
GdaTransactionStatus *gda_transaction_status_new (const gchar *name);
diff --git a/libgda/gda-tree-manager.h b/libgda/gda-tree-manager.h
index 69a7dec..06d1143 100644
--- a/libgda/gda-tree-manager.h
+++ b/libgda/gda-tree-manager.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -74,6 +74,26 @@ struct _GdaTreeManagerClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-tree-manager
+ * @short_description: Base class for all the tree managers
+ * @title: GdaTreeManager
+ * @stability: Stable
+ * @see_also:
+ *
+ * A #GdaTreeManager object is responsible for creating nodes in the tree(s) for which it
+ * operates.
+ *
+ * When creating nodes, a #GdaTreeManager object can (depending on its implementation), get some
+ * named attributes from the node below which it has to create nodes, using the gda_tree_node_fetch_attribute()
+ * or gda_tree_node_get_node_attribute(). For example the #GdaTreeMgrColumns manager (which creates a node for each column
+ * of a table) needs the table name and the schema in which the table is; both can be specified using an
+ * object's property, or, if not specified that way, are fetched as attributes.
+ *
+ * The #GdaTreeManager itself is an abstract type (which can't be instantiated). Use an existing sub class or subclass
+ * it yourself.
+ */
+
GType gda_tree_manager_get_type (void) G_GNUC_CONST;
GdaTreeManager *gda_tree_manager_new_with_func (GdaTreeManagerNodesFunc update_func);
diff --git a/libgda/gda-tree-mgr-columns.h b/libgda/gda-tree-mgr-columns.h
index a9ccbd3..c31749e 100644
--- a/libgda/gda-tree-mgr-columns.h
+++ b/libgda/gda-tree-mgr-columns.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,26 @@ struct _GdaTreeMgrColumnsClass {
GdaTreeManagerClass object_class;
};
+/**
+ * SECTION:gda-tree-mgr-columns
+ * @short_description: A tree manager which creates a node for each column of a table
+ * @title: GdaTreeMgrColumns
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTreeMgrColumns is a #GdaTreeManager object which creates a node for
+ * each column in a table.
+ *
+ * It uses the #GdaMetaStore associated to a #GdaConnection to get the columns list
+ * for a table designated by its name and the database schema it is in; it's up to the
+ * caller to make sure the data in the #GdaMetaStore is up to date.
+ *
+ * The #GdaConnection to be used needs to be specified when the object is created. The table
+ * name and schema can however be specified when the object is created, and if not, are
+ * fetched from the #GdaTreeNode below which the nodes will be placed (using
+ * gda_tree_node_fetch_attribute()).
+ */
+
GType gda_tree_mgr_columns_get_type (void) G_GNUC_CONST;
GdaTreeManager* gda_tree_mgr_columns_new (GdaConnection *cnc, const gchar *schema,
const gchar *table_name);
diff --git a/libgda/gda-tree-mgr-label.h b/libgda/gda-tree-mgr-label.h
index c54e2ab..6445163 100644
--- a/libgda/gda-tree-mgr-label.h
+++ b/libgda/gda-tree-mgr-label.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,17 @@ struct _GdaTreeMgrLabelClass {
GdaTreeManagerClass object_class;
};
+/**
+ * SECTION:gda-tree-mgr-label
+ * @short_description: A tree manager which creates a single node
+ * @title: GdaTreeMgrLabel
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTreeMgrLabel is a #GdaTreeManager object which creates a single node. This tree manager
+ * is useful to create "sections" in a #GdaTree hierarchy.
+ */
+
GType gda_tree_mgr_label_get_type (void) G_GNUC_CONST;
GdaTreeManager* gda_tree_mgr_label_new (const gchar *label);
diff --git a/libgda/gda-tree-mgr-schemas.h b/libgda/gda-tree-mgr-schemas.h
index d0a0ad9..3fbaa9b 100644
--- a/libgda/gda-tree-mgr-schemas.h
+++ b/libgda/gda-tree-mgr-schemas.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,22 @@ struct _GdaTreeMgrSchemasClass {
GdaTreeManagerClass object_class;
};
+/**
+ * SECTION:gda-tree-mgr-schemas
+ * @short_description: A tree manager which creates a node for each schema in a database
+ * @title: GdaTreeMgrSchemas
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTreeMgrSchemas is a #GdaTreeManager object which creates a node for
+ * each schema in a database.
+ *
+ * It uses the #GdaMetaStore associated to a #GdaConnection to get the schemas list; it's up to the
+ * caller to make sure the data in the #GdaMetaStore is up to date.
+ *
+ * The #GdaConnection to be used needs to be specified when the object is created.
+ */
+
GType gda_tree_mgr_schemas_get_type (void) G_GNUC_CONST;
GdaTreeManager* gda_tree_mgr_schemas_new (GdaConnection *cnc);
diff --git a/libgda/gda-tree-mgr-select.h b/libgda/gda-tree-mgr-select.h
index 811eb5d..a83df28 100644
--- a/libgda/gda-tree-mgr-select.h
+++ b/libgda/gda-tree-mgr-select.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,28 @@ struct _GdaTreeMgrSelectClass {
GdaTreeManagerClass object_class;
};
+/**
+ * SECTION:gda-tree-mgr-select
+ * @short_description: A tree manager which creates a node for each row resulting from the execution of a SELECT statement
+ * @title: GdaTreeMgrSelect
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTreeMgrSelect is a #GdaTreeManager object which executes a SELECT statement and
+ * creates a node for each row in the result.
+ *
+ * The #GdaConnection and SELECT #GdaStatement to be used need to be specified when the object is created.
+ * If the SELECT statement to be used needs some parameters, then it is possible to give values to some of them
+ * when constructing the object, but not necessary.
+ *
+ * If the SELECT statement needs some parameters which have not been provided during the construction, then
+ * these parameters will be fetched from the #GdaTreeNode below which the nodes will be placed (using
+ * gda_tree_node_fetch_attribute()).
+ *
+ * For each node created, an attribute is set for each column in the SELECT statement: the attribute name is
+ * the column name and the attribute value is the value if that column.
+ */
+
GType gda_tree_mgr_select_get_type (void) G_GNUC_CONST;
GdaTreeManager* gda_tree_mgr_select_new (GdaConnection *cnc, GdaStatement *stmt, GdaSet *params);
diff --git a/libgda/gda-tree-mgr-tables.h b/libgda/gda-tree-mgr-tables.h
index f22e0da..c0534ce 100644
--- a/libgda/gda-tree-mgr-tables.h
+++ b/libgda/gda-tree-mgr-tables.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -48,6 +48,26 @@ struct _GdaTreeMgrTablesClass {
GdaTreeManagerClass object_class;
};
+/**
+ * SECTION:gda-tree-mgr-tables
+ * @short_description: A tree manager which creates a node for each table in a schema
+ * @title: GdaTreeMgrTables
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTreeMgrTables is a #GdaTreeManager object which creates a node for
+ * each table in a database schema.
+ *
+ * It uses the #GdaMetaStore associated to a #GdaConnection to get the tables list
+ * in database schema; it's up to the
+ * caller to make sure the data in the #GdaMetaStore is up to date.
+ *
+ * The #GdaConnection to be used needs to be specified when the object is created. The
+ * schema can however be specified when the object is created, and if not, is
+ * fetched from the #GdaTreeNode below which the nodes will be placed (using
+ * gda_tree_node_fetch_attribute()).
+ */
+
GType gda_tree_mgr_tables_get_type (void) G_GNUC_CONST;
GdaTreeManager* gda_tree_mgr_tables_new (GdaConnection *cnc, const gchar *schema);
diff --git a/libgda/gda-tree-node.h b/libgda/gda-tree-node.h
index 970cc9d..f44a60f 100644
--- a/libgda/gda-tree-node.h
+++ b/libgda/gda-tree-node.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -69,6 +69,21 @@ struct _GdaTreeNodeClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-tree-node
+ * @short_description: A node in a #GdaTree
+ * @title: GdaTreeNode
+ * @stability: Stable
+ * @see_also:
+ *
+ * Every node in a #GdaTree tree is represented by a single #GdaTreeNode object. There is no distinction
+ * between nodes which have children and those which don't (leaf nodes).
+ *
+ * The #GdaTreeNode is very basic as it only has a "name" attribute: users are encouraged to subclass it to
+ * add more features if needed (and make use of them by defining a #GdaTreeManagerNodeFunc function and
+ * calling gda_tree_manager_set_node_create_func()).
+ */
+
GType gda_tree_node_get_type (void) G_GNUC_CONST;
GdaTreeNode* gda_tree_node_new (const gchar *name);
diff --git a/libgda/gda-tree.h b/libgda/gda-tree.h
index d10efde..fa792db 100644
--- a/libgda/gda-tree.h
+++ b/libgda/gda-tree.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -66,6 +66,21 @@ struct _GdaTreeClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-tree
+ * @short_description: A tree-structure
+ * @title: GdaTree
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaTree is the top level object representing hierarchically structured data. From this object it
+ * is also possible (depending on the tree managers it uses), to clean (remove all the nodes) the whole tree,
+ * or to request a complete or partial update of the nodes.
+ *
+ * It is also possible to set attributes to the tree itself (as it is possible to do for tree nodes),
+ * or to dump the whole or part of a tree in an indented and easy to read fashion.
+ */
+
GType gda_tree_get_type (void) G_GNUC_CONST;
GdaTree* gda_tree_new (void);
void gda_tree_add_manager (GdaTree *tree, GdaTreeManager *manager);
diff --git a/libgda/gda-util.h b/libgda/gda-util.h
index cd4fec1..1440896 100644
--- a/libgda/gda-util.h
+++ b/libgda/gda-util.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 1998 - 2010 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Rodrigo Moya <rodrigo gnome-db org>
@@ -33,6 +33,16 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gda-util
+ * @short_description: Utility functions
+ * @title: Utility functions
+ * @stability: Stable
+ * @see_also:
+ *
+ * Some usefull functions.
+ */
+
/*
* Type utilities
*/
diff --git a/libgda/gda-value.h b/libgda/gda-value.h
index 37f93d5..5b2cbc2 100644
--- a/libgda/gda-value.h
+++ b/libgda/gda-value.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 1998 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -58,18 +58,39 @@ G_BEGIN_DECLS
#define GDA_VALUE_HOLDS_TIME(value) G_VALUE_HOLDS(value, GDA_TYPE_TIME)
#define GDA_VALUE_HOLDS_TIMESTAMP(value) G_VALUE_HOLDS(value, GDA_TYPE_TIMESTAMP)
+/**
+ * GdaGeometricPoint:
+ * @x:
+ * @y:
+ */
typedef struct {
gdouble x;
gdouble y;
} GdaGeometricPoint;
+/**
+ * GdaNumeric:
+ * @number:
+ * @precision:
+ * @width:
+ */
typedef struct {
gchar *number;
glong precision;
glong width;
+
+ /*< private >*/
gpointer reserved; /* reserved for future usage with GMP (http://gmplib.org/) */
} GdaNumeric;
+/**
+ * GdaTime:
+ * @hour:
+ * @minute:
+ * @second:
+ * @fraction:
+ * @timezone:
+ */
typedef struct {
gushort hour;
gushort minute;
@@ -78,6 +99,17 @@ typedef struct {
glong timezone; /* # of seconds to the east UTC */
} GdaTime;
+/**
+ * GdaTimestamp:
+ * @year: representation of the date
+ * @month: month representation of the date, as a number between 1 and 12
+ * @day: day representation of the date, as a number between 1 and 31
+ * @hour:
+ * @minute:
+ * @second:
+ * @fraction:
+ * @timezone:
+ */
typedef struct {
gshort year;
gushort month;
@@ -89,6 +121,11 @@ typedef struct {
glong timezone; /* # of seconds to the east UTC */
} GdaTimestamp;
+/**
+ * GdaBinary:
+ * @data:
+ * @binary_length:
+ */
typedef struct {
guchar *data;
glong binary_length;
@@ -110,6 +147,40 @@ typedef struct {
#define gda_value_isa(value, type) (G_VALUE_HOLDS(value, type))
+/**
+ * SECTION:gda-value
+ * @short_description: Assorted functions for dealing with #GValue values
+ * @title: A single Value
+ * @stability: Stable
+ * @see_also: #GValue and #GdaBlobOp
+ *
+ * &LIBGDA; manages each individual value within an opaque #GValue structure. Any GValue type can be used,
+ * and &LIBGDA; adds a few more data types usually found in DBMS such as NUMERIC, TIME, TIMESTAMP, GEOMETRIC POINT, BINARY and BLOB.
+ *
+ * Libgda makes a distinction between binary and blob types
+ * <itemizedlist>
+ * <listitem><para>binary data can be inserted into an SQL statement using a
+ * (DBMS dependent) syntax, such as "X'ABCD'" syntax for SQLite or the binary strings syntax for PostgreSQL. Binary data
+ * is manipulated using a #GdaBinary structure (which is basically a bytes buffer and a length attribute).
+ * </para></listitem>
+ * <listitem><para>blob data are a special feature that some DBMS have which requires some non SQL code to manipulate them.
+ * Usually only a reference is stored in each table containing a blob, and the actual blob data resides somewhere on the disk
+ * (while still being managed transparently by the database). For example PotsgreSQL stores blobs as files on the disk and
+ * references them using object identifiers (Oid). Blob data
+ * is manipulated using a #GdaBlob structure which encapsulates a #GdaBinary structure and adds a reference to a
+ * #GdaBlobOp object used to read and write data from and to the blob.
+ * </para></listitem>
+ * </itemizedlist>
+ * Please note that is distinction between binary data and blobs is Libgda only and does not reflect the DBMS's documentations;
+ * for instance MySQL has several BLOB types but Libgda interprets them as binary types.
+ *
+ * Each provider or connection can be queried about its blob support using the gda_server_provider_supports_feature() or
+ * gda_connection_supports_feature() methods.
+ *
+ * The NULL value is a special case value: it is represented by to a zero-filled (uninitialized) #GValue and has a type equal
+ * to %GDA_TYPE_NULL.
+ */
+
GValue *gda_value_new (GType type);
GValue *gda_value_new_binary (const guchar *val, glong size);
@@ -204,6 +275,13 @@ GType gda_short_get_type (void) G_GNUC_CONST;
GType gda_ushort_get_type (void) G_GNUC_CONST;
/* Helper macros */
+/**
+ * gda_value_new_null:
+ *
+ * Creates a new #GValue of type %GDA_TYPE_NULL representing a NULL value
+ *
+ * Returns: (transfer full): a new #GValue
+ */
#define gda_value_new_null() (g_new0 (GValue, 1))
G_END_DECLS
diff --git a/libgda/gda-xa-transaction.h b/libgda/gda-xa-transaction.h
index 8ba5698..e5ea3e8 100644
--- a/libgda/gda-xa-transaction.h
+++ b/libgda/gda-xa-transaction.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2008 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -67,13 +67,53 @@ struct _GdaXaTransactionClass {
void (*_gda_reserved4) (void);
};
+
+/**
+ * GdaXaTransactionId:
+ * @format: any number
+ * @gtrid_length: number between 1 and 64
+ * @bqual_length: number between 1 and 64
+ * @data:
+ */
struct _GdaXaTransactionId {
- guint32 format; /* any number */
- gushort gtrid_length; /* 1-64 */
- gushort bqual_length; /* 1-64 */
+ guint32 format;
+ gushort gtrid_length;
+ gushort bqual_length;
char data [128];
};
+/**
+ * SECTION:gda-xa-transaction
+ * @short_description: Distributed transaction manager
+ * @title: GdaXaTransaction
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaXaTransaction object acts as a distributed transaction manager: to make sure local transactions on several
+ * connections (to possibly different databases and database types) either all succeed or all fail. For more information,
+ * see the X/Open CAE document Distributed Transaction Processing: The XA Specification.
+ * This document is published by The Open Group and available at
+ * <ulink url="http://www.opengroup.org/public/pubs/catalog/c193.htm";>http://www.opengroup.org/public/pubs/catalog/c193.htm</ulink>.
+ *
+ * The two phases commit protocol is implemented during the execution of a distributed transaction: modifications
+ * made on any connection are first <emphasis>prepared</emphasis> (which means that they are store in the database), and
+ * if that phase succeeded for all the involved connections, then the <emphasis>commit</emphasis> phase is executed
+ * (where all the data previously stored during the <emphasis>prepare</emphasis> phase are actually committed).
+ * That second phase may actually fail, but the distributed transaction will still be considered as sucessfull
+ * as the data stored during the <emphasis>prepare</emphasis> phase can be committed afterwards.
+ *
+ * A distributed transaction involves the following steps:
+ * <orderedlist>
+ * <listitem><para>Create a #GdaXaTransaction object</para></listitem>
+ * <listitem><para>Register the connections which will be part of the distributed transaction with that object
+ * using gda_xa_transaction_register_connection()</para></listitem>
+ * <listitem><para>Beging the distributed transaction using gda_xa_transaction_begin()</para></listitem>
+ * <listitem><para>Work individually on each connection as normally (make modifications)</para></listitem>
+ * <listitem><para>Commit the distributed transaction using gda_xa_transaction_commit()</para></listitem>
+ * <listitem><para>Discard the #GdaXaTransaction object using g_object_unref()</para></listitem>
+ * </orderedlist>
+ */
+
GType gda_xa_transaction_get_type (void) G_GNUC_CONST;
GdaXaTransaction *gda_xa_transaction_new (guint32 format, const gchar *global_transaction_id);
diff --git a/libgda/handlers/gda-handler-bin.h b/libgda/handlers/gda-handler-bin.h
index 6785486..25dc8ed 100644
--- a/libgda/handlers/gda-handler-bin.h
+++ b/libgda/handlers/gda-handler-bin.h
@@ -1,6 +1,5 @@
-/* gda-handler-bin.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -47,11 +46,22 @@ struct _GdaHandlerBinClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-bin
+ * @short_description: Default handler for binary values
+ * @title: GdaHanderBin
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_bin_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_bin_new (void);
diff --git a/libgda/handlers/gda-handler-boolean.h b/libgda/handlers/gda-handler-boolean.h
index 3c8e1c9..a036fcf 100644
--- a/libgda/handlers/gda-handler-boolean.h
+++ b/libgda/handlers/gda-handler-boolean.h
@@ -1,6 +1,5 @@
-/* gda-handler-boolean.h
- *
- * Copyright (C) 2003 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -47,11 +46,22 @@ struct _GdaHandlerBooleanClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-boolean
+ * @short_description: Default handler for boolean values
+ * @title: GdaHanderBoolean
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_boolean_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_boolean_new (void);
diff --git a/libgda/handlers/gda-handler-numerical.h b/libgda/handlers/gda-handler-numerical.h
index 4fc7b66..ce85021 100644
--- a/libgda/handlers/gda-handler-numerical.h
+++ b/libgda/handlers/gda-handler-numerical.h
@@ -1,6 +1,5 @@
-/* gda-handler-numerical.h
- *
- * Copyright (C) 2003 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -48,11 +47,22 @@ struct _GdaHandlerNumericalClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-numerical
+ * @short_description: Default handler for numeric values
+ * @title: GdaHanderNumerical
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_numerical_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_numerical_new (void);
diff --git a/libgda/handlers/gda-handler-string.h b/libgda/handlers/gda-handler-string.h
index 4b0082f..da79d75 100644
--- a/libgda/handlers/gda-handler-string.h
+++ b/libgda/handlers/gda-handler-string.h
@@ -1,6 +1,5 @@
-/* gda-handler-string.h
- *
- * Copyright (C) 2003 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -47,11 +46,22 @@ struct _GdaHandlerStringClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-string
+ * @short_description: Default handler for string values
+ * @title: GdaHanderString
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_string_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_string_new (void);
diff --git a/libgda/handlers/gda-handler-time.h b/libgda/handlers/gda-handler-time.h
index 2afd2c1..8702004 100644
--- a/libgda/handlers/gda-handler-time.h
+++ b/libgda/handlers/gda-handler-time.h
@@ -1,6 +1,5 @@
-/* gda-handler-time.h
- *
- * Copyright (C) 2003 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2003 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -47,11 +46,22 @@ struct _GdaHandlerTimeClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-time
+ * @short_description: Default handler for time values
+ * @title: GdaHanderTime
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_time_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_time_new (void);
diff --git a/libgda/handlers/gda-handler-type.h b/libgda/handlers/gda-handler-type.h
index d453584..aaa09bb 100644
--- a/libgda/handlers/gda-handler-type.h
+++ b/libgda/handlers/gda-handler-type.h
@@ -1,6 +1,5 @@
-/* gda-handler-type.h
- *
- * Copyright (C) 2005 - 2009 Vivien Malerba
+/*
+ * Copyright (C) 2005 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -47,11 +46,22 @@ struct _GdaHandlerTypeClass
{
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-handler-type
+ * @short_description: Default handler for GType values
+ * @title: GdaHanderType
+ * @stability: Stable
+ * @see_also: #GdaDataHandler interface
+ *
+ * You should normally not need to use this API, refer to the #GdaDataHandler
+ * interface documentation for more information.
+ */
GType gda_handler_type_get_type (void) G_GNUC_CONST;
GdaDataHandler *gda_handler_type_new (void);
diff --git a/libgda/libgda.h.in b/libgda/libgda.h.in
index 7fb4216..c90f9b0 100644
--- a/libgda/libgda.h.in
+++ b/libgda/libgda.h.in
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 1998 - 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 1998 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Michael Lausch <michael lausch at>
@@ -87,6 +87,14 @@
G_BEGIN_DECLS
+/**
+ * SECTION:libgda
+ * @short_description: Library initialization and information
+ * @title: Library initialization
+ * @stability: Stable
+ * @see_also:
+ */
+
void gda_init (void);
void gda_locale_changed (void);
gchar *gda_get_application_exec_path (const gchar *app_name);
diff --git a/libgda/providers-support/gda-data-select-priv.h b/libgda/providers-support/gda-data-select-priv.h
index a05501b..d22c695 100644
--- a/libgda/providers-support/gda-data-select-priv.h
+++ b/libgda/providers-support/gda-data-select-priv.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -31,6 +31,27 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gda-data-select-priv
+ * @short_description: Base class for all the data models returned by DBMS providers when a SELECT statement is executed
+ * @title: Subclassing GdaDataSelect
+ * @stability: Stable
+ * @see_also: #GdaDataModel and #GdaDataSelect
+ *
+ * All database providers should subclass this class when returning a data model after the execution of a SELECT
+ * statement. Specifically it has the following features:
+ * <itemizedlist>
+ * <listitem><para>Manages its list of <link linkend="GdaColumn">GdaColumn</link> using the list exported by the prepared statement object (<link linkend="GdaPStmt">GdaPStmt</link>)</para></listitem>
+ * <listitem><para>Allows random or cursor based access</para></listitem>
+ * <listitem><para>Allows for efficient memory usage allowing the subclass to finely tune its memory usage</para></listitem>
+ * <listitem><para>Provides a generic mechanism for writable data models</para></listitem>
+ * </itemizedlist>
+ *
+ * See the <link linkend="libgda-provider-recordset">Virtual methods for recordsets</link> section for more information
+ * about how to implement the virtual methods of the subclassed object.
+ *
+ * This section documents the methods available for the database provider's implementations.
+ */
GType gda_data_select_get_type (void) G_GNUC_CONST;
diff --git a/libgda/providers-support/gda-pstmt.h b/libgda/providers-support/gda-pstmt.h
index c0c91a3..6e87cbc 100644
--- a/libgda/providers-support/gda-pstmt.h
+++ b/libgda/providers-support/gda-pstmt.h
@@ -1,5 +1,5 @@
-/* GDA common library
- * Copyright (C) 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -59,6 +59,7 @@ struct _GdaPStmt {
struct _GdaPStmtClass {
GObjectClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -66,6 +67,34 @@ struct _GdaPStmtClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-pstmt
+ * @short_description: Base class for prepared statement's
+ * @title: GdaPstmt
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaPStmt represents the association between a #GdaStatement statement and a <emphasis>prepared statement</emphasis>
+ * which is database dependent and is an in-memory representation of a statement. Using prepared statement has the
+ * following advantages:
+ * <itemizedlist>
+ * <listitem><para>the parsing of the SQL has to be done only once, which improves performances if the statement
+ * has to be executed more than once</para></listitem>
+ * <listitem><para>if a statement has been prepared, then it means it is syntactically correct and has been
+ * <emphasis>understood</emphasis> by the database's API</para></listitem>
+ * <listitem><para>it is possible to use variables in prepared statement which eliminates the risk
+ * of SQL code injection</para></listitem>
+ * </itemizedlist>
+ *
+ * The #GdaPStmt is not intended to be instantiated, but subclassed by database provider's implementation.
+ * Once created, the database provider's implementation can decide to associate (for future lookup) to
+ * a #GdaStatement object in a connection using gda_connection_add_prepared_statement().
+ *
+ * The #GdaPStmt object can keep a reference to the #GdaStatement object (which can be set and get using
+ * the gda_pstmt_set_gda_statement() and gda_pstmt_get_gda_statement()), however that reference
+ * if a weak one (which means it will be lost if the #GdaStatement object is destroyed).
+ */
+
GType gda_pstmt_get_type (void) G_GNUC_CONST;
void gda_pstmt_set_gda_statement (GdaPStmt *pstmt, GdaStatement *stmt);
void gda_pstmt_copy_contents (GdaPStmt *src, GdaPStmt *dest);
diff --git a/libgda/sql-parser/gda-sql-parser.h b/libgda/sql-parser/gda-sql-parser.h
index a970177..380ad8b 100644
--- a/libgda/sql-parser/gda-sql-parser.h
+++ b/libgda/sql-parser/gda-sql-parser.h
@@ -1,6 +1,5 @@
-/* gda-sql-parser.h
- *
- * Copyright (C) 2007 Vivien Malerba
+/*
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -72,6 +71,7 @@ typedef struct _GdaSqlParserIface
GdaSqlParser *parser;
GdaSqlStatement *parsed_statement;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
@@ -95,6 +95,7 @@ struct _GdaSqlParserClass
void (*parser_parse) (void*, int, GValue *, GdaSqlParserIface *);
gint *parser_tokens_trans;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -102,6 +103,86 @@ struct _GdaSqlParserClass
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-sql-parser
+ * @short_description: SQL parser
+ * @title: GdaSqlParser
+ * @stability: Stable
+ * @see_also: #GdaSqlBuilder, #GdaSqlStatement and #GdaStatement
+ *
+ * The #GdaSqlParser is an object dedicated to creating #GdaStatement and #GdaBatch objects from SQL strings. The actual contents
+ * of the parsed statements is represented as #GdaSqlStatement structures (which can be obtained from any #GdaStatement through the
+ * "structure" property).
+ *
+ * #GdaSqlParser parsers can be created by calling gda_server_provider_create_parser() for a provider adapted SQL parser, or using
+ * gda_sql_parser_new() for a general purpose SQL parser.
+ *
+ * The #GdaSqlParser can either work in "parse" mode where it will try to parse the SQL string, or in "delimiter" mode where it will
+ * only attempt at delimiting SQL statements in a string which may contain several SQL statements (usually separated by a semi column).
+ * If operating in "parser" mode, and the parser can't correctly parse the string, then it will switch to the "delimiter" mode
+ * for the next statement in the string to parse (and create a GDA_SQL_STATEMENT_UNKNOWN statement).
+ *
+ * The #GdaSqlParser object parses and analyzes SQL statements and reports the following statement types:
+ * <itemizedlist>
+ * <listitem><para>SELECT (and COMPOUND select),
+ * INSERT, UPDATE and DELETE SQL statements should be completely parsed.
+ * </para></listitem>
+ * <listitem><para>Transaction related statements (corresponding to the BEGIN, COMMIT, ROLLBACK,
+ * SAVEPOINT, ROLLBACK SAVEPOINT and DELETE SAVEPOINT) are parsed and a minimalist structure is created to
+ * extract some information (that structure is not enough per-se to re-create the complete SQL statement).
+ * </para></listitem>
+ * <listitem><para>Any other type of SQL statement (CREATE TABLE, ...) creates a #GdaStatement of type
+ * GDA_SQL_STATEMENT_UNKNOWN, and it only able to locate place holders (variables) and end of statement
+ * marks.</para></listitem>
+ * </itemizedlist>
+ *
+ * NOTE: Any SQL of a type which should be parsed which but which creates a #GdaStatement of type GDA_SQL_STATEMENT_UNKNOWN
+ * (check with gda_statement_get_statement_type()) should be reported as a bug.
+ *
+ * The #GdaSqlParser object recognizes place holders (variables), which can later be queried and valued using
+ * gda_statement_get_parameters(). The following syntax are recognized (other syntaxes might be
+ * recognized for specific database providers if the #GdaSqlParser is created using gda_server_provider_create_parser()
+ * but for portability reasons it's better to avoid them):
+ * <itemizedlist>
+ * <listitem><para><programlisting>##NAME[::TYPE[::NULL]]]</programlisting>:
+ * for a variable named NAME with the optional type TYPE (which can be a GType
+ * name or a custom database type name), and with the optional "::NULL" to instruct that the variable can
+ * be NULL.
+ * </para></listitem>
+ * <listitem><para>
+ * <programlisting>## /* name:NAME [type:TYPE] [nullok:[TRUE|FALSE]] [descr:DESCR] */</programlisting>
+ * for a variable named NAME with the optional type TYPE (which can be a GType
+ * name or a custom database type name), with the optional "nullok" attribute and an optional
+ * description DESCR. Note that the NAME, TYPE and DESCR literals here must be quoted (simple or double quotes) if
+ * they include non alphanumeric characters, and that there must always be at least a space between the
+ * <![CDATA[##]]> and the opening and closing comments (C style).
+ * </para></listitem>
+ * </itemizedlist>
+ * Note that the type string must be a type recognized by the
+ * <link linkend="gda-g-type-from-string">gda_g_type_from_string()</link> function (all valid GType names
+ * plus a few synonyms). Examples of correct place holders definitions are:
+ * <programlisting>
+ *## /* name:"+0" type:gchararray */
+ *## /* name:'-5' type:string */
+ *## /*name:myvar type:gint descr:ToBeDefined nullok:FALSE*/
+ *## /*name:myvar type:int descr:"A long description"*/
+ *##+0::gchararray
+ *##-5::timestamp
+ *</programlisting>
+ *
+ * Also note that variables should not be used when an SQL identifier is expected. For example the following
+ * examples <emphasis>should be avoided</emphasis> because they may not work properly (depending on the database being used):
+ *<programlisting>
+ *SELECT * FROM ##tablename::string;
+ *DELETE FROM mytable WHERE ##tcol::string = 5;
+ *ALTER GROUP mygroup ADD USER ##name::gchararray;
+ *</programlisting>
+ *
+ * The #GdaSqlParser object internally uses a LEMON generated parser (the same as the one used by SQLite).
+ *
+ * The #GdaSqlParser object implements its own locking mechanism so it is thread-safe.
+ */
+
GType gda_sql_parser_get_type (void) G_GNUC_CONST;
GdaSqlParser *gda_sql_parser_new (void);
diff --git a/libgda/sql-parser/gda-sql-statement.h b/libgda/sql-parser/gda-sql-statement.h
index 17f13fa..8fc9b36 100644
--- a/libgda/sql-parser/gda-sql-statement.h
+++ b/libgda/sql-parser/gda-sql-statement.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2008 The GNOME Foundation.
+/*
+ * Copyright (C) 2008 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -25,6 +25,35 @@
G_BEGIN_DECLS
+/**
+ * SECTION:gda-sql-statement
+ * @short_description: SQL parser
+ * @title: GdaSqlParser
+ * @stability: Stable
+ * @see_also: The #GdaSqlBuilder object which features some easy to use API to build #GdaSqlStatement structures or #GdaStatement objects without having to worry about the details of #GdaSqlStatement's contents.
+ *
+ * Please note that it is not advised to build #GdaSqlStatement structures directly, but rather
+ * it is recommended to use the #GdaSqlBuilder object and its associated API.
+ *
+ * Every SQL statement can be decomposed in a #GdaSqlStatement structure. This is not a #GObject, but rather just a C structure
+ * which can be manipulated directly. The structure is a tree composed of several key structures which are show in the following diagram
+ * (even though it does not show, all structures "inherit" the #GdaSqlAnyPart structure which holds some basic information).
+ *<mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="parts.png" format="PNG"/>
+ * </imageobject>
+ * <caption>
+ * <para>
+ * Main parts of the #GdaSqlStatement structure.
+ * </para>
+ * </caption>
+ *</mediaobject>
+ *
+ * The samples/SqlParserConsole directory of &LIBGDA;'s sources contains a small utility
+ * to display statements' structures as a graph (using the GraphViz language). It has been used to
+ * provide the examples in this section of the documentation.
+ */
+
#include <sql-parser/gda-statement-struct-select.h>
#include <sql-parser/gda-statement-struct-insert.h>
#include <sql-parser/gda-statement-struct-update.h>
diff --git a/libgda/sql-parser/gda-statement-struct-compound.h b/libgda/sql-parser/gda-statement-struct-compound.h
index 3b522f0..89d5cb7 100644
--- a/libgda/sql-parser/gda-statement-struct-compound.h
+++ b/libgda/sql-parser/gda-statement-struct-compound.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -30,6 +30,15 @@ G_BEGIN_DECLS
/*
* Kinds
*/
+/**
+ * GdaSqlStatementCompoundType:
+ * @GDA_SQL_STATEMENT_COMPOUND_UNION:
+ * @GDA_SQL_STATEMENT_COMPOUND_UNION_ALL:
+ * @GDA_SQL_STATEMENT_COMPOUND_INTERSECT:
+ * @GDA_SQL_STATEMENT_COMPOUND_INTERSECT_ALL:
+ * @GDA_SQL_STATEMENT_COMPOUND_EXCEPT:
+ * @GDA_SQL_STATEMENT_COMPOUND_EXCEPT_ALL:
+ */
typedef enum {
GDA_SQL_STATEMENT_COMPOUND_UNION,
GDA_SQL_STATEMENT_COMPOUND_UNION_ALL,
@@ -42,11 +51,18 @@ typedef enum {
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementCompound:
+ * @any:
+ * @compound_type:
+ * @stmt_list:
+ */
struct _GdaSqlStatementCompound {
GdaSqlAnyPart any;
GdaSqlStatementCompoundType compound_type;
GSList *stmt_list; /* list of SELECT or COMPOUND statements */
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-decl.h b/libgda/sql-parser/gda-statement-struct-decl.h
index 2863bba..098949a 100644
--- a/libgda/sql-parser/gda-statement-struct-decl.h
+++ b/libgda/sql-parser/gda-statement-struct-decl.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2008 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -56,6 +56,24 @@ typedef struct _GdaSqlStatementCompound GdaSqlStatementCompound;
/*
* Statement type
*/
+/**
+ * GdaSqlStatementType:
+ * @GDA_SQL_STATEMENT_SELECT: a SELECT statement
+ * @GDA_SQL_STATEMENT_INSERT: an INSERT statement
+ * @GDA_SQL_STATEMENT_UPDATE: an UPDATE statement
+ * @GDA_SQL_STATEMENT_DELETE: a DELETE statement
+ * @GDA_SQL_STATEMENT_COMPOUND: a compound statement: multiple SELECT statements grouped together using an operator
+ * @GDA_SQL_STATEMENT_BEGIN: start of transaction statement
+ * @GDA_SQL_STATEMENT_ROLLBACK: transaction abort statement
+ * @GDA_SQL_STATEMENT_COMMIT: transaction commit statement
+ * @GDA_SQL_STATEMENT_SAVEPOINT: new savepoint definition statement
+ * @GDA_SQL_STATEMENT_ROLLBACK_SAVEPOINT: return to savepoint statement
+ * @GDA_SQL_STATEMENT_DELETE_SAVEPOINT: savepoint deletion statement
+ * @GDA_SQL_STATEMENT_UNKNOWN: unknown statement, only identifies variables
+ * @GDA_SQL_STATEMENT_NONE: not used
+ *
+ * Known types of statements
+ */
typedef enum {
GDA_SQL_STATEMENT_SELECT,
GDA_SQL_STATEMENT_INSERT,
@@ -79,6 +97,34 @@ typedef enum {
/*
* Structures identification
*/
+/**
+ * GdaSqlAnyPartType:
+ * @GDA_SQL_ANY_STMT_SELECT: structure is a #GdaSqlStatementSelect
+ * @GDA_SQL_ANY_STMT_INSERT: structure is a #GdaSqlStatementInsert
+ * @GDA_SQL_ANY_STMT_UPDATE: structure is a #GdaSqlStatementUpdate
+ * @GDA_SQL_ANY_STMT_DELETE: structure is a #GdaSqlStatementDelete
+ * @GDA_SQL_ANY_STMT_COMPOUND: structure is a #GdaSqlStatementCompound
+ * @GDA_SQL_ANY_STMT_BEGIN: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_ROLLBACK: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_COMMIT: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_SAVEPOINT: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_ROLLBACK_SAVEPOINT: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_DELETE_SAVEPOINT: structure is a #GdaSqlStatementTransaction
+ * @GDA_SQL_ANY_STMT_UNKNOWN: structure is a #GdaSqlStatementUnknown
+ * @GDA_SQL_ANY_EXPR: structure is a #GdaSqlExpr
+ * @GDA_SQL_ANY_SQL_FIELD: structure is a #GdaSqlField
+ * @GDA_SQL_ANY_SQL_TABLE: structure is a #GdaSqlTable
+ * @GDA_SQL_ANY_SQL_FUNCTION: structure is a #GdaSqlFunction
+ * @GDA_SQL_ANY_SQL_OPERATION: structure is a #GdaSqlOperation
+ * @GDA_SQL_ANY_SQL_CASE: structure is a #GdaSqlCase
+ * @GDA_SQL_ANY_SQL_SELECT_FIELD: structure is a #GdaSqlSelectField
+ * @GDA_SQL_ANY_SQL_SELECT_TARGET: structure is a #GdaSqlSelectTarget
+ * @GDA_SQL_ANY_SQL_SELECT_JOIN: structure is a #GdaSqlSelectJoin
+ * @GDA_SQL_ANY_SQL_SELECT_FROM: structure is a #GdaSqlSelectFrom
+ * @GDA_SQL_ANY_SQL_SELECT_ORDER: structure is a #GdaSqlSelectOrder
+ *
+ * Type of part.
+ */
typedef enum {
/* complete statements */
GDA_SQL_ANY_STMT_SELECT = GDA_SQL_STATEMENT_SELECT,
@@ -108,6 +154,15 @@ typedef enum {
GDA_SQL_ANY_SQL_SELECT_ORDER
} GdaSqlAnyPartType;
+
+/**
+ * GdaSqlAnyPart:
+ * @type: type of structure, as a #GdaSqlAnyPartType enum.
+ * @parent: pointer to the parent #GdaSqlAnyPart structure
+ *
+ * Base structure of which all structures (except #GdaSqlStatement) "inherit". It identifies, for each structure,
+ * its type and its parent in the structure hierarchy.
+ */
struct _GdaSqlAnyPart {
GdaSqlAnyPartType type;
GdaSqlAnyPart *parent;
@@ -122,6 +177,15 @@ struct _GdaSqlAnyPart {
*/
/* returns FALSE if a recursive walking should be stopped (mandatory is @error is set) */
+/**
+ * GdaSqlForeachFunc:
+ * @Param1: the current #GdaSqlAnyPart node
+ * @Param2: user data passed to gda_sql_any_part_foreach().
+ * @Param3: pointer to a place to store errors
+ * @Returns: FALSE if the gda_sql_any_part_foreach() should stop at this point and fail
+ *
+ * Specifies the type of functions passed to gda_sql_any_part_foreach().
+ */
typedef gboolean (*GdaSqlForeachFunc) (GdaSqlAnyPart *, gpointer, GError **);
gboolean gda_sql_any_part_foreach (GdaSqlAnyPart *node, GdaSqlForeachFunc func, gpointer data, GError **error);
@@ -146,6 +210,7 @@ typedef struct {
GdaSqlForeachFunc check_structure_func;
GdaSqlForeachFunc check_validity_func;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
@@ -156,12 +221,12 @@ typedef struct {
/*
* Validation against a dictionary
*/
-
typedef struct {
GdaConnection *cnc;
GdaMetaStore *store;
GdaMetaStruct *mstruct;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-delete.h b/libgda/sql-parser/gda-statement-struct-delete.h
index bb3ee42..acc3e0b 100644
--- a/libgda/sql-parser/gda-statement-struct-delete.h
+++ b/libgda/sql-parser/gda-statement-struct-delete.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -31,11 +31,18 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementDelete:
+ * @any:
+ * @table:
+ * @cond:
+ */
struct _GdaSqlStatementDelete {
GdaSqlAnyPart any;
GdaSqlTable *table;
GdaSqlExpr *cond;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-insert.h b/libgda/sql-parser/gda-statement-struct-insert.h
index 8c1de64..a7941da 100644
--- a/libgda/sql-parser/gda-statement-struct-insert.h
+++ b/libgda/sql-parser/gda-statement-struct-insert.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -31,6 +31,41 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementInsert:
+ * @any: inheritance structure
+ * @on_conflict: conflict resolution clause if there is one (such as "OR REPLACE")
+ * @table: name of the table to which data is inserted
+ * @fields_list: list of #GdaSqlField fields which are valued for insertion
+ * @values_list: list of list of #GdaSqlExpr expressions (this is a list of list, not a simple list)
+ * @select: a #GdaSqlStatementSelect or #GdaSqlStatementCompound structure representing the values to insert
+ *
+ * The statement is an INSERT statement, any kind of INSERT statement can be represented using this structure
+ * (if this is not the case
+ * then report a bug).
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="stmt-insert1.png" format="PNG"/>
+ * </imageobject>
+ * <caption>
+ * <para>
+ * Example of a #GdaSqlStatement having a #GdaSqlStatementInsert as its contents with 2 lists of values
+ * to insert.
+ * </para>
+ * </caption>
+ * </mediaobject>
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="stmt-insert2.png" format="PNG"/>
+ * </imageobject>
+ * <caption>
+ * <para>
+ * Another example of a #GdaSqlStatement having a #GdaSqlStatementInsert as its contents, using a SELECT
+ * to express the values to insert.
+ * </para>
+ * </caption>
+ * </mediaobject>
+ */
struct _GdaSqlStatementInsert {
GdaSqlAnyPart any;
gchar *on_conflict; /* conflict resolution clause */
@@ -39,6 +74,7 @@ struct _GdaSqlStatementInsert {
GSList *values_list; /* list of list of GdaSqlExpr */
GdaSqlAnyPart *select; /* SELECT OR COMPOUND statements: GdaSqlStatementSelect or GdaSqlStatementCompound */
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-parts.h b/libgda/sql-parser/gda-statement-struct-parts.h
index 7770d82..8a03be6 100644
--- a/libgda/sql-parser/gda-statement-struct-parts.h
+++ b/libgda/sql-parser/gda-statement-struct-parts.h
@@ -108,6 +108,14 @@ void gda_sql_expr_take_select (GdaSqlExpr *expr, GdaSqlStatement
/*
* Any Table's field
*/
+/**
+ * GdaSqlField:
+ * any:
+ * @field_name:
+ * @validity_meta_table_column:
+ *
+ * This structure represents the name of a table's field.
+ */
struct _GdaSqlField {
GdaSqlAnyPart any;
gchar *field_name;
@@ -132,6 +140,14 @@ void gda_sql_field_take_name (GdaSqlField *field, GValue *value
/*
* Any table
*/
+/**
+ * GdaSqlTable:
+ * @any:
+ * @table_name:
+ * @validity_meta_object:
+ *
+ * This structure represents the name of a table.
+ */
struct _GdaSqlTable
{
GdaSqlAnyPart any;
@@ -157,6 +173,14 @@ void gda_sql_table_take_name (GdaSqlTable *table, GValue *value
/*
* A function with any number of arguments
*/
+/**
+ * GdaSqlFunction:
+ * @any: inheritance structure
+ * @function_name: name of the function , in the form [[catalog.]schema.]function_name
+ * @args_list: list of #GdaSqlExpr expressions, one for each argument
+ *
+ * This structure represents a function or an aggregate with zero or more arguments.
+ */
struct _GdaSqlFunction {
GdaSqlAnyPart any;
gchar *function_name;
@@ -180,6 +204,39 @@ void gda_sql_function_take_args_list (GdaSqlFunction *function, GSLi
/*
* An operation on one or more expressions
*/
+/**
+ * GdaSqlOperatorType:
+ * @GDA_SQL_OPERATOR_TYPE_AND:
+ * @GDA_SQL_OPERATOR_TYPE_OR:
+ * @GDA_SQL_OPERATOR_TYPE_EQ:
+ * @GDA_SQL_OPERATOR_TYPE_IS:
+ * @GDA_SQL_OPERATOR_TYPE_LIKE:
+ * @GDA_SQL_OPERATOR_TYPE_BETWEEN:
+ * @GDA_SQL_OPERATOR_TYPE_GT:
+ * @GDA_SQL_OPERATOR_TYPE_LT:
+ * @GDA_SQL_OPERATOR_TYPE_GEQ:
+ * @GDA_SQL_OPERATOR_TYPE_LEQ:
+ * @GDA_SQL_OPERATOR_TYPE_DIFF:
+ * @GDA_SQL_OPERATOR_TYPE_REGEXP:
+ * @GDA_SQL_OPERATOR_TYPE_REGEXP_CI:
+ * @GDA_SQL_OPERATOR_TYPE_NOT_REGEXP:
+ * @GDA_SQL_OPERATOR_TYPE_NOT_REGEXP_CI:
+ * @GDA_SQL_OPERATOR_TYPE_SIMILAR:
+ * @GDA_SQL_OPERATOR_TYPE_ISNULL:
+ * @GDA_SQL_OPERATOR_TYPE_ISNOTNULL:
+ * @GDA_SQL_OPERATOR_TYPE_NOT:
+ * @GDA_SQL_OPERATOR_TYPE_IN:
+ * @GDA_SQL_OPERATOR_TYPE_NOTIN:
+ * @GDA_SQL_OPERATOR_TYPE_CONCAT:
+ * @GDA_SQL_OPERATOR_TYPE_PLUS:
+ * @GDA_SQL_OPERATOR_TYPE_MINUS:
+ * @GDA_SQL_OPERATOR_TYPE_STAR:
+ * @GDA_SQL_OPERATOR_TYPE_DIV:
+ * @GDA_SQL_OPERATOR_TYPE_REM:
+ * @GDA_SQL_OPERATOR_TYPE_BITAND:
+ * @GDA_SQL_OPERATOR_TYPE_BITOR:
+ * @GDA_SQL_OPERATOR_TYPE_BITNOT:
+ */
typedef enum {
GDA_SQL_OPERATOR_TYPE_AND,
GDA_SQL_OPERATOR_TYPE_OR,
@@ -215,6 +272,14 @@ typedef enum {
GDA_SQL_OPERATOR_TYPE_BITNOT
} GdaSqlOperatorType;
+/**
+ * GdaSqlOperation:
+ * @any: inheritance structure
+ * @operator_type:
+ * @operands: list of #GdaSqlExpr operands
+ *
+ * This structure represents an operation between one or more operands.
+ */
struct _GdaSqlOperation {
GdaSqlAnyPart any;
GdaSqlOperatorType operator_type;
@@ -236,6 +301,16 @@ GdaSqlOperatorType gda_sql_operation_operator_from_string (const gchar *op);
/*
* A CASE expression
*/
+/**
+ * GdaSqlCase:
+ * @any: inheritance structure
+ * @base_expr: expression to test
+ * @when_expr_list: list of #GdaSqlExpr, one for each WHEN clause
+ * @then_expr_list: list of #GdaSqlExpr, one for each THEN clause
+ * @else_expr: default expression for the CASE
+ *
+ * This structure represents a CASE WHEN... construct
+ */
struct _GdaSqlCase
{
GdaSqlAnyPart any;
@@ -258,6 +333,21 @@ gchar *gda_sql_case_serialize (GdaSqlCase *sc);
/*
* Any expression in a SELECT ... before the FROM clause
*/
+/**
+ * GdaSqlSelectField:
+ * @any: inheritance structure
+ * @expr: expression
+ * @field_name: field name part of @expr if @expr represents a field
+ * @table_name: table name part of @expr if @expr represents a field
+ * @as: alias
+ * @validity_meta_object:
+ * @validity_meta_table_column:
+ *
+ * This structure represents a selected item in a SELECT statement (when executed, the returned data set
+ * will have one column per selected item). Note that the @table_name and
+ * @field_name field parts <emphasis>will be</emphasis> overwritten by &LIBGDA;,
+ * set the value of @expr->value instead.
+ */
struct _GdaSqlSelectField
{
GdaSqlAnyPart any;
@@ -289,6 +379,19 @@ void gda_sql_select_field_take_alias (GdaSqlSelectField *field
/*
* Any TARGET ... in a SELECT statement
*/
+/**
+ * GdaSqlSelectTarget:
+ * @any: inheritance structure
+ * @expr: expression
+ * @table_name: table name part of @expr if @expr represents a table
+ * @as: alias
+ * @validity_meta_object:
+ *
+ * This structure represents a target used to fetch data from in a SELECT statement; it can represent a table or
+ * a sub select. Note that the @table_name
+ * part <emphasis>will be</emphasis> overwritten by &LIBGDA;,
+ * set the value of @expr->value instead.
+ */
struct _GdaSqlSelectTarget
{
GdaSqlAnyPart any;
@@ -318,6 +421,15 @@ void gda_sql_select_target_take_alias (GdaSqlSelectTarget *target
/*
* Any JOIN ... in a SELECT statement
*/
+/**
+ * GdaSqlSelectJoinType:
+ * @GDA_SQL_SELECT_JOIN_CROSS:
+ * @GDA_SQL_SELECT_JOIN_NATURAL:
+ * @GDA_SQL_SELECT_JOIN_INNER:
+ * @GDA_SQL_SELECT_JOIN_LEFT:
+ * @GDA_SQL_SELECT_JOIN_RIGHT:
+ * @GDA_SQL_SELECT_JOIN_FULL:
+ */
typedef enum {
GDA_SQL_SELECT_JOIN_CROSS,
GDA_SQL_SELECT_JOIN_NATURAL,
@@ -326,6 +438,17 @@ typedef enum {
GDA_SQL_SELECT_JOIN_RIGHT,
GDA_SQL_SELECT_JOIN_FULL
} GdaSqlSelectJoinType;
+
+/**
+ * GdaSqlSelectJoin:
+ * @any: inheritance structure
+ * @type: type of join
+ * @position: represents a join between a target at (pos < @position) and the one at @position
+ * @expr: joining expression, or %NULL
+ * @use: list of #GdaSqlField pointers to use when joining, or %NULL
+ *
+ * This structure represents a join between two targets in a SELECT statement.
+ */
struct _GdaSqlSelectJoin
{
GdaSqlAnyPart any;
@@ -351,6 +474,14 @@ const gchar *gda_sql_select_join_type_to_string (GdaSqlSelectJoinType type
/*
* Any FROM ... in a SELECT statement
*/
+/**
+ * GdaSqlSelectFrom:
+ * @any: inheritance structure
+ * @targets: list of #GdaSqlSelectTarget
+ * @joins: list of #GdaSqlSelectJoin
+ *
+ * This structure represents the FROM clause of a SELECT statement, it lists targets and joins
+ */
struct _GdaSqlSelectFrom
{
GdaSqlAnyPart any;
@@ -374,6 +505,15 @@ void gda_sql_select_from_take_new_join (GdaSqlSelectFrom *from, G
/*
* Any expression in a SELECT ... after the ORDER BY
*/
+/**
+ * GdaSqlSelectOrder:
+ * @any: inheritance structure
+ * @expr: expression to order on
+ * @asc: TRUE is ordering is ascending
+ * @collation_name: name of the collation to use for ordering
+ *
+ * This structure represents the ordering of a SELECT statement.
+ */
struct _GdaSqlSelectOrder
{
GdaSqlAnyPart any;
diff --git a/libgda/sql-parser/gda-statement-struct-select.h b/libgda/sql-parser/gda-statement-struct-select.h
index 61af908..9c765d4 100644
--- a/libgda/sql-parser/gda-statement-struct-select.h
+++ b/libgda/sql-parser/gda-statement-struct-select.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -30,6 +30,20 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementSelect:
+ * @any:
+ * @distinct:
+ * @distinct_expr:
+ * @expr_list:
+ * @from:
+ * @where_cond:
+ * @group_by:
+ * @having_cond:
+ * @order_by:
+ * @limit_count:
+ * @limit_offset:
+ */
struct _GdaSqlStatementSelect {
GdaSqlAnyPart any;
gboolean distinct;
@@ -46,6 +60,7 @@ struct _GdaSqlStatementSelect {
GdaSqlExpr *limit_count;
GdaSqlExpr *limit_offset;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-trans.h b/libgda/sql-parser/gda-statement-struct-trans.h
index e0c5105..73e8e31 100644
--- a/libgda/sql-parser/gda-statement-struct-trans.h
+++ b/libgda/sql-parser/gda-statement-struct-trans.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -31,12 +31,25 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementTransaction:
+ * @any: inheritance structure
+ * @isolation_level: isolation level as a #GdaTransactionIsolation
+ * @trans_mode: transaction mode (DEFERRED, IMMEDIATE, EXCLUSIVE, READ_WRITE, READ_ONLY)
+ * @trans_name: transaction name
+ *
+ * The statement is a transaction management related statement (BEGIN, ROLLBACK, etc). The #GdaSqlStatementTransaction structure
+ * does not hold enough information to reconstruct the complete SQL statement (some information may be missing) - the aim of this
+ * structure is to identify a minimum set of information in the transaction statement. Note that the complete SQL which created the
+ * statement should be available in the #GdaSqlStatement structure which encapsulates this structure.
+ */
struct _GdaSqlStatementTransaction {
GdaSqlAnyPart any;
GdaTransactionIsolation isolation_level;
gchar *trans_mode; /* DEFERRED, IMMEDIATE, EXCLUSIVE, READ_WRITE, READ_ONLY */
gchar *trans_name;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-unknown.h b/libgda/sql-parser/gda-statement-struct-unknown.h
index 4692b54..9033ba4 100644
--- a/libgda/sql-parser/gda-statement-struct-unknown.h
+++ b/libgda/sql-parser/gda-statement-struct-unknown.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -30,10 +30,18 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementUnknown:
+ * @any:
+ * @expressions: a list of #GdaSqlExpr pointers
+ *
+ * Represents any statement which type is not identified (any DDL statement or database specific dialect)
+ */
struct _GdaSqlStatementUnknown {
GdaSqlAnyPart any;
- GSList *expressions; /* list of GdaSqlExpr pointers */
+ GSList *expressions;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-update.h b/libgda/sql-parser/gda-statement-struct-update.h
index 584d786..d46800e 100644
--- a/libgda/sql-parser/gda-statement-struct-update.h
+++ b/libgda/sql-parser/gda-statement-struct-update.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -31,6 +31,15 @@ G_BEGIN_DECLS
/*
* Structure definition
*/
+/**
+ * GdaSqlStatementUpdate:
+ * @any:
+ * @on_conflict:
+ * @table:
+ * @fields_list:
+ * @expr_list:
+ * @cond:
+ */
struct _GdaSqlStatementUpdate {
GdaSqlAnyPart any;
gchar *on_conflict; /* conflict resolution clause */
@@ -39,6 +48,7 @@ struct _GdaSqlStatementUpdate {
GSList *expr_list; /* list of GdaSqlExpr pointers */
GdaSqlExpr *cond;
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sql-parser/gda-statement-struct-util.c b/libgda/sql-parser/gda-statement-struct-util.c
index 704e760..6bb8554 100644
--- a/libgda/sql-parser/gda-statement-struct-util.c
+++ b/libgda/sql-parser/gda-statement-struct-util.c
@@ -299,8 +299,10 @@ _string_is_identifier (const gchar *str)
* @str: a quoted string
*
* Prepares @str to be compared:
- * - if surrounded by double quotes or single quotes, then just remove the quotes
- * - otherwise convert to lower case
+ * <itemizedlist>
+ * <listitem><para>if surrounded by double quotes or single quotes, then just remove the quotes</para></listitem>
+ * <listitem><para>otherwise convert to lower case</para></listitem>
+ * </itemizedlist>
*
* The quoted string:
* <itemizedlist>
diff --git a/libgda/sql-parser/gda-statement-struct.h b/libgda/sql-parser/gda-statement-struct.h
index 4a45003..7a19ff9 100644
--- a/libgda/sql-parser/gda-statement-struct.h
+++ b/libgda/sql-parser/gda-statement-struct.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2009 Vivien Malerba
+ * Copyright (C) 2007 - 2011 Vivien Malerba
*
* This Library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public License as
@@ -27,12 +27,22 @@
G_BEGIN_DECLS
+/**
+ * GdaSqlStatement:
+ * @sql:
+ * @stmt_type: type of statement
+ * @contents: contents, cast it depending on @stmt_type (for example to a #GdaSqlStatementSelect).
+ * @validity_meta_struct:
+ *
+ * This structure is the top level structure encapsulating several type of statements.
+ */
struct _GdaSqlStatement {
gchar *sql;
GdaSqlStatementType stmt_type;
gpointer contents; /* depends on stmt_type */
GdaMetaStruct *validity_meta_struct; /* set when gda_sql_statement_check_validity() was last called */
+ /*< private >*/
/* Padding for future expansion */
gpointer _gda_reserved1;
gpointer _gda_reserved2;
diff --git a/libgda/sqlite/virtual/gda-vconnection-data-model.h b/libgda/sqlite/virtual/gda-vconnection-data-model.h
index 0eb7727..90f8153 100644
--- a/libgda/sqlite/virtual/gda-vconnection-data-model.h
+++ b/libgda/sqlite/virtual/gda-vconnection-data-model.h
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2007 - 2010 The GNOME Foundation.
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -40,11 +40,33 @@ typedef struct _GdaVconnectionDataModelPrivate GdaVconnectionDataModelPrivate;
typedef struct _GdaVconnectionDataModelSpec GdaVconnectionDataModelSpec;
typedef struct _GdaVconnectionDataModelFilter GdaVconnectionDataModelFilter;
+/**
+ * GdaVconnectionDataModelCreateColumnsFunc:
+ * @Param1:
+ * @Param2:
+ * @Returns:
+ */
typedef GList *(*GdaVconnectionDataModelCreateColumnsFunc) (GdaVconnectionDataModelSpec *, GError **);
+
+/**
+ * GdaVconnectionDataModelCreateModelFunc:
+ * @Param1:
+ * @Returns:
+ */
typedef GdaDataModel *(*GdaVconnectionDataModelCreateModelFunc) (GdaVconnectionDataModelSpec *);
+
+/**
+ * GdaVconnectionDataModelFunc:
+ * @Param1:
+ * @Param2:
+ * @Param3:
+ */
+
typedef void (*GdaVconnectionDataModelFunc) (GdaDataModel *, const gchar *, gpointer );
-/*
+/**
+ * GdaVconnectionDataModelFilter:
+ *
* Enabling pre-filtering when creating a data model to be used as a table,
* (structure closely mapped with SQLite's sqlite3_index_info type), to enable
* the data model to perform some filter tasks itself.
@@ -82,10 +104,29 @@ struct _GdaVconnectionDataModelFilter {
double estimatedCost; /* Estimated cost of using this index */
};
+/**
+ * GdaVconnectionDataModelParseFilterFunc:
+ * @Param1:
+ * @Param2:
+ */
typedef void (*GdaVconnectionDataModelParseFilterFunc) (GdaVconnectionDataModelSpec *, GdaVconnectionDataModelFilter *);
+
+/**
+ * GdaVconnectionDataModelCreateFModelFunc:
+ * @Param1:
+ * @Returns:
+ */
typedef GdaDataModel *(*GdaVconnectionDataModelCreateFModelFunc) (GdaVconnectionDataModelSpec *,
int, const char *, int, GValue **);
-
+/**
+ * GdaVconnectionDataModelSpec:
+ * @data_model:
+ * @create_columns_func:
+ * @create_model_func:
+ * @create_filter_func:
+ * @create_filtered_model_func:
+ *
+ */
struct _GdaVconnectionDataModelSpec {
GdaDataModel *data_model;
GdaVconnectionDataModelCreateColumnsFunc create_columns_func;
@@ -104,11 +145,23 @@ struct _GdaVconnectionDataModel {
struct _GdaVconnectionDataModelClass {
GdaVirtualConnectionClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-vconnection-data-model
+ * @short_description: Virtual connection based on a list of GdaDataModel
+ * @title: GdaVconnectionDataModel
+ * @stability: Stable
+ * @see_also: The #GdaVproviderDataModel provider to use to create such connection objects.
+ *
+ * The #GdaVconnectionDataModel is a virtual connection in which #GdaDataModel data models can be added
+ * or removed, each representing a table in the connection.
+ */
+
GType gda_vconnection_data_model_get_type (void) G_GNUC_CONST;
gboolean gda_vconnection_data_model_add (GdaVconnectionDataModel *cnc, GdaVconnectionDataModelSpec *spec,
diff --git a/libgda/sqlite/virtual/gda-vconnection-hub.h b/libgda/sqlite/virtual/gda-vconnection-hub.h
index cf6cb87..e3da934 100644
--- a/libgda/sqlite/virtual/gda-vconnection-hub.h
+++ b/libgda/sqlite/virtual/gda-vconnection-hub.h
@@ -1,5 +1,5 @@
-/* GDA
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -47,6 +47,7 @@ struct _GdaVconnectionHub {
struct _GdaVconnectionHubClass {
GdaVconnectionDataModelClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -54,6 +55,24 @@ struct _GdaVconnectionHubClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-vconnection-hub
+ * @short_description: Virtual connection which bind together connections
+ * @title: GdaVconnectionHub
+ * @stability: Stable
+ * @see_also:
+ *
+ * The #GdaVconnectionHub object "binds" together the tables from other (opened) connections to make it possible to run
+ * SQL queries on data from several connections at once.
+ *
+ * A #GdaVconnectionHub connection can bind several other connections, each separated in its own namespace (which is specified
+ * when adding a connection using gda_vconnection_hub_add()).
+ *
+ * For example if a connection A has two tables 'table_1' and 'table_2', then after gda_vconnection_hub_add() has been called
+ * with A as connection argument and with a "c1" namespace, then in the corresponding #GdaVconnectionHub connection, table
+ * 'table_1' must be referred to as 'c1.table_1' and 'table_2' must be referred to as 'c1.table_2'.
+ */
+
GType gda_vconnection_hub_get_type (void) G_GNUC_CONST;
gboolean gda_vconnection_hub_add (GdaVconnectionHub *hub,
diff --git a/libgda/sqlite/virtual/gda-virtual-connection.h b/libgda/sqlite/virtual/gda-virtual-connection.h
index d0d9976..7f80f43 100644
--- a/libgda/sqlite/virtual/gda-virtual-connection.h
+++ b/libgda/sqlite/virtual/gda-virtual-connection.h
@@ -1,5 +1,5 @@
-/* GDA virtual connection
- * Copyright (C) 2007 - 2010 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -54,6 +54,16 @@ struct _GdaVirtualConnectionClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-virtual-connection
+ * @short_description: Base class for all virtual connection objects
+ * @title: GdaVirtualConnection
+ * @stability: Stable
+ * @see_also:
+ *
+ * This is a base virtual class for all virtual connection implementations.
+ */
+
GType gda_virtual_connection_get_type (void) G_GNUC_CONST;
GdaConnection *gda_virtual_connection_open (GdaVirtualProvider *virtual_provider, GError **error);
GdaConnection *gda_virtual_connection_open_extended (GdaVirtualProvider *virtual_provider,
diff --git a/libgda/sqlite/virtual/gda-virtual-provider.h b/libgda/sqlite/virtual/gda-virtual-provider.h
index 2f4ac31..1e21d04 100644
--- a/libgda/sqlite/virtual/gda-virtual-provider.h
+++ b/libgda/sqlite/virtual/gda-virtual-provider.h
@@ -1,5 +1,5 @@
-/* GDA virtual provider (based on SQLite)
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -47,11 +47,22 @@ struct _GdaVirtualProvider {
struct _GdaVirtualProviderClass {
GdaSqliteProviderClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
};
+/**
+ * SECTION:gda-virtual-provider
+ * @short_description: Base class for all virtual provider objects
+ * @title: GdaVirtualProvider
+ * @stability: Stable
+ * @see_also: #GdaVirtualConnection
+ *
+ * This is a base virtual class for all virtual providers implementations.
+ */
+
GType gda_virtual_provider_get_type (void) G_GNUC_CONST;
G_END_DECLS
diff --git a/libgda/sqlite/virtual/gda-vprovider-data-model.h b/libgda/sqlite/virtual/gda-vprovider-data-model.h
index cc06031..3665511 100644
--- a/libgda/sqlite/virtual/gda-vprovider-data-model.h
+++ b/libgda/sqlite/virtual/gda-vprovider-data-model.h
@@ -1,5 +1,5 @@
-/* GDA SQLite vprovider for GdaDataModel
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaVproviderDataModel {
struct _GdaVproviderDataModelClass {
GdaVirtualProviderClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,6 +53,19 @@ struct _GdaVproviderDataModelClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-vprovider-data-model
+ * @short_description: Virtual provider for connections based on a list of GdaDataModel
+ * @title: GdaVproviderDataModel
+ * @stability: Stable
+ * @see_also: See also the <link linkend="VirtualIntro">introduction to virtual connections</link>
+ *
+ * This provider is used to create virtual connections in which each #GdaDataModel data model can be
+ * added as a table in the connection. Using gda_virtual_connection_open() with this provider as argument
+ * will generate a #GdaVconnectionDataModel connection object, from which data models can be added.
+ */
+
+
GType gda_vprovider_data_model_get_type (void) G_GNUC_CONST;
GdaVirtualProvider *gda_vprovider_data_model_new (void);
diff --git a/libgda/sqlite/virtual/gda-vprovider-hub.h b/libgda/sqlite/virtual/gda-vprovider-hub.h
index bfa04f8..13d949e 100644
--- a/libgda/sqlite/virtual/gda-vprovider-hub.h
+++ b/libgda/sqlite/virtual/gda-vprovider-hub.h
@@ -1,5 +1,5 @@
-/* GDA SQLite vprovider for Hub of connections
- * Copyright (C) 2007 - 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2007 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -45,6 +45,7 @@ struct _GdaVproviderHub {
struct _GdaVproviderHubClass {
GdaVproviderDataModelClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_gda_reserved1) (void);
void (*_gda_reserved2) (void);
@@ -52,6 +53,22 @@ struct _GdaVproviderHubClass {
void (*_gda_reserved4) (void);
};
+/**
+ * SECTION:gda-vprovider-hub
+ * @short_description: Virtual provider for connections based on other connection
+ * @title: GdaVproviderHub
+ * @stability: Stable
+ * @see_also: See also the <link linkend="VirtualIntro">introduction to virtual connections</link>
+ *
+ * This provider is used to create virtual connections which "incorporate" tables from other connections. This is typically
+ * used when one need to compare or migrate data from one database to the other by creating two connections for each database,
+ * and "binding" them into a third virtual connection using this provider.
+ *
+ * Using gda_virtual_connection_open() with this provider as argument
+ * will generate a #GdaVconnectionHub connection object, from which connections can be added.
+ */
+
+
GType gda_vprovider_hub_get_type (void) G_GNUC_CONST;
GdaVirtualProvider *gda_vprovider_hub_new (void);
diff --git a/libgda/thread-wrapper/gda-thread-wrapper.h b/libgda/thread-wrapper/gda-thread-wrapper.h
index 7b98312..1c02026 100644
--- a/libgda/thread-wrapper/gda-thread-wrapper.h
+++ b/libgda/thread-wrapper/gda-thread-wrapper.h
@@ -1,5 +1,5 @@
-/* GDA library
- * Copyright (C) 2009 The GNOME Foundation.
+/*
+ * Copyright (C) 2009 - 2011 The GNOME Foundation.
*
* AUTHORS:
* Vivien Malerba <malerba gnome-db org>
@@ -62,12 +62,88 @@ struct _GdaThreadWrapperClass {
void (*_gda_reserved4) (void);
};
+/**
+ * GdaThreadWrapperFunc:
+ * @arg: pointer to the data (which is the @arg argument passed to gda_thread_wrapper_execute_void())
+ * @error: a place to store errors
+ * @Returns: a pointer to some data which will be returned by gda_thread_wrapper_fetch_result()
+ *
+ * Specifies the type of function to be passed to gda_thread_wrapper_execute().
+ */
typedef gpointer (*GdaThreadWrapperFunc) (gpointer arg, GError **error);
+
+/**
+ * GdaThreadWrapperVoidFunc:
+ * @arg: a pointer to the data (which is the @arg argument passed to gda_thread_wrapper_execute_void())
+ * @error: a place to store errors
+ *
+ * Specifies the type of function to be passed to gda_thread_wrapper_execute_void().
+ */
typedef void (*GdaThreadWrapperVoidFunc) (gpointer arg, GError **error);
+
+/**
+ * GdaThreadWrapperCallback:
+ * @wrapper: the #GdaThreadWrapper
+ * @instance: a pointer to the instance which emitted the signal
+ * @signame: the name of the signal being emitted
+ * @n_param_values: number of GValue in @param_values
+ * @param_values: array of @n_param_values GValue
+ * @gda_reserved: reserved
+ * @data: a pointer to the data (which is the @data argument passed to gda_thread_wrapper_connect_raw())
+ *
+ * Specifies the type of function to be passed to gda_thread_wrapper_connect_raw()
+ */
typedef void (*GdaThreadWrapperCallback) (GdaThreadWrapper *wrapper, gpointer instance, const gchar *signame,
gint n_param_values, const GValue *param_values, gpointer gda_reserved,
gpointer data);
+/**
+ * SECTION:gda-thread-wrapper
+ * @short_description: Execute functions in a sub thread
+ * @title: GdaThreadWrapper
+ * @stability: Stable
+ * @see_also:
+ *
+ * The purpose of the #GdaThreadWrapper object is to execute functions in an isolated sub thread. As the
+ * #GdaThreadWrapper is thread safe, one is able to isolate some code's execution is a <emphasis>private</emphasis>
+ * <emphasis>worker</emphasis> thread, and make a non thread safe code thread safe.
+ *
+ * The downside of this is that the actual execution of the code will be slower as it requires
+ * threads to be synchronized.
+ *
+ * The #GdaThreadWrapper implements its own locking mechanism and can safely be used from multiple
+ * threads at once without needing further locking.
+ *
+ * Each thread using a #GdaThreadWrapper object can use it as if it was the only user: the #GdaThreadWrapper will
+ * simply dispatch all the execution requests to its private <emphasis>worker</emphasis> thread and report the
+ * execution's status only to the thread which made the request.
+ *
+ * The user can also specify a callback function to be called when an object exmits a signal while being
+ * used by the worker thread, see the gda_thread_wrapper_connect_raw() method.
+ *
+ * The following diagram illustrates the conceptual working of the #GdaThreadWrapper object: here two user threads
+ * are represented (assigned a red and green colors), both using a single #GdaThreadWrapper, so in this diagram, 3 threads
+ * are present. The communication between the threads are handled by some #GAsyncQueue objects (in a transparent way for
+ * the user, presented here only for illustration purposes). The queue represented in yellow is where jobs are
+ * pushed by each user thread (step 1), and popped by the worker thread (step 2). Once the user thread has finished
+ * with a job, it stores the result along with the job and pushes it to the queue dedicated to the user thread
+ * (step 3) in this example the red queue (because the job was issued from the thread represented in red). The last
+ * step is when the user fetches the result (in its user thread), step 4.
+ *
+ * If, when the worker thread is busy with a job, a signal is emitted, and if the user has set up a signal handler
+ * using gda_thread_wrapper_connect_raw(),
+ * then a "job as signal" is created by the worker thread and pushed to the user thread as illustrated
+ * at the bottom of the diagram.
+ * <mediaobject>
+ * <imageobject role="html">
+ * <imagedata fileref="thread-wrapper.png" format="PNG" contentwidth="170mm"/>
+ * </imageobject>
+ * <textobject>
+ * <phrase>GdaThreadWrapper's conceptual working</phrase>
+ * </textobject>
+ * </mediaobject>
+ */
+
GType gda_thread_wrapper_get_type (void) G_GNUC_CONST;
GdaThreadWrapper *gda_thread_wrapper_new (void);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
