[evolution-data-server/dbus: 33/33] Add documentation to e-data-book-view and resync

[Ross Burton <rburton src gnome org>]

commit 562a0a22810061b53a68c488074705503f49f41e
Author: Ross Burton <ross linux intel com>
Date:   Mon Jun 1 16:09:50 2009 +0100

    Add documentation to e-data-book-view and resync
---
 addressbook/libedata-book/e-data-book-view.c |  497 ++++++++++++++++----------
 addressbook/libedata-book/e-data-book-view.h |   49 ++--
 2 files changed, 325 insertions(+), 221 deletions(-)

diff --git a/addressbook/libedata-book/e-data-book-view.c b/addressbook/libedata-book/e-data-book-view.c
index 48a4080..6eb5d60 100644
--- a/addressbook/libedata-book/e-data-book-view.c
+++ b/addressbook/libedata-book/e-data-book-view.c
@@ -159,180 +159,6 @@ book_destroyed_cb (gpointer data, GObject *dead)
 	}
 }
 
-/**
- * e_data_book_view_new:
- * @book: The #EDataBook to search
- * @path: The object path that this book view should have
- * @card_query: The query as a string
- * @card_sexp: The query as an #EBookBackendSExp
- * @max_results: The maximum number of results to return
- *
- * Create a new #EDataBookView for the given #EBook, filtering on #card_sexp,
- * and place it on DBus at the object path #path.
- */
-EDataBookView *
-e_data_book_view_new (EDataBook *book, const char *path, const char *card_query, EBookBackendSExp *card_sexp, int max_results)
-{
-	EDataBookView *view;
-	EDataBookViewPrivate *priv;
-
-	view = g_object_new (E_TYPE_DATA_BOOK_VIEW, NULL);
-	priv = view->priv;
-
-	priv->book = book;
-	/* Attach a weak reference to the book, so if it dies the book view is destroyed too */
-	g_object_weak_ref (G_OBJECT (priv->book), book_destroyed_cb, view);
-	priv->backend = g_object_ref (e_data_book_get_backend (book));
-	priv->card_query = g_strdup (card_query);
-	priv->card_sexp = card_sexp;
-	priv->max_results = max_results;
-
-	dbus_g_connection_register_g_object (connection, path, G_OBJECT (view));
-
-	return view;
-}
-
-static void
-e_data_book_view_dispose (GObject *object)
-{
-	EDataBookView *book_view = E_DATA_BOOK_VIEW (object);
-	EDataBookViewPrivate *priv = book_view->priv;
-
-	if (priv->book) {
-		/* Remove the weak reference */
-		g_object_weak_unref (G_OBJECT (priv->book), book_destroyed_cb, book_view);
-		priv->book = NULL;
-	}
-
-	if (priv->backend) {
-		e_book_backend_remove_book_view (priv->backend, book_view);
-		g_object_unref (priv->backend);
-		priv->backend = NULL;
-	}
-
-	if (priv->card_sexp) {
-		g_object_unref (priv->card_sexp);
-		priv->card_sexp = NULL;
-	}
-
-	if (priv->idle_id) {
-		g_source_remove (priv->idle_id);
-		priv->idle_id = 0;
-	}
-
-	G_OBJECT_CLASS (e_data_book_view_parent_class)->dispose (object);
-}
-
-static void
-e_data_book_view_finalize (GObject *object)
-{
-	EDataBookView *book_view = E_DATA_BOOK_VIEW (object);
-	EDataBookViewPrivate *priv = book_view->priv;
-
-	reset_array (priv->adds);
-	reset_array (priv->changes);
-	reset_array (priv->removes);
-	g_array_free (priv->adds, TRUE);
-	g_array_free (priv->changes, TRUE);
-	g_array_free (priv->removes, TRUE);
-
-	g_free (priv->card_query);
-
-	g_mutex_free (priv->pending_mutex);
-
-	g_hash_table_destroy (priv->ids);
-
-	G_OBJECT_CLASS (e_data_book_view_parent_class)->finalize (object);
-}
-
-static gboolean
-bookview_idle_start (gpointer data)
-{
-	EDataBookView *book_view = data;
-
-	book_view->priv->running = TRUE;
-	book_view->priv->idle_id = 0;
-
-	e_book_backend_start_book_view (book_view->priv->backend, book_view);
-	return FALSE;
-}
-
-static gboolean
-impl_BookView_start (EDataBookView *book_view, GError **error)
-{
-	book_view->priv->idle_id = g_idle_add (bookview_idle_start, book_view);
-	return TRUE;
-}
-
-static gboolean
-bookview_idle_stop (gpointer data)
-{
-	EDataBookView *book_view = data;
-
-	e_book_backend_stop_book_view (book_view->priv->backend, book_view);
-
-	book_view->priv->running = FALSE;
-	book_view->priv->idle_id = 0;
-
-	return FALSE;
-}
-
-static gboolean
-impl_BookView_stop (EDataBookView *book_view, GError **error)
-{
-	if (book_view->priv->idle_id)
-		g_source_remove (book_view->priv->idle_id);
-
-	book_view->priv->idle_id = g_idle_add (bookview_idle_stop, book_view);
-	return TRUE;
-}
-
-static gboolean
-impl_BookView_dispose (EDataBookView *book_view, GError **eror)
-{
-	g_object_unref (book_view);
-
-	return TRUE;
-}
-
-void
-e_data_book_view_set_thresholds (EDataBookView *book_view,
-                                 int minimum_grouping_threshold,
-                                 int maximum_grouping_threshold)
-{
-	g_return_if_fail (E_IS_DATA_BOOK_VIEW (book_view));
-
-	g_debug ("e_data_book_view_set_thresholds does nothing in eds-dbus");
-}
-
-const char*
-e_data_book_view_get_card_query (EDataBookView *book_view)
-{
-	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
-	return book_view->priv->card_query;
-}
-
-EBookBackendSExp*
-e_data_book_view_get_card_sexp (EDataBookView *book_view)
-{
-	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
-	return book_view->priv->card_sexp;
-}
-
-int
-e_data_book_view_get_max_results (EDataBookView *book_view)
-{
-	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), 0);
-	return book_view->priv->max_results;
-}
-
-EBookBackend*
-e_data_book_view_get_backend (EDataBookView *book_view)
-{
-	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
-	return book_view->priv->backend;
-}
-
 static void
 send_pending_adds (EDataBookView *view)
 {
@@ -375,7 +201,7 @@ notify_change (EDataBookView *view, char *vcard)
 	EDataBookViewPrivate *priv = view->priv;
 	send_pending_adds (view);
 	send_pending_removes (view);
-
+  
 	g_array_append_val (priv->changes, vcard);
 }
 
