[evolution-data-server/dbus: 33/33] Add documentation to e-data-book-view and resync
- From: Ross Burton <rburton src gnome org>
- To: svn-commits-list gnome org
- Subject: [evolution-data-server/dbus: 33/33] Add documentation to e-data-book-view and resync
- Date: Mon, 1 Jun 2009 11:15:27 -0400 (EDT)
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);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]