GNOME.org
 

[tracker/libtracker-sparql: 31/44] libtracker-sparql: Documentation base finished

commit 2e536d9f68f03a544e2335223c581c8139a319aa
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Aug 3 18:59:14 2010 +0200

    libtracker-sparql: Documentation base finished

 .../libtracker-sparql/libtracker-sparql-docs.sgml  |   46 ++--
 .../libtracker-sparql-sections.txt                 |   77 +++++
 .../libtracker-sparql/libtracker-sparql.types      |    5 +-
 src/libtracker-sparql/tracker-connection.vala      |  300 +++++++++++++++++++-
 src/libtracker-sparql/tracker-cursor.vala          |  111 +++++++-
 5 files changed, 498 insertions(+), 41 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index f6b2439..0978b6e 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -1,46 +1,42 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
-<!--!ENTITY tracker SYSTEM "xml/tracker.xml"-->
-<!--!ENTITY tracker-cancel SYSTEM "xml/tracker_cancel.xml"-->
-<!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
-<!--!ENTITY tracker-statistics SYSTEM "xml/tracker_statistics.xml"-->
-<!--!ENTITY tracker-resources SYSTEM "xml/tracker_resources.xml"-->
-<!--!ENTITY tracker-search SYSTEM "xml/tracker_search.xml"-->
 <!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
+<!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
+<!ENTITY tracker-sparql-cursor SYSTEM "xml/tracker-sparql-cursor.xml">
+<!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
 <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
-    <title>Tracker Sparql Library Reference Manual</title>
+    <title>Tracker SPARQL Library Reference Manual</title>
     <releaseinfo>for libtracker-sparql &version;</releaseinfo>
   </bookinfo>
 
-  <part id="libtracker-sparql">
+  <part id="libtracker-sparql-overview">
     <title>Overview</title>
     <partintro>
       <para>
-        The libtracker-sparql library BLA BLA BLA...
+        The libtracker-sparql library is the foundation for Tracker
+        querying and inserting into the data store. The data store
+        allows both querying and inserting using SPARQL based on the
+        Nepomuk ontology.
       </para>
+    </partintro>
+  </part>
+
+  <part id="libtracker-sparql-reference">
+    <title>Reference</title>
+    <partintro>
       <para>
+        This section provides the detailed API of the Tracker SPARQL library.
       </para>
     </partintro>
+
+    &tracker-sparql-builder;
+    &tracker-sparql-connection;
+    &tracker-sparql-cursor;
+    &tracker-misc;
   </part>
 
-    <chapter>
-      <title>General</title>
-<!--      &tracker; -->
-<!--      &tracker-cancel; -->
-      &tracker-misc;
-    </chapter>
-    <!--chapter>
-      <title>Querying</title>
-      &tracker-statistics;
-      &tracker-resources;
-      &tracker-search;
-    </chapter-->
-    <chapter>
-      <title>Building Queries</title>
-      &tracker-sparql-builder;
-    </chapter>
 </book>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index b675a6c..5d5d554 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -7,6 +7,7 @@ tracker_sparql_escape_uri_printf
 tracker_sparql_escape_uri_vprintf
 </SECTION>
 
+
 <SECTION>
 <FILE>tracker-sparql-builder</FILE>
 <TITLE>TrackerSparqlBuilder</TITLE>
@@ -61,3 +62,79 @@ tracker_sparql_builder_construct
 tracker_sparql_builder_construct_embedded_insert
 tracker_sparql_builder_construct_update
 </SECTION>
