[tracker/libtracker-sparql: 51/55] libtracker-sparql: Added update example in documentation

[Jürg Billeter <juergbi src gnome org>]

commit 5b4412db10cde3c45eac2f617e067510c705a8f3
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Wed Aug 4 16:07:16 2010 +0200

    libtracker-sparql: Added update example in documentation

 docs/reference/libtracker-sparql/examples.xml |  103 ++++++++++++++++++++++++-
 1 files changed, 101 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
index 9975c53..3507571 100644
--- a/docs/reference/libtracker-sparql/examples.xml
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -10,7 +10,7 @@
 
 
   <chapter id="tracker-examples-builder">
-    <title>Generating proper SPARQL queries with the Builder</title>
+    <title>SPARQL query builder</title>
 
     <para>
       The Tracker SPARQL library provides an easy and secure way of creating
@@ -82,7 +82,7 @@ int main (int argc, char **argv)
   </chapter>
 
   <chapter id="tracker-examples-readonly">
-    <title>Read-Only queries to the store</title>
+    <title>Querying the Store</title>
 
     <para>
       In order to perform read-only queries to the store, a new
@@ -180,5 +180,104 @@ int main (int argc, const char **argv)
 </programlisting>
     </para>
   </chapter>
+
+  <chapter id="tracker-examples-writeonly">
+    <title>Updating the Store</title>
+
+    <para>
+      In order to perform updates in the store, a new
+      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>
+      object must be acquired with
+      <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function>.
+      Note that you MUST NOT use a specific direct-access connection obtained with
+      <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function>, as the direct-access method only supports read-only queries.
+    </para>
+
+    <para>
+      Once a proper connection object has been acquired, the update can be launched either
+      synchronously (<function><link linkend="tracker-sparql-connection-update">tracker_sparql_connection_update</link></function>)
+      or asynchronously (<function><link linkend="tracker-sparql-connection-update-async">tracker_sparql_connection_update_async</link></function>).
+      If launched asynchronously, the result of the operation can be obtained with
+      <function><link linkend="tracker-sparql-connection-update-finish">tracker_sparql_connection_update_finish</link></function>.
+    </para>
+
+    <para>
+      You can assure that all previous update operations where commited to the store before
+      going on with the program, using
+      <function><link linkend="tracker-sparql-connection-update-commit">tracker_sparql_connection_update_commit</link></function>
+      or its equivalent asynchronous version (
+      <function><link linkend="tracker-sparql-connection-update-commit-async">tracker_sparql_connection_update_commit_async</link></function>)
+    </para>
+
+    <para>
+      Once you no longer need the connection, remember to call <function><link linkend="g-object-unref">g_object_unref</link></function>
+      for the <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type>.
+    </para>
+
+    <para>
+      The following program shows how a synchronous update can be done to the store:
+
+<programlisting>
+#include &lt;tracker-sparql.h&gt;
+
+int main (int argc, const char **argv)
+{
+  GError *error = NULL;
+  <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> *connection;
+  const gchar *query =
+    "INSERT { "
+    "  _:tag a nao:Tag ; "
+    "        nao:prefLabel 'mylabel' . "
+    "} WHERE { "
+    "  OPTIONAL { "
+    "    ?tag a nao:Tag ; "
+    "    nao:prefLabel 'mylabel' "
+    "  } . "
+    "FILTER (!bound(?tag)) "
+    "}";
+
+  /* Initialize GLib type system */
+  g_type_init ();
+
+  /* Do NOT get a direct connection if you're going to
+   * do some write operation in the Store */
+  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (&amp;error);
+  if (!connection) {
+    /* Some error happened getting the connection, not good */
+    g_error ("Couldn't obtain a connection to the "
+             "Tracker Store: '%s'",
+             error ? error-&gt;message : "unknown error");
+  }
+
+  /* Run a synchronous update query */
+  <function><link linkend="tracker-sparql-connection-update">tracker_sparql_connection_update</link></function> (connection,
+  					    query,
+  					    NULL,
+  					    &amp;error);
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_error ("Couldn't update the Tracker Store: '%s'",
+             error ? error-&gt;message : "unknown error");
+  }
+
+  /* Commit the transaction (not really needed in this
+   * example, but anyway) */
+  <function><link linkend="tracker-sparql-connection-update-commit">tracker_sparql_connection_update_commit</link></function> (connection,
+				    NULL,
+				    &amp;error);
+  if (error) {
+    /* Some error happened commiting, not good */
+    g_error ("Couldn't commit all previous transactions: '%s'",
+             error ? error-&gt;message : "unknown error");
+  }
+
+  g_object_unref (connection);
+
+  return 0;
+}
+</programlisting>
+    </para>
+  </chapter>
+
 </part>