@@ -406,6 +232,34 @@ notify_add (EDataBookView *view, const char *id, char *vcard)
 			     GUINT_TO_POINTER (1));
 }
 
+static void
+reset_array (GArray *array)
+{
+	gint i = 0;
+	gchar *tmp = NULL;
+
+	/* Free stored strings */
+	for (i = 0; i < array->len; i++)
+		{
+			tmp = g_array_index (array, gchar *, i);
+			g_free (tmp);
+		}
+
+	/* Force the array size to 0 */
+	g_array_set_size (array, 0);
+}
+
+/**
+ * e_data_book_view_notify_update:
+ * @book_view: an #EDataBookView
+ * @contact: an #EContact
+ *
+ * Notify listeners that @contact has changed. This can
+ * trigger an add, change or removal event depending on
+ * whether the change causes the contact to start matching,
+ * no longer match, or stay matching the query specified
+ * by @book_view.
+ **/
 void
 e_data_book_view_notify_update (EDataBookView *book_view, EContact *contact)
 {
@@ -443,6 +297,19 @@ e_data_book_view_notify_update (EDataBookView *book_view, EContact *contact)
 	g_mutex_unlock (priv->pending_mutex);
 }
 
+/**
+ * e_data_book_view_notify_update_vcard:
+ * @book_view: an #EDataBookView
+ * @vcard: a plain vCard
+ *
+ * Notify listeners that @vcard has changed. This can
+ * trigger an add, change or removal event depending on
+ * whether the change causes the contact to start matching,
+ * no longer match, or stay matching the query specified
+ * by @book_view.  This method should be preferred over
+ * #e_data_book_view_notify_update when the native
+ * representation of a contact is a vCard.
+ **/
 void
 e_data_book_view_notify_update_vcard (EDataBookView *book_view, char *vcard)
 {
@@ -481,6 +348,26 @@ e_data_book_view_notify_update_vcard (EDataBookView *book_view, char *vcard)
 	g_mutex_unlock (priv->pending_mutex);
 }
 
