tracker r1300 - branches/xesam-support/src/trackerd

[pvanhoof svn gnome org]

Author: pvanhoof
Date: Thu Apr 24 11:41:08 2008
New Revision: 1300
URL: http://svn.gnome.org/viewvc/tracker?rev=1300&view=rev

Log:
Added some documentation and fixed some API

Modified:
   branches/xesam-support/src/trackerd/tracker-xesam-live-search.c
   branches/xesam-support/src/trackerd/tracker-xesam-live-search.h
   branches/xesam-support/src/trackerd/tracker-xesam-search.c
   branches/xesam-support/src/trackerd/tracker-xesam-search.h
   branches/xesam-support/src/trackerd/tracker-xesam-session.c
   branches/xesam-support/src/trackerd/tracker-xesam-session.h
   branches/xesam-support/src/trackerd/tracker-xesam.h

Modified: branches/xesam-support/src/trackerd/tracker-xesam-live-search.c
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-live-search.c	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-live-search.c	Thu Apr 24 11:41:08 2008
@@ -20,10 +20,12 @@
  */
 
 #include "tracker-xesam-live-search.h"
-
+#include "tracker-xesam-search.h"
+#include "tracker-dbus.h"
 
 struct _TrackerXesamLiveSearchPriv {
 	gchar *search_id;
+	gboolean active;
 };
 
 G_DEFINE_TYPE(TrackerXesamLiveSearch, tracker_xesam_live_search, G_TYPE_OBJECT)
@@ -50,36 +52,223 @@
 {
 	TrackerXesamLiveSearchPriv *priv = self->priv;
 	priv->search_id = NULL;
+	priv->active = FALSE;
+}
+
+
+
+/**
+ * tracker_xesam_live_search_emit_hits_added:
+ * @self: A #TrackerXesamLiveSearch
+ * @count: The number of hits added
+ *
+ * Emits the @hits-added signal on the DBus proxy for Xesam
+ **/
+void 
+tracker_xesam_live_search_emit_hits_added (TrackerXesamLiveSearch *self, guint count) 
+{
+	TrackerXesamSearch *proxy;
+
+	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
+
+	g_signal_emit (proxy, xesam_signals[XESAM_HITS_ADDED], 0, 
+		tracker_xesam_live_search_get_id (self), count);
+}
+
+
+/**
+ * tracker_xesam_live_search_emit_hits_removed:
+ * @self: A #TrackerXesamLiveSearch
+ * @hit_ids: modified hit ids
+ * @hit_ids_length: length of the @hit_ids array
+ *
+ * Emits the @hits-removed signal on the DBus proxy for Xesam
+ *
+ * The hit ids in the array no longer match the query. Any calls to GetHitData 
+ * on any of the given hit ids should return unset fields.
+ **/
+void 
+tracker_xesam_live_search_emit_hits_removed (TrackerXesamLiveSearch *self, guint *hit_ids, gint hit_ids_length) 
+{
+	TrackerXesamSearch *proxy;
+
+	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
+
+	g_signal_emit (proxy, xesam_signals[XESAM_HITS_REMOVED], 0, 
+		tracker_xesam_live_search_get_id (self), 0); // todo
+}
+
+
+/**
+ * tracker_xesam_live_search_emit_hits_modified:
+ * @selfs: A #TrackerXesamLiveSearch
+ * @hit_ids: modified hit ids
+ * @hit_ids_length: length of the @hit_ids array
+ *
+ * Emits the @hits-modified signal on the DBus proxy for Xesam
+ *
+ * The documents corresponding to the hit ids in the array have been modified. 
+ * They can have been moved in which case their uri will have changed.
+ **/
+void 
+tracker_xesam_live_search_emit_hits_modified (TrackerXesamLiveSearch *self, guint *hit_ids, gint hit_ids_length) 
+{
+	TrackerXesamSearch *proxy;
+
+	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
+
+	g_signal_emit (proxy, xesam_signals[XESAM_HITS_MODIFIED], 0, 
+		tracker_xesam_live_search_get_id (self), 0); // todo
 }
 
