[tracker] libtracker-sparql: Document requirement to escape constructed queries

[Philip Withnall <pwithnall src gnome org>]

commit 87a539e53ce395c03679c44b5a4497aa121695ef
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 18:32:06 2014 +0000

    libtracker-sparql: Document requirement to escape constructed queries
    
    Bring SQL injection to the front of people’s minds when using the APIs
    so that hopefully they don’t write injectable code.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741777

 src/libtracker-sparql/tracker-connection.vala |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)
---
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index dec849a..1e1749e 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -220,6 +220,10 @@ public abstract class Tracker.Sparql.Connection : Object {
         * Executes a SPARQL query on. The API call is completely synchronous, so
         * it may block.
         *
+        * The @sparql query should be built with #TrackerSparqlBuilder, or
+        * its parts correctly escaped using tracker_sparql_escape_string(),
+        * otherwise SPARQL injection is possible.
+        *
         * Returns: a #TrackerSparqlCursor if results were found, #NULL otherwise.
         * On error, #NULL is returned and the @error is set accordingly.
         * Call g_object_unref() on the returned cursor when no longer needed.
@@ -269,6 +273,10 @@ public abstract class Tracker.Sparql.Connection : Object {
         * Executes a SPARQL update. The API call is completely
         * synchronous, so it may block.
         *
+        * The @sparql query should be built with #TrackerSparqlBuilder, or
+        * its parts correctly escaped using tracker_sparql_escape_string(),
+        * otherwise SPARQL injection is possible.
+        *
         * Since: 0.10
         */
        public virtual void update (string sparql, int priority = GLib.Priority.DEFAULT, Cancellable? 
cancellable = null) throws Sparql.Error, GLib.Error, GLib.IOError, DBusError {
@@ -381,6 +389,10 @@ public abstract class Tracker.Sparql.Connection : Object {
         * Executes a SPARQL update and returns the URNs of the generated nodes,
         * if any. The API call is completely synchronous, so it may block.
         *
+        * The @sparql query should be built with #TrackerSparqlBuilder, or
+        * its parts correctly escaped using tracker_sparql_escape_string(),
+        * otherwise SPARQL injection is possible.
+        *
         * Returns: a #GVariant with the generated URNs, which should be freed with
         * g_variant_unref() when no longer used.
         *