+/**
+ * e_data_book_view_notify_update_prefiltered_vcard:
+ * @book_view: an #EDataBookView
+ * @id: the UID of this contact
+ * @vcard: a plain vCard
+ *
+ * Notify listeners that @vcard has changed. This can
+ * trigger an add, change or removal event depending on
+ * whether the change causes the contact to start matching,
+ * no longer match, or stay matching the query specified
+ * by @book_view.  This method should be preferred over
+ * #e_data_book_view_notify_update when the native
+ * representation of a contact is a vCard.
+ *
+ * The important difference between this method and
+ * #e_data_book_view_notify_update and #e_data_book_view_notify_update_vcard is
+ * that it doesn't match the contact against the book view query to see if it
+ * should be included, it assumes that this has been done and the contact is
+ * known to exist in the view.
+ **/
 void
 e_data_book_view_notify_update_prefiltered_vcard (EDataBookView *book_view, const char *id, char *vcard)
 {
@@ -503,6 +390,14 @@ e_data_book_view_notify_update_prefiltered_vcard (EDataBookView *book_view, cons
 	g_mutex_unlock (priv->pending_mutex);
 }
 
+/**
+ * e_data_book_view_notify_remove:
+ * @book_view: an #EDataBookView
+ * @id: a unique contact ID
+ *
+ * Notify listeners that a contact specified by @id
+ * was removed from @book_view.
+ **/
 void
 e_data_book_view_notify_remove (EDataBookView *book_view, const char *id)
 {
@@ -519,6 +414,15 @@ e_data_book_view_notify_remove (EDataBookView *book_view, const char *id)
 	g_mutex_unlock (priv->pending_mutex);
 }
 
+/**
+ * e_data_book_view_notify_complete:
+ * @book_view: an #EDataBookView
+ * @status: the status of the query
+ *
+ * Notifies listeners that all pending updates on @book_view
+ * have been sent. The listener's information should now be
+ * in sync with the backend's.
+ **/
 void
 e_data_book_view_notify_complete (EDataBookView *book_view, EDataBookStatus status)
 {
@@ -541,6 +445,15 @@ e_data_book_view_notify_complete (EDataBookView *book_view, EDataBookStatus stat
 	g_signal_emit (book_view, signals[COMPLETE], 0, status);
 }
 
+/**
+ * e_data_book_view_notify_status_message:
+ * @book_view: an #EDataBookView
+ * @message: a text message
+ *
+ * Provides listeners with a human-readable text describing the
+ * current backend operation. This can be used for progress
+ * reporting.
+ **/
 void
 e_data_book_view_notify_status_message (EDataBookView *book_view, const char *message)
 {
@@ -553,6 +466,215 @@ e_data_book_view_notify_status_message (EDataBookView *book_view, const char *me
 }
 
 /**
+ * e_data_book_view_new:
+ * @book: The #EDataBook to search
+ * @path: The object path that this book view should have
+ * @card_query: The query as a string
+ * @card_sexp: The query as an #EBookBackendSExp
+ * @max_results: The maximum number of results to return
+ *
+ * Create a new #EDataBookView for the given #EBook, filtering on #card_sexp,
+ * and place it on DBus at the object path #path.
+ */
+EDataBookView *
+e_data_book_view_new (EDataBook *book, const char *path, const char *card_query, EBookBackendSExp *card_sexp, int max_results)
+{
+	EDataBookView *view;
+	EDataBookViewPrivate *priv;
+
+	view = g_object_new (E_TYPE_DATA_BOOK_VIEW, NULL);
+	priv = view->priv;
+
+	priv->book = book;
+	/* Attach a weak reference to the book, so if it dies the book view is destroyed too */
+	g_object_weak_ref (G_OBJECT (priv->book), book_destroyed_cb, view);
+	priv->backend = g_object_ref (e_data_book_get_backend (book));
+	priv->card_query = g_strdup (card_query);
+	priv->card_sexp = card_sexp;
+	priv->max_results = max_results;
+
+	dbus_g_connection_register_g_object (connection, path, G_OBJECT (view));
+
+	return view;
+}
+
+static void
+e_data_book_view_dispose (GObject *object)
+{
+	EDataBookView *book_view = E_DATA_BOOK_VIEW (object);
+	EDataBookViewPrivate *priv = book_view->priv;
+
+	if (priv->book) {
+		/* Remove the weak reference */
+		g_object_weak_unref (G_OBJECT (priv->book), book_destroyed_cb, book_view);
+		priv->book = NULL;
+	}
+
+	if (priv->backend) {
+		e_book_backend_remove_book_view (priv->backend, book_view);
+		g_object_unref (priv->backend);
+		priv->backend = NULL;
+	}
+
+	if (priv->card_sexp) {
+		g_object_unref (priv->card_sexp);
+		priv->card_sexp = NULL;
+	}
+
+	if (priv->idle_id) {
+		g_source_remove (priv->idle_id);
+		priv->idle_id = 0;
+	}
+
+	G_OBJECT_CLASS (e_data_book_view_parent_class)->dispose (object);
+}
+
+static void
+e_data_book_view_finalize (GObject *object)
+{
+	EDataBookView *book_view = E_DATA_BOOK_VIEW (object);
+	EDataBookViewPrivate *priv = book_view->priv;
+
+	reset_array (priv->adds);
+	reset_array (priv->changes);
+	reset_array (priv->removes);
+	g_array_free (priv->adds, TRUE);
+	g_array_free (priv->changes, TRUE);
+	g_array_free (priv->removes, TRUE);
+
+	g_free (priv->card_query);
+
+	g_mutex_free (priv->pending_mutex);
+
+	g_hash_table_destroy (priv->ids);
+
+	G_OBJECT_CLASS (e_data_book_view_parent_class)->finalize (object);
+}
+
+static gboolean
+bookview_idle_start (gpointer data)
+{
+	EDataBookView *book_view = data;
+
+	book_view->priv->running = TRUE;
+	book_view->priv->idle_id = 0;
+
+	e_book_backend_start_book_view (book_view->priv->backend, book_view);
+	return FALSE;
+}
+
+static gboolean
+impl_BookView_start (EDataBookView *book_view, GError **error)
+{
+	book_view->priv->idle_id = g_idle_add (bookview_idle_start, book_view);
+	return TRUE;
+}
+
+static gboolean
+bookview_idle_stop (gpointer data)
+{
+	EDataBookView *book_view = data;
+
+	e_book_backend_stop_book_view (book_view->priv->backend, book_view);
+
+	book_view->priv->running = FALSE;
+	book_view->priv->idle_id = 0;
+
+	return FALSE;
+}
+
+static gboolean
+impl_BookView_stop (EDataBookView *book_view, GError **error)
+{
+	if (book_view->priv->idle_id)
+		g_source_remove (book_view->priv->idle_id);
+
+	book_view->priv->idle_id = g_idle_add (bookview_idle_stop, book_view);
+	return TRUE;
+}
+
+static gboolean
+impl_BookView_dispose (EDataBookView *book_view, GError **eror)
+{
+	g_object_unref (book_view);
+
+	return TRUE;
+}
+
+void
+e_data_book_view_set_thresholds (EDataBookView *book_view,
+                                 int minimum_grouping_threshold,
+                                 int maximum_grouping_threshold)
+{
+	g_return_if_fail (E_IS_DATA_BOOK_VIEW (book_view));
+
+	g_debug ("e_data_book_view_set_thresholds does nothing in eds-dbus");
+}
+
+/**
+ * e_data_book_view_get_card_query:
+ * @book_view: an #EDataBookView
+ *
+ * Gets the text representation of the s-expression used
+ * for matching contacts to @book_view.
+ *
+ * Return value: The textual s-expression used.
+ **/
+const char*
+e_data_book_view_get_card_query (EDataBookView *book_view)
+{
+	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
+	return book_view->priv->card_query;
+}
+
+/**
+ * e_data_book_view_get_card_sexp:
+ * @book_view: an #EDataBookView
+ *
+ * Gets the s-expression used for matching contacts to
+ * @book_view.
+ *
+ * Return value: The #EBookBackendSExp used.
+ **/
+EBookBackendSExp*
+e_data_book_view_get_card_sexp (EDataBookView *book_view)
+{
+	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
+	return book_view->priv->card_sexp;
+}
+
+/**
+ * e_data_book_view_get_max_results:
+ * @book_view: an #EDataBookView
+ *
+ * Gets the maximum number of results returned by
+ * @book_view's query.
+ *
+ * Return value: The maximum number of results returned.
+ **/
+int
+e_data_book_view_get_max_results (EDataBookView *book_view)
+{
+	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), 0);
+	return book_view->priv->max_results;
+}
+
+/**
+ * e_data_book_view_get_backend:
+ * @book_view: an #EDataBookView
+ *
+ * Gets the backend that @book_view is querying.
+ *
+ * Return value: The associated #EBookBackend.
+ **/
+EBookBackend*
+e_data_book_view_get_backend (EDataBookView *book_view)
+{
+	g_return_val_if_fail (E_IS_DATA_BOOK_VIEW (book_view), NULL);
+	return book_view->priv->backend;
+}
+
+/**
  * e_data_book_view_ref
  * @book_view: an #EBookView
  *
@@ -560,9 +682,9 @@ e_data_book_view_notify_status_message (EDataBookView *book_view, const char *me
  * the transition from Bonobo to DBUS.
  */
 void
-e_data_book_view_ref (EDataBookView *view)
+e_data_book_view_ref (EDataBookView *book_view)
 {
-	g_object_ref (view);
+	g_object_ref (book_view);
 }
 
 /**
@@ -573,24 +695,7 @@ e_data_book_view_ref (EDataBookView *view)
  * the transition from Bonobo to DBUS.
  */
 void
-e_data_book_view_unref (EDataBookView *view)
+e_data_book_view_unref (EDataBookView *book_view)
 {
-	g_object_unref (view);
-}
-
-static void
-reset_array (GArray *array)
-{
-	gint i = 0;
-	gchar *tmp = NULL;
-
-	/* Free stored strings */
-	for (i = 0; i < array->len; i++)
-		{
-			tmp = g_array_index (array, gchar *, i);
-			g_free (tmp);
-		}
-
-	/* Force the array size to 0 */
-	g_array_set_size (array, 0);
+	g_object_unref (book_view);
 }
diff --git a/addressbook/libedata-book/e-data-book-view.h b/addressbook/libedata-book/e-data-book-view.h
index d0e8e23..a34436c 100644
--- a/addressbook/libedata-book/e-data-book-view.h
+++ b/addressbook/libedata-book/e-data-book-view.h
@@ -28,9 +28,9 @@
 #include <glib-object.h>
 #include <dbus/dbus-glib.h>
 #include <libebook/e-contact.h>
-#include "e-data-book-types.h"
-#include "e-book-backend.h"
-#include "e-book-backend-sexp.h"
+#include <libedata-book/e-data-book-types.h>
+#include <libedata-book/e-book-backend.h>
+#include <libedata-book/e-book-backend-sexp.h>
 
 G_BEGIN_DECLS
 
@@ -44,43 +44,42 @@ G_BEGIN_DECLS
 typedef struct _EDataBookViewPrivate EDataBookViewPrivate;
 
 struct _EDataBookView {
-  GObject parent;
-  EDataBookViewPrivate *priv;
+	GObject parent;
+	EDataBookViewPrivate *priv;
 };
 
 struct _EDataBookViewClass {
-  GObjectClass parent;
+	GObjectClass parent;
 };
 
-EDataBookView * e_data_book_view_new (EDataBook        *book,
-                                      const char       *path,
-                                      const char       *card_query,
-                                      EBookBackendSExp *card_sexp,
-                                      int               max_results);
+EDataBookView *e_data_book_view_new                  (EDataBook        *book,
+						      const char       *path,
+						      const char       *card_query,
+						      EBookBackendSExp *card_sexp,
+						      int               max_results);
 
 void              e_data_book_view_set_thresholds    (EDataBookView *book_view,
-                                                      int            minimum_grouping_threshold,
-                                                      int            maximum_grouping_threshold);
+						      int minimum_grouping_threshold,
+						      int maximum_grouping_threshold);
 