+
+/**
+ * tracker_xesam_live_search_emit_done:
+ * @self: A #TrackerXesamLiveSearch
+ *
+ * Emits the @search-done signal on the DBus proxy for Xesam.
+ * 
+ * The given search has scanned the entire index. For non-live searches this 
+ * means that no more hits will be available. For a live search this means that 
+ * all future signals (@hits-Added, @hits-removed, @hits-modified) will be 
+ * related to objects that changed in the index.
+ **/
 void 
-tracker_xesam_live_search_get_hit_count (TrackerXesamLiveSearch *self, guint *count)
+tracker_xesam_live_search_emit_done (TrackerXesamLiveSearch *self) 
+{
+	TrackerXesamSearch *proxy;
+
+	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
+
+	g_signal_emit (proxy, xesam_signals[XESAM_SEARCH_DONE], 0, 
+		tracker_xesam_live_search_get_id (self)); 
+}
+
+/**
+ * tracker_xesam_live_search_close:
+ * @self: a #TrackerXesamLiveSearch
+ * @error: (null-ok) (out): a #GError
+ *
+ * Close @self. An error will be thrown if @self was already closed.
+ **/
+void 
+tracker_xesam_live_search_close (TrackerXesamLiveSearch *self, GError **error)
+{
+	// todo
+}
+
+
+/**
+ * tracker_xesam_live_search_get_hit_count:
+ * @self: a #TrackerXesamLiveSearch
+ * @count: (out): the current number of found hits
+ * @error: (null-ok) (out): a #GError
+ *
+ * Get the current number of found hits.
+ *
+ * An error will be thrown if the search has not been started with 
+ * @tracker_xesam_live_search_activate yet.
+ **/
+void 
+tracker_xesam_live_search_get_hit_count (TrackerXesamLiveSearch *self, guint *count, GError **error)
 {
 	// todo
 	*count = 0;
 }
 
+/**
+ * tracker_xesam_live_search_get_hits:
+ * @self: a #TrackerXesamLiveSearch
+ * @num: Number of hits to retrieve
+ * @hits: (out) (caller-owns): An array of field data for each hit as requested 
+ * via the hit fields property 
+ * @error: (null-ok) (out): a #GError
+ *
+ * Get the field data for the next num hits. This call blocks until there is num 
+ * hits available or the index has been fully searched (and SearchDone emitted).
+ *
+ * An error will be thrown if the search has not been started with 
+ * @tracker_xesam_live_search_activate yet.
+ **/
 void 
-tracker_xesam_live_search_get_hits (TrackerXesamLiveSearch *self, gpointer **hits)
+tracker_xesam_live_search_get_hits (TrackerXesamLiveSearch *self, guint num, gpointer **hits, GError **error)
 {
 	// todo
 	*hits = NULL;
 }
 
+/**
+ * tracker_xesam_live_search_get_hit_data:
+ * @self: a #TrackerXesamLiveSearch
+ * @hit_ids: Array of hit serial numbers for which to retrieve data
+ * @fields: The names of the fields to retrieve for the listed hits. It is 
+ * recommended that this is a subset of the fields listed in hit.fields and 
+ * hit.fields.extended
+ * @hit_data: Array of hits in the same order as the hit ids specified. See 
+ * the section about hit retrieval below. If @hits-removed has been emitted on 
+ * a hit, the returned hit data will consist of unset fields, ie this is not an 
+ * error condition.
+ * @error: (null-ok) (out): a #GError
+ *
+ * Get renewed or additional hit metadata. Primarily intended for snippets or 
+ * modified hits. The hit_ids argument is an array of serial numbers as per hit
+ * entries returned by GetHits. The returned hits will be in the same order as 
+ * the provided @hit_ids. The requested properties does not have to be the ones 
+ * listed in in the hit.fields or hit.fields.extended session properties, 
+ * although this is the recommended behavior.
+ *
+ * An error will be raised if the search handle has been closed or is unknown. 
+ * An error will also be thrown if the search has not been started with 
+ * @tracker_xesam_live_search_activate yet
+ *
+ * Calling on a hit that has been marked removed by the @hits-removed signal 
+ * will not result in an error, but return only unset fields.
+ **/
 void 
-tracker_xesam_live_search_get_hit_data (TrackerXesamLiveSearch *self, gpointer **hit_data)
+tracker_xesam_live_search_get_hit_data (TrackerXesamLiveSearch *self, guint *hit_ids, const gchar **fields, gpointer **hit_data, GError **error)
 {
 	// todo
 	*hit_data = NULL;
 }
 
