Merge branch 'mywork' into 'master'

Tracker Documentation: Use tracker_sparql_connection_query_statement() instead...

Closes #128

See merge request GNOME/tracker!424

2 files changed, 46 insertions, 7 deletions

diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
index 7c475fd06..26aac6e3d 100644
--- a/docs/reference/libtracker-sparql/examples.xml
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -35,9 +35,12 @@
     </para>
 
     <para>
-      Once you end up with the query, remember to call <function><link linkend="g-object-unref">g_object_unref</link></function>
-      for the <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>. And the same applies to the
-      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> when no longer needed.
+      The <function><link linkend="tracker-sparql-connection-query-statement">tracker_sparql_connection_query_statement</link></function>
+      function can be used to obtain a <link linkend="TrackerSparqlStatement">TrackerSparqlStatement</link> object holding a prepared SPARQL
+	    query that can then be executed with <function><link linkend="tracker-sparql-statement-execute">tracker_sparql_statement_execute</link>.
+	    The query string can contain <systemitem>~name</systemitem> placeholders which can be replaced with arbitrary values before query execution with the
+	    <function><link linkend="tracker-sparql-statement-bind-string">tracker_sparql_statement_bind_string</link> and similar functions.
+	    This allows parsing the query string only once and to execute it multiple times with different parameters with potentially significant performance gains.
     </para>
 
     <para>
@@ -133,4 +136,3 @@
   </chapter>
 
 </part>
-
diff --git a/docs/reference/libtracker-sparql/examples/readonly-example.c b/docs/reference/libtracker-sparql/examples/readonly-example.c
index 3759e5299..2aafd7e0d 100644
--- a/docs/reference/libtracker-sparql/examples/readonly-example.c
+++ b/docs/reference/libtracker-sparql/examples/readonly-example.c
@@ -5,6 +5,7 @@ int main (int argc, const char **argv)
   GError *error = NULL;
   TrackerSparqlConnection *connection;
   TrackerSparqlCursor *cursor;
+  TrackerSparqlStatement *stmt;
   const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
 
   connection = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", NULL, NULL, &error);
@@ -18,9 +19,9 @@ int main (int argc, const char **argv)
 
   /* Make a synchronous query to the store */
   cursor = tracker_sparql_connection_query (connection,
-                                          query,
-                                          NULL,
-                                          &error);
+                                            query,
+                                            NULL,
+                                            &error);
 
   if (error) {
     /* Some error happened performing the query, not good */
@@ -49,6 +50,42 @@ int main (int argc, const char **argv)
     g_object_unref (cursor);
   }
 
+  /* Prepare the statement with tracker_sparql_connection_query_statement */
+  stmt = tracker_sparql_connection_query_statement (connection,
+                                                    query,
+                                                    NULL,
+                                                    &error);
+
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_printerr ("Couldn't query the Tracker Store: '%s'",
+                error->message);
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Executes the SPARQL query with the currently bound values and get new cursor */
+  cursor = tracker_sparql_statement_execute (stmt, NULL, &error);
+
+  /* Check results... */
+  if (!cursor) {
+    g_print ("No results found :-/\n");
+  } else {
+    gint i = 0;
+
+    /* Iterate, synchronously, the results... */
+    while (tracker_sparql_cursor_next (cursor, NULL, &error)) {
+      g_print ("Result [%d]: %s\n",
+               i++,
+               tracker_sparql_cursor_get_string (cursor, 0, NULL));
+    }
+
+    g_print ("A total of '%d' results were found\n", i);
+
+    g_object_unref (cursor);
+  }
+
   g_object_unref (connection);
 
   return 0;