-const char *       e_data_book_view_get_card_query    (EDataBookView                *book_view);
-EBookBackendSExp * e_data_book_view_get_card_sexp     (EDataBookView                *book_view);
-int                e_data_book_view_get_max_results   (EDataBookView                *book_view);
-EBookBackend *     e_data_book_view_get_backend       (EDataBookView                *book_view);
-void               e_data_book_view_notify_update     (EDataBookView                *book_view,
-                                                      EContact                     *contact);
+const char*       e_data_book_view_get_card_query    (EDataBookView                *book_view);
+EBookBackendSExp* e_data_book_view_get_card_sexp     (EDataBookView                *book_view);
+int               e_data_book_view_get_max_results   (EDataBookView                *book_view);
+EBookBackend*     e_data_book_view_get_backend       (EDataBookView                *book_view);
+void         e_data_book_view_notify_update          (EDataBookView                *book_view,
+						      EContact                     *contact);
 
 void         e_data_book_view_notify_update_vcard    (EDataBookView                *book_view,
-                                                      char                         *vcard);
+						      char                         *vcard);
 void         e_data_book_view_notify_update_prefiltered_vcard (EDataBookView       *book_view,
                                                                const char          *id,
                                                                char                *vcard);
 void         e_data_book_view_notify_remove          (EDataBookView                *book_view,
-                                                      const char                   *id);
-void         e_data_book_view_notify_complete        (EDataBookView                *book_view, 
-                                                      EDataBookStatus               status);
+						      const char                   *id);
+void         e_data_book_view_notify_complete        (EDataBookView                *book_view,
+						      EDataBookStatus               status);
 void         e_data_book_view_notify_status_message  (EDataBookView                *book_view,
-                                                      const char                   *message);
-
+						      const char                   *message);
 void         e_data_book_view_ref                    (EDataBookView                *book_view);
 void         e_data_book_view_unref                  (EDataBookView                *book_view);