+/**
+ * tracker_xesam_live_search_is_active:
+ * @self: a #TrackerXesamLiveSearch
+ *
+ * Get whether or not @self is active.
+ *
+ * @returns: whether or not @self is active
+ **/
+gboolean 
+tracker_xesam_live_search_is_active (TrackerXesamLiveSearch *self)
+{
+	TrackerXesamLiveSearchPriv *priv = self->priv;
+	return priv->active;
+}
+
+/**
+ * tracker_xesam_live_search_activate:
+ * @self: a #TrackerXesamLiveSearch
+ *
+ * Activates @self
+ **/
 void 
 tracker_xesam_live_search_activate (TrackerXesamLiveSearch *self)
 {
+	TrackerXesamLiveSearchPriv *priv = self->priv;
 	// todo
+	priv->active = TRUE;
 }
 
 
+/**
+ * tracker_xesam_live_search_get_query:
+ * @self: a #TrackerXesamLiveSearch
+ *
+ * Gets the query
+ *
+ * @returns: a read-only string with the query
+ **/
 const gchar* 
 tracker_xesam_live_search_get_query (TrackerXesamLiveSearch *self)
 {
@@ -87,6 +276,14 @@
 	return "WHERE 1=1";
 }
 
+
+/**
+ * tracker_xesam_live_search_set_id:
+ * @self: A #TrackerXesamLiveSearch
+ * @search_id: a unique ID string for @self
+ *
+ * Set a read-only unique ID string for @self.
+ **/
 void 
 tracker_xesam_live_search_set_id (TrackerXesamLiveSearch *self, const gchar *search_id)
 {
@@ -96,6 +293,14 @@
 	priv->search_id = g_strdup (search_id);
 }
 
+/**
+ * tracker_xesam_live_search_get_id:
+ * @self: A #TrackerXesamLiveSearch
+ *
+ * Get the read-only unique ID string for @self.
+ *
+ * returns: a unique id
+ **/
 const gchar* 
 tracker_xesam_live_search_get_id (TrackerXesamLiveSearch *self)
 {
@@ -103,6 +308,13 @@
 	return (const gchar*) priv->search_id;
 }
 