+
+
+<SECTION>
+<FILE>tracker-sparql-connection</FILE>
+<TITLE>TrackerSparqlConnection</TITLE>
+TrackerSparqlError
+TrackerSparqlConnection
+tracker_sparql_connection_get
+tracker_sparql_connection_get_direct
+tracker_sparql_connection_query
+tracker_sparql_connection_query_async
+tracker_sparql_connection_query_finish
+tracker_sparql_connection_update
+tracker_sparql_connection_update_async
+tracker_sparql_connection_update_finish
+tracker_sparql_connection_update_blank
+tracker_sparql_connection_update_blank_async
+tracker_sparql_connection_update_blank_finish
+tracker_sparql_connection_update_commit
+tracker_sparql_connection_update_commit_async
+tracker_sparql_connection_update_commit_finish
+tracker_sparql_connection_import
+tracker_sparql_connection_import_async
+tracker_sparql_connection_import_finish
+tracker_sparql_connection_statistics
+tracker_sparql_connection_statistics_async
+tracker_sparql_connection_statistics_finish
+<SUBSECTION Standard>
+TrackerSparqlConnectionClass
+TRACKER_SPARQL_CONNECTION
+TRACKER_SPARQL_CONNECTION_CLASS
+TRACKER_SPARQL_CONNECTION_GET_CLASS
+TRACKER_SPARQL_IS_CONNECTION
+TRACKER_SPARQL_IS_CONNECTION_CLASS
+TRACKER_SPARQL_TYPE_CONNECTION
+tracker_sparql_connection_get_type
+<SUBSECTION Private>
+TRACKER_DBUS_INTERFACE_RESOURCES
+TRACKER_DBUS_INTERFACE_STATISTICS
+TRACKER_DBUS_INTERFACE_STEROIDS
+TRACKER_DBUS_OBJECT_RESOURCES
+TRACKER_DBUS_OBJECT_STATISTICS
+TRACKER_DBUS_OBJECT_STEROIDS
+TRACKER_DBUS_SERVICE
+TrackerSparqlConnectionPrivate
+tracker_sparql_connection_construct
+tracker_sparql_error_quark
+</SECTION>
+
+
+<SECTION>
+<FILE>tracker-sparql-cursor</FILE>
+<TITLE>TrackerSparqlCursor</TITLE>
+TrackerSparqlCursor
+tracker_sparql_cursor_get_connection
+tracker_sparql_cursor_get_n_columns
+tracker_sparql_cursor_get_string
+tracker_sparql_cursor_get_type
+tracker_sparql_cursor_next
+tracker_sparql_cursor_next_async
+tracker_sparql_cursor_next_finish
+tracker_sparql_cursor_rewind
+tracker_sparql_cursor_set_connection
+<SUBSECTION Standard>
+TrackerSparqlCursorClass
+TRACKER_SPARQL_CURSOR
+TRACKER_SPARQL_CURSOR_CLASS
+TRACKER_SPARQL_CURSOR_GET_CLASS
+TRACKER_SPARQL_ERROR
+TRACKER_SPARQL_IS_CURSOR
+TRACKER_SPARQL_IS_CURSOR_CLASS
+TRACKER_SPARQL_TYPE_CURSOR
+<SUBSECTION Private>
+TrackerSparqlCursorPrivate
+tracker_sparql_cursor_construct
+</SECTION>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql.types b/docs/reference/libtracker-sparql/libtracker-sparql.types
index 0c5128c..10b4f32 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql.types
+++ b/docs/reference/libtracker-sparql/libtracker-sparql.types
@@ -1 +1,4 @@
-tracker_sparql_builder_get_type
\ No newline at end of file
+tracker_sparql_builder_get_type
+tracker_sparql_builder_state_get_type
+tracker_sparql_connection_get_type
+tracker_sparql_cursor_get_type
\ No newline at end of file
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index 98f8447..8da1cfe 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -17,7 +17,20 @@
  * Boston, MA  02110-1301, USA.
  */
 
-// Convenience
+/**
+ * SECTION: tracker-sparql-connection
+ * @short_description: Connecting to the Store
+ * @title: TrackerSparqlConnection
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * #TrackerSparqlConnection is an object which allows setting up
+ * connections to the Tracker Store.
+ * </para>
+ */
+
+// Convenience, hidden in the documentation
 public const string TRACKER_DBUS_SERVICE = "org.freedesktop.Tracker1";
 public const string TRACKER_DBUS_INTERFACE_RESOURCES = TRACKER_DBUS_SERVICE + ".Resources";
 public const string TRACKER_DBUS_OBJECT_RESOURCES = "/org/freedesktop/Tracker1/Resources";
@@ -26,6 +39,26 @@ public const string TRACKER_DBUS_OBJECT_STATISTICS = "/org/freedesktop/Tracker1/
 public const string TRACKER_DBUS_INTERFACE_STEROIDS = TRACKER_DBUS_SERVICE + ".Steroids";
 public const string TRACKER_DBUS_OBJECT_STEROIDS = "/org/freedesktop/Tracker1/Steroids";
 