+/**
+ * tracker_xesam_live_search_new:
+ *
+ * Create a new #TrackerXesamLiveSearch
+ *
+ * @returns: (caller-owns): a new #TrackerXesamLiveSearch
+ **/
 TrackerXesamLiveSearch* 
 tracker_xesam_live_search_new (const gchar *query_xml) 
 {

Modified: branches/xesam-support/src/trackerd/tracker-xesam-live-search.h
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-live-search.h	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-live-search.h	Thu Apr 24 11:41:08 2008
@@ -54,11 +54,16 @@
 const gchar* tracker_xesam_live_search_get_id (TrackerXesamLiveSearch *self);
 const gchar* tracker_xesam_live_search_get_query (TrackerXesamLiveSearch *self);
 void tracker_xesam_live_search_activate (TrackerXesamLiveSearch *self);
+gboolean tracker_xesam_live_search_is_active (TrackerXesamLiveSearch *self);
+void tracker_xesam_live_search_get_hit_data (TrackerXesamLiveSearch *self, guint *hit_ids, const gchar **fields, gpointer **hit_data, GError **error);
+void tracker_xesam_live_search_get_hits (TrackerXesamLiveSearch *self, guint num, gpointer **hits, GError **error);
+void tracker_xesam_live_search_get_hit_count (TrackerXesamLiveSearch *self, guint *count, GError **error);
+void tracker_xesam_live_search_close (TrackerXesamLiveSearch *self, GError **error);
 
-void tracker_xesam_live_search_get_hit_data (TrackerXesamLiveSearch *self, gpointer **hit_data);
-void tracker_xesam_live_search_get_hits (TrackerXesamLiveSearch *self, gpointer **hits);
-void tracker_xesam_live_search_get_hit_count (TrackerXesamLiveSearch *self, guint *count);
-
+void tracker_xesam_live_search_emit_hits_added (TrackerXesamLiveSearch *self, guint count);
+void tracker_xesam_live_search_emit_hits_removed (TrackerXesamLiveSearch *self, guint *hit_ids, gint hit_ids_length);
+void tracker_xesam_live_search_emit_hits_modified (TrackerXesamLiveSearch *self, guint *hit_ids, gint hit_ids_length);
+void tracker_xesam_live_search_emit_done (TrackerXesamLiveSearch *self);
 
 G_END_DECLS
 

Modified: branches/xesam-support/src/trackerd/tracker-xesam-search.c
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-search.c	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-search.c	Thu Apr 24 11:41:08 2008
@@ -173,9 +173,20 @@
 				    GError             **error)
 {
 	guint request_id = tracker_dbus_get_next_request_id ();
+	TrackerXesamSession *session = tracker_xesam_get_session (session_id, error);
 
-	tracker_xesam_close_session (session_id, error);
+	if (session) {
+		GList *searches = tracker_xesam_session_get_searches (session);
+		while (searches) {
+			TrackerXesamLiveSearch *search = searches->data;
+			tracker_xesam_live_search_close (search, NULL);
+			searches = g_list_next (searches);
+		}
+		g_list_free (searches);
+		g_object_unref (session);
+	}
 
+	tracker_xesam_close_session (session_id, error);
 	tracker_dbus_request_success (request_id);
 
 	return TRUE;
@@ -186,15 +197,17 @@
 tracker_xesam_search_set_property (TrackerXesamSearch   *object,
 				  const gchar         *session_id,
 				  const gchar         *prop,
-				  gpointer             val,  /* not sure */
-				  gpointer            *new_val,  /* not sure */
+				  gchar               *val,  /* not sure */
+				  gchar              **new_val,  /* not sure */
 				  GError             **error)
 {
 	guint request_id = tracker_dbus_get_next_request_id ();
 	TrackerXesamSession *session = tracker_xesam_get_session (session_id, error);
 
-	if (session)
-		tracker_xesam_session_set_property (session, prop, val);
+	if (session) {
+		tracker_xesam_session_set_property (session, prop, val, new_val);
+		g_object_unref (session);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -205,7 +218,7 @@
 tracker_xesam_search_get_property (TrackerXesamSearch  *object,
 				   const gchar         *session_id,
 				   const gchar         *prop,
-				   gpointer            *value,  /* not sure */
+				   gchar              **value,  /* not sure */
 				   GError             **error)
 {
 	guint request_id = tracker_dbus_get_next_request_id ();
@@ -213,7 +226,7 @@
 
 	if (session) {
 		gchar *ret = NULL;
-		ret = tracker_xesam_session_get_property (session, prop);
+		tracker_xesam_session_get_property (session, prop, &ret);
 		*value = g_strdup (ret);
 		g_free (ret);
 	}
@@ -237,10 +250,13 @@
 	if (session) {
 		TrackerXesamLiveSearch *search;
 		gchar *ret = NULL;
-		search = tracker_xesam_session_create_search (session, query_xml, &ret);
-		*search_id = g_strdup (ret);
-		g_free (ret);
-		g_object_unref (search);
+		search = tracker_xesam_session_create_search (session, query_xml, &ret, error);
+		if (ret) {
+			*search_id = g_strdup (ret);
+			g_free (ret);
+		}
+		if (search)
+			g_object_unref (search);
 	}
 
 	tracker_dbus_request_success (request_id);
@@ -256,9 +272,10 @@
 	guint request_id = tracker_dbus_get_next_request_id ();
 	TrackerXesamLiveSearch *search = tracker_xesam_get_live_search (search_id, error);
 
-	tracker_xesam_live_search_activate (search);
-
-	g_object_unref (search);
+	if (search) {
+		tracker_xesam_live_search_activate (search);
+		g_object_unref (search);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -274,9 +291,10 @@
 	guint request_id = tracker_dbus_get_next_request_id ();
 	TrackerXesamLiveSearch *search = tracker_xesam_get_live_search (search_id, error);
 
-	tracker_xesam_live_search_get_hit_count (search, count);
-
-	g_object_unref (search);
+	if (search) {
+		tracker_xesam_live_search_get_hit_count (search, count, error);
+		g_object_unref (search);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -293,9 +311,10 @@
 	guint request_id = tracker_dbus_get_next_request_id ();
 	TrackerXesamLiveSearch *search = tracker_xesam_get_live_search (search_id, error);
 
-	tracker_xesam_live_search_get_hits (search, hits);
-
-	g_object_unref (search);
+	if (search) {
+		tracker_xesam_live_search_get_hits (search, num, hits, error);
+		g_object_unref (search);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -313,9 +332,10 @@
 	guint request_id = tracker_dbus_get_next_request_id ();
 	TrackerXesamLiveSearch *search = tracker_xesam_get_live_search (search_id, error);
 
-	tracker_xesam_live_search_get_hit_data (search, hit_data);
-
-	g_object_unref (search);
+	if (search) {
+		tracker_xesam_live_search_get_hit_data (search, hit_ids, fields, hit_data, error);
+		g_object_unref (search);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -328,16 +348,12 @@
 				   GError             **error)
 {
 	guint request_id = tracker_dbus_get_next_request_id ();
-	TrackerXesamLiveSearch *search = NULL;
-	TrackerXesamSession *session = tracker_xesam_get_session_for_search (search_id, &search, error);
-
-	if (search && session)
-		tracker_xesam_session_close_search (session, search);
+	TrackerXesamLiveSearch *search = tracker_xesam_get_live_search (search_id, error);
 
-	if (session)
-		g_object_unref (session);
-	if (search)
+	if (search) {
+		tracker_xesam_live_search_close (search, error);
 		g_object_unref (search);
+	}
 
 	tracker_dbus_request_success (request_id);
 
@@ -358,3 +374,25 @@
 	return TRUE;
 }
 
+/**
+ * tracker_xesam_search_emit_state_changed:
+ * @self: A #TrackerXesamSearch
+ * @state_info: (in): a list of strings that contain the state
+ * @state_info_length: amount of strings in @state_info
+ *
+ * Emits the @state-changed signal on the DBus proxy for Xesam.
+ *
+ * When the state as returned by @tracker_get_state changes this @state-changed
+ * signal must be fired with an argument as described in said method. If the 
+ * indexer expects to only enter the UPDATE state for a very brief period 
+ * - indexing one changed file - it is not required that the @state-changed
+ * signal is fired. The signal only needs to be fired if the process of updating 
+ * the index is going to be non-negligible. The purpose of this signal is not to 
+ * provide exact details on the engine, just to provide hints for a user 
+ * interface.
+ **/
+void 
+tracker_xesam_search_emit_state_changed (TrackerXesamSearch *self, gchar **state_info, gint state_info_length) 
+{
+	g_signal_emit (self, xesam_signals[XESAM_STATE_CHANGED], 0, 0); // todo
+}

Modified: branches/xesam-support/src/trackerd/tracker-xesam-search.h
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-search.h	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-search.h	Thu Apr 24 11:41:08 2008
@@ -42,6 +42,7 @@
 #define TRACKER_IS_XESAM_SEARCH_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), TRACKER_TYPE_XESAM_SEARCH))
 #define TRACKER_XESAM_SEARCH_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), TRACKER_TYPE_XESAM_SEARCH, TrackerXesamSearchClass))
 
+
 typedef struct TrackerXesamSearch      TrackerXesamSearch;
 typedef struct TrackerXesamSearchClass TrackerXesamSearchClass;
 
@@ -78,13 +79,13 @@
 gboolean tracker_xesam_search_set_property     (TrackerXesamSearch   *object,
 						const gchar         *session_id,
 						const gchar         *prop,
-						gpointer             val,  /* not sure */
-						gpointer            *new_val,  /* not sure */
+						gchar               *val,  /* not sure */
+						gchar              **new_val,  /* not sure */
 						GError             **error);
 gboolean tracker_xesam_search_get_property     (TrackerXesamSearch  *object,
 						const gchar         *session_id,
 						const gchar         *prop,
-						gpointer            *value,  /* not sure */
+						gchar              **value,  /* not sure */
 						GError             **error);
 gboolean tracker_xesam_search_close_session    (TrackerXesamSearch  *object,
 						const gchar         *session_id,
@@ -119,6 +120,9 @@
 						gchar             ***state_info, /* not sure */
 						GError             **error);
 
+
+void tracker_xesam_search_emit_state_changed (TrackerXesamSearch *self, gchar **state_info, gint state_info_length);
+
 G_END_DECLS
 
 #endif /* __TRACKER_XESAM_SEARCH_H__ */

Modified: branches/xesam-support/src/trackerd/tracker-xesam-session.c
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-session.c	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-session.c	Thu Apr 24 11:41:08 2008
@@ -60,6 +60,13 @@
 	object_class->finalize = tracker_xesam_session_finalize;
 }
 
+/**
+ * tracker_xesam_session_get_id:
+ * @self: A #TrackerXesamSession
+ * @session_id: a unique ID string for @self
+ *
+ * Set a read-only unique ID string for @self.
+ **/
 void 
 tracker_xesam_session_set_id (TrackerXesamSession *self, const gchar *session_id)
 {
@@ -69,6 +76,14 @@
 	priv->session_id = g_strdup (session_id);
 }
 
+/**
+ * tracker_xesam_session_get_id:
+ * @self: A #TrackerXesamSession
+ *
+ * Get the read-only unique ID string for @self.
+ *
+ * returns: a unique id
+ **/
 const gchar* 
 tracker_xesam_session_get_id (TrackerXesamSession *self)
 {
@@ -76,6 +91,17 @@
 	return (const gchar*) priv->session_id;
 }
 
+
+
+/**
+ * tracker_xesam_session_get_searches:
+ * @self: A #TrackerXesamSession
+ *
+ * Get all searches in @self as a doubly linked list containing 
+ * #TrackerXesamLiveSearch objects.
+ *
+ * @returns: (caller-owns) (null-ok): all searches in @self
+ **/
 GList *
 tracker_xesam_session_get_searches (TrackerXesamSession *self)
 {
@@ -83,102 +109,91 @@
 	return g_hash_table_get_values (priv->searches);
 }
 
-void 
-tracker_xesam_session_hits_added (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint count) 
-{
-	TrackerXesamSearch *proxy;
-
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-	g_return_if_fail (search == NULL || TRACKER_IS_SEARCH (search));
-
-	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
-
-	g_signal_emit (proxy, xesam_signals[XESAM_HITS_ADDED], 0, 
-		tracker_xesam_live_search_get_id (search), count);
-}
-
-
-void 
-tracker_xesam_session_hits_removed (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint *hit_ids, gint hit_ids_length) 
-{
-	TrackerXesamSearch *proxy;
-
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-	g_return_if_fail (search == NULL || TRACKER_IS_SEARCH (search));
-
-	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
-
-	g_signal_emit (proxy, xesam_signals[XESAM_HITS_REMOVED], 0, 
-		tracker_xesam_live_search_get_id (search), 0); // todo
-}
-
-
-void 
-tracker_xesam_session_hits_modified (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint *hit_ids, gint hit_ids_length) 
-{
-	TrackerXesamSearch *proxy;
-
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-	g_return_if_fail (search == NULL || TRACKER_IS_SEARCH (search));
-
-	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
-
-	g_signal_emit (proxy, xesam_signals[XESAM_HITS_MODIFIED], 0, 
-		tracker_xesam_live_search_get_id (search), 0); // todo
-}
-
-
-void 
-tracker_xesam_session_search_done (TrackerXesamSession *self, TrackerXesamLiveSearch *search) 
-{
-	TrackerXesamSearch *proxy;
-
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-	g_return_if_fail (search == NULL || TRACKER_IS_SEARCH (search));
-
-	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
-
-	g_signal_emit (proxy, xesam_signals[XESAM_SEARCH_DONE], 0, 
-		tracker_xesam_live_search_get_id (search)); 
-}
-
-
-void 
-tracker_xesam_session_state_changed (TrackerXesamSession *self, gchar **state_info, gint state_info_length) 
-{
-	TrackerXesamSearch *proxy;
-
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-
-	proxy = TRACKER_XESAM_SEARCH (tracker_dbus_get_object (TRACKER_TYPE_XESAM_SEARCH));
-
-	g_signal_emit (proxy, xesam_signals[XESAM_STATE_CHANGED], 0, 0); // todo
-}
-
-
-void 
-tracker_xesam_session_set_property (TrackerXesamSession *self, const gchar *prop, const gchar *val) 
-{
-	g_return_if_fail (TRACKER_IS_SESSION (self));
-}
-
-
-gchar* 
-tracker_xesam_session_get_property (TrackerXesamSession *self, const gchar *prop) 
-{
-	g_return_val_if_fail (TRACKER_IS_SESSION (self), NULL);
-	return g_strdup ("");
-}
 
 
+/**
+ * tracker_xesam_session_set_property:
+ * @self: A #TrackerXesamSession
+ * @prop: The name or the property to set, see the list of session properties 
+ * for valid property names at http://xesam.org/main/XesamSearchAPI#properties
+ * @val: The value to set the property to
+ * @new_val: (out) (caller-owns): The actual value the search engine will use. 
+ * As noted above it is  not guaranteed that the requested value will be 
+ * respected
+ * 
+ * Set a property on the session. It is not guaranteed that the session property 
+ * will actually be used, the return value is the property value that will be 
+ * used. Search engines must respect the default property values however. For a 
+ * list of properties and descriptions see below.
+ * 
+ * Calling this method after the first search has been created with 
+ * @tracker_xesam_session_create_search is illegal. The server will raise an 
+ * error if you do. Ie. once you create the first search the properties are set
+ * in stone for the parent session. The search engine will also throw an error 
+ * if the session handle has been closed or is invalid.
+ * 
+ * An error will also be thrown if the prop parameter is not a valid session 
+ * property, if it is a property marked as read-only, or if the requested value 
+ * is invalid.
+ **/
+void 
+tracker_xesam_session_set_property (TrackerXesamSession *self, const gchar *prop, const gchar *val, gchar **new_val) 
+{
+	g_return_if_fail (TRACKER_IS_SESSION (self));
+	if (new_val)
+		*new_val = g_strdup (val);
+}
+
+
+
+/**
+ * tracker_xesam_session_get_property:
+ * @self: A #TrackerXesamSession
+ * @prop: The name or the property to set, see the list of session properties 
+ * for valid property names at http://xesam.org/main/XesamSearchAPI#properties
+ * @value: (out) (caller-owns): The value of a session property
+ * 
+ * Get the value of a session property. The server should throw an error if the 
+ * session handle is closed or does not exist. An error should also be raised if
+ * prop is not a valid session property.
+ **/
+void
+tracker_xesam_session_get_property (TrackerXesamSession *self, const gchar *prop, gchar **value) 
+{
+	g_return_if_fail (TRACKER_IS_SESSION (self));
+	if (value)
+		*value = g_strdup ("");
+	return;
+}
+
+
+
+/**
+ * tracker_xesam_session_create_search:
+ * @self: A #TrackerXesamSession
+ * @query_xml: A string in the xesam query language
+ * @search_id: (out) (caller-owns): An opaque handle for the Search object 
+ * @error: (null-ok) (out): a #GError
+ *
+ * Create a new search from @query_xml. If there are errors parsing the 
+ * @query_xml parameter an error will be set in @error.
+ * 
+ * Notifications of hits can be obtained by listening to the @hits-added signal. 
+ * Signals will not be emitted before a call to @tracker_xesam_live_search_activate
+ * has been made. 
+ *
+ * @returns: (caller-owns): a new non-activated #TrackerXesamLiveSearch
+ **/
 TrackerXesamLiveSearch* 
-tracker_xesam_session_create_search (TrackerXesamSession *self, const gchar *query_xml, gchar **search_id) 
+tracker_xesam_session_create_search (TrackerXesamSession *self, const gchar *query_xml, gchar **search_id, GError **error) 
 {
 	TrackerXesamLiveSearch *search;
 	TrackerXesamSessionPriv *priv = self->priv;
 
 	g_return_val_if_fail (TRACKER_IS_SESSION (self), NULL);
 
+	// todo: parse the query and pass the parsed query or error
+
 	search = tracker_xesam_live_search_new (query_xml);
 	tracker_xesam_live_search_set_id (search, tracker_unique_key ());
 
@@ -192,14 +207,17 @@
 	return search;
 }
 
-void 
-tracker_xesam_session_close_search (TrackerXesamSession *self, TrackerXesamLiveSearch *search)
-{
-	TrackerXesamSessionPriv *priv = self->priv;
-	g_hash_table_remove (priv->searches, 
-		tracker_xesam_live_search_get_id (search));
-}
 
+/**
+ * tracker_xesam_session_get_search:
+ * @self: A #TrackerXesamSession
+ * @search_id: (in): An opaque handle for the Search object 
+ * @error: (null-ok) (out): a #GError
+ *
+ * Get the #TrackerXesamLiveSearch identified by @search_id in @self.
+ *
+ * @returns: (null-ok) (caller-owns): a #TrackerXesamLiveSearch or NULL
+ **/
 TrackerXesamLiveSearch* 
 tracker_xesam_session_get_search (TrackerXesamSession *self, const gchar *search_id, GError **error)
 {
@@ -210,6 +228,13 @@
 	return search;
 }
 
+/**
+ * tracker_xesam_session_new:
+ *
+ * Create a new #TrackerXesamSession
+ *
+ * @returns: (caller-owns): a new #TrackerXesamSession
+ **/
 TrackerXesamSession* 
 tracker_xesam_session_new (void) 
 {

Modified: branches/xesam-support/src/trackerd/tracker-xesam-session.h
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam-session.h	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam-session.h	Thu Apr 24 11:41:08 2008
@@ -53,19 +53,13 @@
 	GObjectClass parent_class;
 };
 
-void tracker_xesam_session_hits_added (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint count);
-void tracker_xesam_session_hits_removed (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint *hit_ids, gint hit_ids_length);
-void tracker_xesam_session_hits_modified (TrackerXesamSession *self, TrackerXesamLiveSearch *search, guint *hit_ids, gint hit_ids_length);
-void tracker_xesam_session_search_done (TrackerXesamSession *self, TrackerXesamLiveSearch *search);
-void tracker_xesam_session_state_changed (TrackerXesamSession *self, gchar **state_info, gint state_info_length);
-void tracker_xesam_session_set_property (TrackerXesamSession *self, const gchar *prop, const gchar* val);
-char* tracker_xesam_session_get_property (TrackerXesamSession *self, const gchar *prop);
-TrackerXesamLiveSearch* tracker_xesam_session_create_search (TrackerXesamSession *self, const gchar *query_xml , gchar **search_id);
+void tracker_xesam_session_set_property (TrackerXesamSession *self, const gchar *prop, const gchar *val, gchar **new_val);
+void tracker_xesam_session_get_property (TrackerXesamSession *self, const gchar *prop, gchar **value);
+TrackerXesamLiveSearch* tracker_xesam_session_create_search (TrackerXesamSession *self, const gchar *query_xml , gchar **search_id, GError **error);
 TrackerXesamLiveSearch* tracker_xesam_session_get_search (TrackerXesamSession *self, const gchar *search_id, GError **error);
 GList *tracker_xesam_session_get_searches (TrackerXesamSession *self);
 void tracker_xesam_session_set_id (TrackerXesamSession *self, const gchar *session_id);
 const gchar* tracker_xesam_session_get_id (TrackerXesamSession *self);
-void tracker_xesam_session_close_search (TrackerXesamSession *self, TrackerXesamLiveSearch *search);
 
 TrackerXesamSession* tracker_xesam_session_new (void);
 GType tracker_xesam_session_get_type (void);

Modified: branches/xesam-support/src/trackerd/tracker-xesam.h
==============================================================================
--- branches/xesam-support/src/trackerd/tracker-xesam.h	(original)
+++ branches/xesam-support/src/trackerd/tracker-xesam.h	Thu Apr 24 11:41:08 2008
@@ -28,7 +28,7 @@
 
 TrackerXesamSession* tracker_xesam_get_session (const gchar *session_id, GError **error);
 TrackerXesamSession* tracker_xesam_get_session_for_search (const gchar *search_id, TrackerXesamLiveSearch **search_in, GError **error);
-TrackerXesamLiveSearch* tracker_xesam_get_live_search  (const gchar *search_id, GError **error);
+TrackerXesamLiveSearch* tracker_xesam_get_live_search (const gchar *search_id, GError **error);
 TrackerXesamSession* tracker_xesam_create_session (TrackerXesamSearch *dbus_proxy, gchar **session_id, GError **error);
 void tracker_xesam_close_session (const gchar *session_id, GError **error);