+
+/**
+ * TRACKER_SPARQL_ERROR:
+ *
+ * Error domain for Tracker Sparql. Errors in this domain will be from the
+ * #TrackerSparqlError enumeration. See #GError for more information on error
+ * domains.
+ */
+
+/**
+ * TrackerSparqlError:
+ * @TRACKER_SPARQL_ERROR_PARSE: Error parsing the SPARQL string.
+ * @TRACKER_SPARQL_UNKNOWN_CLASS: Unknown class.
+ * @TRACKER_SPARQL_UNKNOWN_PROPERTY: Unknown property.
+ * @TRACKER_SPARQL_TYPE: Wrong type.
+ * @TRACKER_SPARQL_INTERNAL: Internal error.
+ * @TRACKER_SPARQL_UNSUPPORTED: Unsupported feature or method.
+ *
+ * Possible errors reported in the operations with the #TrackerSparqlConnection.
+ */
 public errordomain Tracker.Sparql.Error {
 	PARSE,
 	UNKNOWN_CLASS,
@@ -35,18 +68,34 @@ public errordomain Tracker.Sparql.Error {
 	UNSUPPORTED
 }
 
+/**
+ * TrackerSparqlConnection:
+ *
+ * The <structname>TrackerSparqlConnection</structname> object represents an
+ * connection with the Tracker Store.
+ */
 public abstract class Tracker.Sparql.Connection : Object {
 	static bool direct_only;
 	static weak Connection? singleton;
 	static int verbosity = 0;
 
+	/**
+	 * tracker_sparql_connection_get:
+	 * @error: #GError for error reporting.
+	 *
+	 * Returns a new #TrackerSparqlConnection, which will use the best method
+	 * available to connect to the Tracker Store.
+	 *
+	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+	 * object when no longer used.
+	 */
 	public static Connection get () throws Sparql.Error {
 		if (singleton != null) {
 			assert (!direct_only);
 			return singleton;
 		} else {
 			log_init ();
-			
+
 			var result = new PluginLoader ();
 			singleton = result;
 			result.add_weak_pointer ((void**) (&singleton));
@@ -54,13 +103,23 @@ public abstract class Tracker.Sparql.Connection : Object {
 		}
 	}
 
+	/**
+	 * tracker_sparql_connection_get_direct:
+	 * @error: #GError for error reporting.
+	 *
+	 * Returns a new #TrackerSparqlConnection, which uses direct-access method
+	 * to connect to the Tracker Store.
+	 *
+	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+	 * object when no longer used.
+	 */
 	public static Connection get_direct () throws Sparql.Error {
 		if (singleton != null) {
 			assert (direct_only);
 			return singleton;
 		} else {
 			log_init ();
-			
+
 			var result = new PluginLoader (true /* direct_only */);
 			direct_only = true;
 			singleton = result;
@@ -74,7 +133,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 		string env_verbosity = Environment.get_variable ("TRACKER_SPARQL_VERBOSITY");
 		if (env_verbosity != null)
 			verbosity = env_verbosity.to_int ();
-	
+
 		GLib.Log.set_handler (null, LogLevelFlags.LEVEL_MASK | LogLevelFlags.FLAG_FATAL, log_handler);
 		GLib.Log.set_default_handler (log_handler);
 	}
@@ -131,41 +190,256 @@ public abstract class Tracker.Sparql.Connection : Object {
 		GLib.Log.default_handler (log_domain, log_level, message);
 	}
 
-	// Query
+	/**
+	 * tracker_sparql_connection_query:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL query on the store. The API call is completely
+	 * synchronous, so it may block.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public abstract Cursor query (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
+
+	/**
+	 * tracker_sparql_connection_query_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL query
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL query on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_query_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL query operation.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public async abstract Cursor query_async (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
 
-	// Update
+	/**
+	 * tracker_sparql_connection_update:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL update on the store. The API call is completely
+	 * synchronous, so it may block.
+	 */
 	public virtual void update (string sparql, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_update_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @priority: the priority for the asynchronous operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL update on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL update operation.
+	 */
 	public async virtual void update_async (string sparql, int priority = GLib.Priority.DEFAULT, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_async' not implemented");
 	}
 
-	// Only applies to update_async with the right priority. 
-	// Priority is used to identify batch updates.
+	/**
+	 * tracker_sparql_connection_update_blank:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL update on the store, and returns the URNs of the
+	 * generated nodes, if any. The API call is completely synchronous, so it
+	 * may block.
+	 *
+	 * Returns: a #GVariant with the generated URNs, which should be freed with
+	 * g_variant_unref() when no longer used.
+	 */
+	public virtual GLib.Variant? update_blank (string sparql, Cancellable? cancellable = null) throws Sparql.Error {
+		warning ("Interface 'update_blank' not implemented");
+		return null;
+	}
+
+	/**
+	 * tracker_sparql_connection_update_blank_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @priority: the priority for the asynchronous operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL update on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_blank_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL update operation, and returns
+	 * the URNs of the generated nodes, if any.
+	 *
+	 * Returns: a #GVariant with the generated URNs, which should be freed with
+	 * g_variant_unref() when no longer used.
+	 */
+	public async virtual GLib.Variant? update_blank_async (string sparql, int priority = GLib.Priority.DEFAULT, Cancellable? cancellable = null) throws Sparql.Error {
+		warning ("Interface 'update_blank_async' not implemented");
+		return null;
+	}
+
+	/**
+	 * tracker_sparql_connection_update_commit:
+	 * @self: a #TrackerSparqlConnection
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Makes sure that any previous asynchronous update has been commited
+	 * to the store. Only applies to tracker_sparql_connection_update_async()
+	 * with the right priority (Priority is used to identify batch updates.)
+	 * The API call is completely synchronous, so it may block.
+	 */
 	public virtual void update_commit (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_commit' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_update_commit_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Makes sure, asynchronously, that any previous asynchronous update has
+	 * been commited to the store. Only applies to
+	 * tracker_sparql_connection_update_async() with the right priority
+	 * (Priority is used to identify batch updates.)
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_commit_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous commit operation.
+	 */
 	public async virtual void update_commit_async (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_commit_async' not implemented");
 	}
-	
-	// Import
+
+	/**
+	 * tracker_sparql_connection_import:
+	 * @self: a #TrackerSparqlConnection
+	 * @file: a #GFile
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Loads a Turtle file (TTL) into the store. The API call is completely
+	 * synchronous, so it may block.
+	 */
 	public virtual void import (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_import_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @file: a #GFile
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Loads, asynchronously, a Turtle file (TTL) into the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_import_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous load of the Turtle file.
+	 */
 	public async virtual void import_async (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import_async' not implemented");
 	}
-	
-	// Statistics
+
+	/**
+	 * tracker_sparql_connection_statistics:
+	 * @self: a #TrackerSparqlConnection
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Retrieves the statistics from the Store. The API call is completely
+	 * synchronous, so it may block.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public virtual Cursor? statistics (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics' not implemented");
 		return null;
 	}
-	
+
+	/**
+	 * tracker_sparql_connection_statistics_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Retrieves, asynchronously, the statistics from the Store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_statistics_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous retrieval of statistics from the Store.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public async virtual Cursor? statistics_async (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics_async' not implemented");
 		return null;
diff --git a/src/libtracker-sparql/tracker-cursor.vala b/src/libtracker-sparql/tracker-cursor.vala
index 3a83173..a1f6402 100644
--- a/src/libtracker-sparql/tracker-cursor.vala
+++ b/src/libtracker-sparql/tracker-cursor.vala
@@ -17,12 +17,119 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/**
+ * SECTION: tracker-sparql-cursor
+ * @short_description: Iteration of the query results
+ * @title: TrackerSparqlCursor
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * #TrackerSparqlCursor is an object which provides methods to iterate the
+ * results of a query to the Tracker Store.
+ * </para>
+ */
+
+
+/**
+ * TrackerSparqlCursor:
+ *
+ * The <structname>TrackerSparqlCursor</structname> object represents an
+ * iterator of results.
+ */
 public abstract class Tracker.Sparql.Cursor : Object {
-	public Connection connection { get; set; }
-	public abstract int n_columns { get; }
+
+	/**
+	 * TrackerSparqlCursor:connection:
+	 *
+	 * The #TrackerSparqlConnection used to retrieve the results.
+	 */
+	public Connection connection {
+		/**
+		 * tracker_sparql_cursor_get_connection:
+		 * @self: a #TrackerSparqlCursor
+		 *
+		 * Returns the connection used to retrieve the results.
+		 *
+		 * Returns: a #TrackerSparqlConnection. The returned object must not
+		 * be freed by the caller.
+		 */
+		get;
+		// Note: set method hidden in the documentation as the user of the
+		//  library should never use it.
+		set;
+	}
+
+	/**
+	 * TrackerSparqlCursor:n_columns:
+	 *
+	 * Number of columns available in the results to iterate.
+	 */
+	public abstract int n_columns {
+		/**
+		 * tracker_sparql_cursor_get_n_columns:
+		 * @self: a #TrackerSparqlCursor
+		 *
+		 * Returns the number of columns available in the results to iterate.
+		 *
+		 * Returns: a #gint with the number of columns.
+		 */
+		get;
+	}
+
+	/**
+	 * tracker_sparql_cursor_get_string:
+	 * @self: a #TrackerSparqlCursor
+	 * @column: column number to retrieve
+	 * @length: length of the returned string
+	 *
+	 * Returns the string at @column in the current row being iterated.
+	 *
+	 * Returns: a string, which should not be freed by the caller.
+	 */
 	public abstract unowned string? get_string (int column, out long length = null);
 
+	/**
+	 * tracker_sparql_cursor_next:
+	 * @self: a #TrackerSparqlCursor
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Iterates to the next result. The API call is completely synchronous, so
+	 * it may block.
+	 *
+	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 */
 	public abstract bool next (Cancellable? cancellable = null) throws GLib.Error;
+
+	/**
+	 * tracker_sparql_cursor_next_async:
+	 * @self: a #TrackerSparqlCursor
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Iterates, asynchronously, to the next result.
+	 */
+
+	/**
+	 * tracker_sparql_cursor_next_finish:
+	 * @self: a #TrackerSparqlCursor
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous iteration to the next result.
+	 *
+	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 */
 	public async abstract bool next_async (Cancellable? cancellable = null) throws GLib.Error;
+
+	/**
+	 * tracker_sparql_cursor_rewind:
+	 * @self: a #TrackerSparqlCursor
+	 *
+	 * Resets the iterator to point back to the first result.
+	 */
 	public abstract void rewind ();
 }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]