[evolution-data-server/openismus-work-master: 70/73] Added EBookClientCursor
- From: Tristan Van Berkom <tvb src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [evolution-data-server/openismus-work-master: 70/73] Added EBookClientCursor
- Date: Thu, 4 Jul 2013 19:16:56 +0000 (UTC)
commit 9fa5d734bd926ed274b4a55022f520c33f362db8
Author: Tristan Van Berkom <tristanvb openismus com>
Date: Tue Jul 2 17:47:34 2013 +0900
Added EBookClientCursor
The user facing cursor API, deals with calling cursor APIs in DRA mode
and normal modes over D-Bus, handles threading situations, and notifies
of cursor state changes in the caller's main context.
addressbook/libebook/Makefile.am | 2 +
addressbook/libebook/e-book-client-cursor.c | 1832 +++++++++++++++++++++++++++
addressbook/libebook/e-book-client-cursor.h | 130 ++
3 files changed, 1964 insertions(+), 0 deletions(-)
---
diff --git a/addressbook/libebook/Makefile.am b/addressbook/libebook/Makefile.am
index 9fe5ef4..724b38a 100644
--- a/addressbook/libebook/Makefile.am
+++ b/addressbook/libebook/Makefile.am
@@ -41,6 +41,7 @@ libebook_1_2_la_CPPFLAGS = \
libebook_1_2_la_SOURCES = \
$(ENUM_GENERATED) \
e-book-client.c \
+ e-book-client-cursor.c \
e-book-client-view.c \
e-book-view-private.h \
e-book-view.c \
@@ -69,6 +70,7 @@ libebookincludedir = $(privincludedir)/libebook
libebookinclude_HEADERS = \
libebook.h \
e-book-client.h \
+ e-book-client-cursor.h \
e-book-client-view.h \
e-book-enumtypes.h \
e-book-view.h \
diff --git a/addressbook/libebook/e-book-client-cursor.c b/addressbook/libebook/e-book-client-cursor.c
new file mode 100644
index 0000000..2ac57bd
--- /dev/null
+++ b/addressbook/libebook/e-book-client-cursor.c
@@ -0,0 +1,1832 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*
+ * Copyright (C) 2013 Intel Corporation
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ * Author: Tristan Van Berkom <tristanvb openismus com>
+ */
+
+#ifdef HAVE_CONFIG_H
+#include <config.h>
+#endif
+
+#include <glib/gi18n-lib.h>
+
+#include <libedataserver/libedataserver.h>
+#include <libedata-book/libedata-book.h>
+
+/* Private D-Bus class. */
+#include <e-dbus-address-book-cursor.h>
+
+#include "e-book-client.h"
+#include "e-book-client-cursor.h"
+
+/* Forward declarations */
+typedef struct _SetSexpContext SetSexpContext;
+typedef struct _MoveByContext MoveByContext;
+typedef struct _AlphabetIndexContext AlphabetIndexContext;
+typedef enum _NotificationType NotificationType;
+typedef struct _Notification Notification;
+
+/* GObjectClass */
+static void book_client_cursor_dispose (GObject *object);
+static void book_client_cursor_finalize (GObject *object);
+static void book_client_cursor_set_property (GObject *object,
+ guint property_id,
+ const GValue *value,
+ GParamSpec *pspec);
+static void book_client_cursor_get_property (GObject *object,
+ guint property_id,
+ GValue *value,
+ GParamSpec *pspec);
+
+/* GInitable */
+static void e_book_client_cursor_initable_init (GInitableIface *interface);
+static gboolean book_client_cursor_initable_init (GInitable *initable,
+ GCancellable *cancellable,
+ GError **error);
+
+/* Private mutators */
+static void book_client_cursor_set_client (EBookClientCursor *cursor,
+ EBookClient *client);
+static void book_client_cursor_set_context (EBookClientCursor *cursor,
+ GMainContext *context);
+static GMainContext *book_client_cursor_ref_context (EBookClientCursor *cursor);
+static void book_client_cursor_set_proxy (EBookClientCursor *cursor,
+ EDBusAddressBookCursor *proxy);
+static void book_client_cursor_set_connection (EBookClientCursor *cursor,
+ GDBusConnection *connection);
+static void book_client_cursor_set_direct_cursor (EBookClientCursor *cursor,
+ EDataBookCursor *direct_cursor);
+static void book_client_cursor_set_object_path (EBookClientCursor *cursor,
+ const gchar *object_path);
+static void book_client_cursor_set_locale (EBookClientCursor *cursor,
+ const gchar *locale);
+static void book_client_cursor_set_revision (EBookClientCursor *cursor,
+ const gchar *revision);
+static void book_client_cursor_set_total (EBookClientCursor *cursor,
+ gint total);
+static void book_client_cursor_set_position (EBookClientCursor *cursor,
+ gint position);
+
+/* Notifications from other threads */
+static void notification_new_string (EBookClientCursor *cursor,
+ NotificationType type,
+ const gchar *value);
+static void notification_new_int (EBookClientCursor *cursor,
+ NotificationType type,
+ gint value);
+static void notification_free (Notification *notification);
+static void notification_queue (EBookClientCursor *cursor,
+ Notification *notification);
+static gboolean notification_dispatch (Notification *notification);
+
+/* Callbacks from EBookClient */
+static void client_revision_changed_cb (EClient *client,
+ const gchar *prop_name,
+ const gchar *prop_value,
+ GWeakRef *weak_ref);
+static void client_locale_changed_cb (EBookClient *book_client,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref);
+
+/* Callbacks from EDBusAddressBookCursor */
+static void proxy_total_changed_cb (EDBusAddressBookCursor *proxy,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref);
+static void proxy_position_changed_cb (EDBusAddressBookCursor *proxy,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref);
+
+/* Callbacks from EDataBookCursor */
+static void dra_total_changed_cb (EDataBookCursor *direct_cursor,
+ GParamSpec *pspec,
+ EBookClientCursor *cursor);
+static void dra_position_changed_cb (EDataBookCursor *direct_cursor,
+ GParamSpec *pspec,
+ EBookClientCursor *cursor);
+
+/* Threaded method call contexts */
+static SetSexpContext *set_sexp_context_new (const gchar *sexp);
+static void set_sexp_context_free (SetSexpContext *context);
+static void set_sexp_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable);
+static MoveByContext *move_by_context_new (EBookCursorOrigin origin,
+ gint count,
+ gboolean fetch_results);
+static void move_by_context_free (MoveByContext *context);
+static void move_by_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable);
+static AlphabetIndexContext *alphabet_index_context_new (gint index,
+ const gchar *locale);
+static void alphabet_index_context_free (AlphabetIndexContext *context);
+static void alphabet_index_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable);
+
+struct _EBookClientCursorPrivate {
+
+ /* Weak reference to the EBookClient and
+ * to the GMainContext in which notifications
+ * should be delivered to the EBookClientCursor user */
+ GWeakRef client;
+ GMainContext *main_context;
+ GMutex main_context_lock;
+
+ /* Connection with the addressbook cursor over D-Bus */
+ EDBusAddressBookCursor *dbus_proxy;
+ GDBusConnection *connection;
+ gchar *object_path;
+
+ /* Direct Read Access to the addressbook cursor */
+ EDataBookCursor *direct_cursor;
+
+ /* Signal connection ids */
+ gulong revision_changed_id;
+ gulong locale_changed_id;
+ gulong proxy_total_changed_id;
+ gulong proxy_position_changed_id;
+ gulong dra_total_changed_id;
+ gulong dra_position_changed_id;
+
+ /* Keep a handle on the current locale according
+ * to the EBookClient, this is also how we
+ * derive the active alphabet
+ */
+ gchar *locale;
+
+ /* Keep a handle on the revision, we need to
+ * hold on to the currently known revision for
+ * DRA mode cursors. Also we trigger the
+ * refresh signal in normal mode whenever the
+ * revision changes
+ */
+ gchar *revision;
+
+ /* Keep a handle on our property values */
+ gchar **alphabet;
+ gint n_labels;
+ gint underflow;
+ gint inflow;
+ gint overflow;
+
+ /* Client side positional values */
+ gint position;
+ gint total;
+};
+
+enum {
+ PROP_0,
+ PROP_CLIENT,
+ PROP_CONTEXT,
+ PROP_CONNECTION,
+ PROP_DIRECT_CURSOR,
+ PROP_OBJECT_PATH,
+ PROP_ALPHABET,
+ PROP_TOTAL,
+ PROP_POSITION,
+};
+
+enum {
+ REFRESH,
+ LAST_SIGNAL
+};
+
+static guint signals[LAST_SIGNAL];
+
+G_DEFINE_TYPE_WITH_CODE (
+ EBookClientCursor,
+ e_book_client_cursor,
+ G_TYPE_OBJECT,
+ G_IMPLEMENT_INTERFACE (
+ G_TYPE_INITABLE,
+ e_book_client_cursor_initable_init))
+
+/****************************************************
+ * GObjectClass *
+ ****************************************************/
+static void
+e_book_client_cursor_class_init (EBookClientCursorClass *class)
+{
+ GObjectClass *object_class;
+
+ object_class = G_OBJECT_CLASS (class);
+ object_class->dispose = book_client_cursor_dispose;
+ object_class->finalize = book_client_cursor_finalize;
+ object_class->set_property = book_client_cursor_set_property;
+ object_class->get_property = book_client_cursor_get_property;
+
+ g_object_class_install_property (
+ object_class,
+ PROP_CLIENT,
+ g_param_spec_object (
+ "client",
+ "Client",
+ "The EBookClient for the cursor",
+ E_TYPE_BOOK_CLIENT,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_CONTEXT,
+ g_param_spec_boxed (
+ "context",
+ "Context",
+ "The GMainContext in which this cursor was created",
+ G_TYPE_MAIN_CONTEXT,
+ G_PARAM_WRITABLE |
+ G_PARAM_CONSTRUCT_ONLY));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_CONNECTION,
+ g_param_spec_object (
+ "connection",
+ "Connection",
+ "The GDBusConnection used "
+ "to create the D-Bus proxy",
+ G_TYPE_DBUS_CONNECTION,
+ G_PARAM_WRITABLE |
+ G_PARAM_CONSTRUCT_ONLY));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_DIRECT_CURSOR,
+ g_param_spec_object (
+ "direct-cursor",
+ "Direct Cursor",
+ "The EDataBookCursor for direct read access",
+ E_TYPE_DATA_BOOK_CURSOR,
+ G_PARAM_WRITABLE |
+ G_PARAM_CONSTRUCT_ONLY));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_OBJECT_PATH,
+ g_param_spec_string (
+ "object-path",
+ "Object Path",
+ "The object path used "
+ "to create the D-Bus proxy",
+ NULL,
+ G_PARAM_WRITABLE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_ALPHABET,
+ g_param_spec_boxed (
+ "alphabet",
+ "Alphabet",
+ "The active alphabet",
+ G_TYPE_STRV,
+ G_PARAM_READABLE |
+ G_PARAM_STATIC_STRINGS));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_TOTAL,
+ g_param_spec_int (
+ "total",
+ "Total",
+ "The total contacts for this cursor's query",
+ 0, G_MAXINT, 0,
+ G_PARAM_READABLE));
+
+ g_object_class_install_property (
+ object_class,
+ PROP_POSITION,
+ g_param_spec_int (
+ "position",
+ "Position",
+ "The current cursor position",
+ 0, G_MAXINT, 0,
+ G_PARAM_READABLE));
+
+ signals[REFRESH] = g_signal_new (
+ "refresh",
+ G_OBJECT_CLASS_TYPE (object_class),
+ G_SIGNAL_RUN_LAST,
+ G_STRUCT_OFFSET (EBookClientCursorClass, refresh),
+ NULL, NULL, NULL,
+ G_TYPE_NONE, 0);
+
+ g_type_class_add_private (class, sizeof (EBookClientCursorPrivate));
+}
+
+static void
+e_book_client_cursor_init (EBookClientCursor *cursor)
+{
+ cursor->priv =
+ G_TYPE_INSTANCE_GET_PRIVATE (cursor,
+ E_TYPE_BOOK_CLIENT_CURSOR,
+ EBookClientCursorPrivate);
+ g_mutex_init (&cursor->priv->main_context_lock);
+}
+
+static void
+book_client_cursor_dispose (GObject *object)
+{
+ EBookClientCursor *cursor = E_BOOK_CLIENT_CURSOR (object);
+
+ book_client_cursor_set_client (cursor, NULL);
+ book_client_cursor_set_proxy (cursor, NULL);
+ book_client_cursor_set_direct_cursor (cursor, NULL);
+ book_client_cursor_set_connection (cursor, NULL);
+ book_client_cursor_set_context (cursor, NULL);
+
+ /* Chain up to parent's dispose() method. */
+ G_OBJECT_CLASS (e_book_client_cursor_parent_class)->dispose (object);
+}
+
+static void
+book_client_cursor_finalize (GObject *object)
+{
+ EBookClientCursor *cursor = E_BOOK_CLIENT_CURSOR (object);
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ g_free (priv->locale);
+ g_free (priv->revision);
+ g_free (priv->object_path);
+ g_strfreev (priv->alphabet);
+ g_mutex_clear (&priv->main_context_lock);
+
+ /* Chain up to parent's finalize() method. */
+ G_OBJECT_CLASS (e_book_client_cursor_parent_class)->finalize (object);
+}
+
+static void
+book_client_cursor_set_property (GObject *object,
+ guint property_id,
+ const GValue *value,
+ GParamSpec *pspec)
+{
+ switch (property_id) {
+ case PROP_CLIENT:
+ book_client_cursor_set_client (
+ E_BOOK_CLIENT_CURSOR (object),
+ g_value_get_object (value));
+ break;
+
+ case PROP_CONTEXT:
+ book_client_cursor_set_context (
+ E_BOOK_CLIENT_CURSOR (object),
+ g_value_get_boxed (value));
+ break;
+
+ case PROP_CONNECTION:
+ book_client_cursor_set_connection (
+ E_BOOK_CLIENT_CURSOR (object),
+ g_value_get_object (value));
+ break;
+
+ case PROP_OBJECT_PATH:
+ book_client_cursor_set_object_path (
+ E_BOOK_CLIENT_CURSOR (object),
+ g_value_get_string (value));
+ break;
+
+ case PROP_DIRECT_CURSOR:
+ book_client_cursor_set_direct_cursor (
+ E_BOOK_CLIENT_CURSOR (object),
+ g_value_get_object (value));
+ break;
+
+ default:
+ G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+ break;
+ }
+}
+
+static void
+book_client_cursor_get_property (GObject *object,
+ guint property_id,
+ GValue *value,
+ GParamSpec *pspec)
+{
+ switch (property_id) {
+ case PROP_CLIENT:
+ g_value_take_object (
+ value,
+ e_book_client_cursor_ref_client (
+ E_BOOK_CLIENT_CURSOR (object)));
+ break;
+
+ case PROP_ALPHABET:
+ g_value_set_boxed (
+ value,
+ e_book_client_cursor_get_alphabet (
+ E_BOOK_CLIENT_CURSOR (object),
+ NULL, NULL, NULL, NULL));
+ break;
+
+ case PROP_TOTAL:
+ g_value_set_int (
+ value,
+ e_book_client_cursor_get_total (
+ E_BOOK_CLIENT_CURSOR (object)));
+ break;
+
+ case PROP_POSITION:
+ g_value_set_int (
+ value,
+ e_book_client_cursor_get_position (
+ E_BOOK_CLIENT_CURSOR (object)));
+ break;
+
+ default:
+ G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+ break;
+
+ }
+}
+
+/****************************************************
+ * GInitable *
+ ****************************************************/
+static void
+e_book_client_cursor_initable_init (GInitableIface *interface)
+{
+ interface->init = book_client_cursor_initable_init;
+}
+
+static gboolean
+book_client_cursor_initable_init (GInitable *initable,
+ GCancellable *cancellable,
+ GError **error)
+{
+ EBookClientCursor *cursor = E_BOOK_CLIENT_CURSOR (initable);
+ EBookClientCursorPrivate *priv = cursor->priv;
+ EDBusAddressBookCursor *proxy;
+
+ /* We only need a proxy for regular access, no need in DRA mode */
+ if (priv->direct_cursor)
+ return TRUE;
+
+ proxy = e_dbus_address_book_cursor_proxy_new_sync (
+ priv->connection,
+ G_DBUS_PROXY_FLAGS_NONE,
+ ADDRESS_BOOK_DBUS_SERVICE_NAME,
+ priv->object_path,
+ cancellable, error);
+
+ if (!proxy)
+ return FALSE;
+
+ book_client_cursor_set_proxy (cursor, proxy);
+ g_object_unref (proxy);
+
+ return TRUE;
+}
+
+/****************************************************
+ * Private Mutators *
+ ****************************************************
+ *
+ * All private mutators are called either in the thread
+ * which e_book_client_get_cursor() was originally called,
+ * or in the object construction process where there is
+ * a well known strong reference to the EBookClientCursor
+ * instance.
+ */
+static void
+book_client_cursor_set_client (EBookClientCursor *cursor,
+ EBookClient *client)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+ EBookClient *current_client;
+
+ g_return_if_fail (client == NULL || E_IS_BOOK_CLIENT (client));
+
+ current_client = e_book_client_cursor_ref_client (cursor);
+
+ /* Clients can't really change, but we set up this
+ * mutator style code just to manage the signal connections
+ * we watch on the client, we need to disconnect them properly.
+ */
+ if (current_client != client) {
+
+ if (current_client) {
+
+ /* Disconnect signals */
+ g_signal_handler_disconnect (current_client, priv->revision_changed_id);
+ g_signal_handler_disconnect (current_client, priv->locale_changed_id);
+ priv->revision_changed_id = 0;
+ priv->locale_changed_id = 0;
+
+ /* e_book_client_cursor_ref_client() gave us a ref */
+ g_object_unref (current_client);
+ }
+
+ /* Set the new client */
+ g_weak_ref_set (&priv->client, client);
+
+ if (client) {
+ gchar *revision = NULL;
+
+ /* Connect signals */
+ priv->revision_changed_id =
+ g_signal_connect_data (client, "backend-property-changed",
+ G_CALLBACK (client_revision_changed_cb),
+ e_weak_ref_new (cursor),
+ (GClosureNotify) e_weak_ref_free,
+ 0);
+ priv->locale_changed_id =
+ g_signal_connect_data (client, "notify::locale",
+ G_CALLBACK (client_locale_changed_cb),
+ e_weak_ref_new (cursor),
+ (GClosureNotify) e_weak_ref_free,
+ 0);
+
+ /* Load initial locale & revision */
+ book_client_cursor_set_locale (cursor, e_book_client_get_locale (client));
+
+ /* This loads a cached D-Bus property, no D-Bus activity */
+ e_client_get_backend_property_sync (E_CLIENT (client),
+ CLIENT_BACKEND_PROPERTY_REVISION,
+ &revision, NULL, NULL);
+ book_client_cursor_set_revision (cursor, revision);
+ g_free (revision);
+ }
+ }
+}
+
+static void
+book_client_cursor_set_connection (EBookClientCursor *cursor,
+ GDBusConnection *connection)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ g_return_if_fail (connection == NULL || G_IS_DBUS_CONNECTION (connection));
+
+ if (priv->connection != connection) {
+
+ if (priv->connection)
+ g_object_unref (priv->connection);
+
+ priv->connection = connection;
+
+ if (priv->connection)
+ g_object_ref (priv->connection);
+ }
+}
+
+static void
+proxy_dispose_cb (GObject *source_object,
+ GAsyncResult *result,
+ gpointer user_data)
+{
+ GError *local_error = NULL;
+
+ e_dbus_address_book_cursor_call_dispose_finish (
+ E_DBUS_ADDRESS_BOOK_CURSOR (source_object), result, &local_error);
+
+ if (local_error != NULL) {
+ g_dbus_error_strip_remote_error (local_error);
+ g_warning ("%s: %s", G_STRFUNC, local_error->message);
+ g_error_free (local_error);
+ }
+}
+
+static void
+book_client_cursor_set_proxy (EBookClientCursor *cursor,
+ EDBusAddressBookCursor *proxy)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ g_return_if_fail (proxy == NULL || E_DBUS_IS_ADDRESS_BOOK_CURSOR (proxy));
+
+ if (priv->dbus_proxy != proxy) {
+
+ if (priv->dbus_proxy) {
+ g_signal_handler_disconnect (priv->dbus_proxy, priv->proxy_total_changed_id);
+ g_signal_handler_disconnect (priv->dbus_proxy, priv->proxy_position_changed_id);
+ priv->proxy_total_changed_id = 0;
+ priv->proxy_position_changed_id = 0;
+
+ /* Call D-Bus dispose() asynchronously
+ * so we don't block in our dispose() phase.*/
+ e_dbus_address_book_cursor_call_dispose (
+ priv->dbus_proxy, NULL,
+ proxy_dispose_cb, NULL);
+
+ g_object_unref (priv->dbus_proxy);
+ }
+
+ priv->dbus_proxy = proxy;
+
+ if (priv->dbus_proxy) {
+ gint position, total;
+
+ priv->proxy_total_changed_id =
+ g_signal_connect_data (priv->dbus_proxy, "notify::total",
+ G_CALLBACK (proxy_total_changed_cb),
+ e_weak_ref_new (cursor),
+ (GClosureNotify) e_weak_ref_free,
+ 0);
+ priv->proxy_position_changed_id =
+ g_signal_connect_data (priv->dbus_proxy, "notify::position",
+ G_CALLBACK (proxy_position_changed_cb),
+ e_weak_ref_new (cursor),
+ (GClosureNotify) e_weak_ref_free,
+ 0);
+
+ /* Set initial values */
+ total = e_dbus_address_book_cursor_get_total (proxy);
+ position = e_dbus_address_book_cursor_get_position (proxy);
+ book_client_cursor_set_total (cursor, total);
+ book_client_cursor_set_position (cursor, position);
+
+ g_object_ref (priv->dbus_proxy);
+ }
+ }
+}
+
+static void
+book_client_cursor_set_context (EBookClientCursor *cursor,
+ GMainContext *context)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ if (priv->main_context != context) {
+ if (priv->main_context)
+ g_main_context_unref (priv->main_context);
+
+ priv->main_context = context;
+
+ if (priv->main_context)
+ g_main_context_ref (priv->main_context);
+ }
+}
+
+static GMainContext *
+book_client_cursor_ref_context (EBookClientCursor *cursor)
+{
+ GMainContext *main_context;
+
+ /* This is called from D-Bus callbacks which will fire from
+ * whichever thread the EBookClient created the EBookClientCursor
+ * in, and also from EBookClient signal callbacks which get
+ * fired in the thread that the EBookClient was created in,
+ * which might not be the same thread that e_book_client_get_cursor()
+ * was called from.
+ */
+ g_mutex_lock (&cursor->priv->main_context_lock);
+ main_context = g_main_context_ref (cursor->priv->main_context);
+ g_mutex_unlock (&cursor->priv->main_context_lock);
+
+ return main_context;
+}
+
+static void
+book_client_cursor_set_direct_cursor (EBookClientCursor *cursor,
+ EDataBookCursor *direct_cursor)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ g_return_if_fail (direct_cursor == NULL || E_IS_DATA_BOOK_CURSOR (direct_cursor));
+
+ if (priv->direct_cursor != direct_cursor) {
+
+ if (priv->direct_cursor) {
+
+ g_signal_handler_disconnect (priv->direct_cursor, priv->dra_total_changed_id);
+ g_signal_handler_disconnect (priv->direct_cursor, priv->dra_position_changed_id);
+ priv->dra_total_changed_id = 0;
+ priv->dra_position_changed_id = 0;
+
+ g_object_unref (priv->direct_cursor);
+ }
+
+ priv->direct_cursor = direct_cursor;
+
+ if (priv->direct_cursor) {
+ GError *error = NULL;
+ gchar *freeme = NULL;
+ gint total, position;
+
+ priv->dra_total_changed_id =
+ g_signal_connect (priv->direct_cursor, "notify::total",
+ G_CALLBACK (dra_total_changed_cb),
+ cursor);
+ priv->dra_position_changed_id =
+ g_signal_connect (priv->direct_cursor, "notify::position",
+ G_CALLBACK (dra_position_changed_cb),
+ cursor);
+
+ /* Load initial locale */
+ if (priv->direct_cursor &&
+ !e_data_book_cursor_load_locale (priv->direct_cursor,
+ &freeme, &error)) {
+ g_warning ("Error loading locale in direct read access cursor: %s",
+ error->message);
+ g_clear_error (&error);
+ }
+ g_free (freeme);
+
+ /* Set initial values */
+ total = e_data_book_cursor_get_total (priv->direct_cursor);
+ position = e_data_book_cursor_get_position (priv->direct_cursor);
+ book_client_cursor_set_total (cursor, total);
+ book_client_cursor_set_position (cursor, position);
+
+ g_object_ref (priv->direct_cursor);
+ }
+ }
+}
+
+static void
+book_client_cursor_set_object_path (EBookClientCursor *cursor,
+ const gchar *object_path)
+{
+ g_return_if_fail (cursor->priv->object_path == NULL);
+
+ cursor->priv->object_path = g_strdup (object_path);
+}
+
+static void
+book_client_cursor_set_locale (EBookClientCursor *cursor,
+ const gchar *locale)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+ ECollator *collator;
+ GError *error = NULL;
+ const gchar *const *labels;
+
+ if (g_strcmp0 (priv->locale, locale) == 0)
+ return;
+
+ g_free (priv->locale);
+ priv->locale = g_strdup (locale);
+
+ collator = e_collator_new (locale, &error);
+
+ if (!collator) {
+ g_warning ("Error loading collator for locale '%s': %s",
+ locale, error->message);
+ g_clear_error (&error);
+ return;
+ }
+
+ g_strfreev (priv->alphabet);
+ labels = e_collator_get_index_labels (collator,
+ &priv->n_labels,
+ &priv->underflow,
+ &priv->inflow,
+ &priv->overflow);
+ priv->alphabet = g_strdupv ((gchar **)labels);
+ e_collator_unref (collator);
+
+ /* Notify the alphabet change */
+ g_object_notify (G_OBJECT (cursor), "alphabet");
+
+ /* The server side EDataBookCursor should have already
+ * reset it's cursor values internally and notified
+ * a new total & position value, however we need to
+ * reset any direct cursor here.
+ */
+ if (priv->direct_cursor) {
+ gchar *freeme = NULL;
+
+ if (!e_data_book_cursor_load_locale (priv->direct_cursor,
+ &freeme, &error)) {
+ g_warning ("Error loading locale in direct read access cursor: %s",
+ error->message);
+ g_clear_error (&error);
+
+ } else if (!e_data_book_cursor_move_by (priv->direct_cursor,
+ NULL,
+ E_BOOK_CURSOR_ORIGIN_RESET,
+ 0,
+ NULL,
+ &error)) {
+ g_warning ("Error resetting cursor position after locale change: %s",
+ error->message);
+ g_clear_error (&error);
+ }
+
+ g_free (freeme);
+ }
+
+ /* The alphabet changing should have been enough,
+ * but still trigger a refresh
+ */
+ g_signal_emit (cursor, signals[REFRESH], 0);
+}
+
+static void
+book_client_cursor_set_revision (EBookClientCursor *cursor,
+ const gchar *revision)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ if (g_strcmp0 (priv->revision, revision) != 0) {
+
+ g_free (priv->revision);
+ priv->revision = g_strdup (revision);
+
+ /* In DRA mode we need to reload our local
+ * total / position calculations with EDataBookCursor APIs
+ */
+
+ /* The addressbook has changed, need a refresh */
+ g_signal_emit (cursor, signals[REFRESH], 0);
+ }
+}
+
+static void
+book_client_cursor_set_total (EBookClientCursor *cursor,
+ gint total)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ if (priv->total != total) {
+ priv->total = total;
+
+ g_object_notify (G_OBJECT (cursor), "total");
+ }
+}
+
+static void
+book_client_cursor_set_position (EBookClientCursor *cursor,
+ gint position)
+{
+ EBookClientCursorPrivate *priv = cursor->priv;
+
+ if (priv->position != position) {
+ priv->position = position;
+
+ g_object_notify (G_OBJECT (cursor), "position");
+ }
+}
+
+/****************************************************
+ * Notifications from other threads *
+ ****************************************************
+ *
+ * The notification subsystem takes care of calling
+ * our private mutator functions from the thread in
+ * which e_book_client_get_cursor() was originally
+ * called, where it's safe to emit signals on the
+ * EBookClientCursor instance.
+ *
+ * The notification functions, notification_new_string()
+ * and notification_new_int() must be called where
+ * a strong reference to the EBookClientCursor exists.
+ */
+enum _NotificationType {
+ REVISION_CHANGED,
+ LOCALE_CHANGED,
+ TOTAL_CHANGED,
+ POSITION_CHANGED,
+};
+
+struct _Notification {
+ GWeakRef cursor;
+ NotificationType type;
+ GValue value;
+};
+
+static void
+notification_new_string (EBookClientCursor *cursor,
+ NotificationType type,
+ const gchar *value)
+{
+ Notification *notification = g_slice_new0 (Notification);
+
+ notification->type = type;
+ g_weak_ref_set (¬ification->cursor, cursor);
+
+ g_value_init (¬ification->value, G_TYPE_STRING);
+ g_value_set_string (¬ification->value, value);
+
+ notification_queue (cursor, notification);
+}
+
+static void
+notification_new_int (EBookClientCursor *cursor,
+ NotificationType type,
+ gint value)
+{
+ Notification *notification = g_slice_new0 (Notification);
+
+ notification->type = type;
+ g_weak_ref_set (¬ification->cursor, cursor);
+
+ g_value_init (¬ification->value, G_TYPE_INT);
+ g_value_set_int (¬ification->value, value);
+
+ notification_queue (cursor, notification);
+}
+
+static void
+notification_free (Notification *notification)
+{
+ if (notification) {
+ g_weak_ref_set (¬ification->cursor, NULL);
+ g_value_unset (¬ification->value);
+ g_slice_free (Notification, notification);
+ }
+}
+
+static void
+notification_queue (EBookClientCursor *cursor,
+ Notification *notification)
+{
+ GMainContext *context;
+ GSource *source;
+
+ context = book_client_cursor_ref_context (cursor);
+
+ source = g_idle_source_new ();
+ g_source_set_callback (source,
+ (GSourceFunc)notification_dispatch,
+ notification,
+ (GDestroyNotify)notification_free);
+ g_source_attach (source, context);
+ g_source_unref (source);
+
+ g_main_context_unref (context);
+}
+
+static gboolean
+notification_dispatch (Notification *notification)
+{
+ EBookClientCursor *cursor;
+
+ cursor = g_weak_ref_get (¬ification->cursor);
+ if (!cursor)
+ return FALSE;
+
+ switch (notification->type) {
+ case REVISION_CHANGED:
+ book_client_cursor_set_revision (
+ cursor,
+ g_value_get_string (¬ification->value));
+ break;
+ case LOCALE_CHANGED:
+ book_client_cursor_set_locale (
+ cursor,
+ g_value_get_string (¬ification->value));
+ break;
+ case TOTAL_CHANGED:
+ book_client_cursor_set_total (
+ cursor,
+ g_value_get_int (¬ification->value));
+ break;
+ case POSITION_CHANGED:
+ book_client_cursor_set_position (
+ cursor,
+ g_value_get_int (¬ification->value));
+ break;
+ }
+
+ g_object_unref (cursor);
+
+ return FALSE;
+}
+
+/****************************************************
+ * Callbacks from EBookClient *
+ ****************************************************/
+static void
+client_revision_changed_cb (EClient *client,
+ const gchar *prop_name,
+ const gchar *prop_value,
+ GWeakRef *weak_ref)
+{
+ EBookClientCursor *cursor;
+
+ if (g_strcmp0 (prop_name, CLIENT_BACKEND_PROPERTY_REVISION) != 0)
+ return;
+
+ cursor = g_weak_ref_get (weak_ref);
+ if (cursor) {
+ notification_new_string (cursor, REVISION_CHANGED, prop_value);
+ g_object_unref (cursor);
+ }
+}
+
+static void
+client_locale_changed_cb (EBookClient *book_client,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref)
+{
+ EBookClientCursor *cursor;
+
+ cursor = g_weak_ref_get (weak_ref);
+ if (cursor) {
+ notification_new_string (cursor, LOCALE_CHANGED, e_book_client_get_locale (book_client));
+ g_object_unref (cursor);
+ }
+}
+
+/****************************************************
+ * Callbacks from EDBusAddressBookCursor *
+ ****************************************************/
+static void
+proxy_total_changed_cb (EDBusAddressBookCursor *proxy,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref)
+{
+ EBookClientCursor *cursor;
+
+ cursor = g_weak_ref_get (weak_ref);
+ if (cursor) {
+ notification_new_int (cursor, TOTAL_CHANGED,
+ e_dbus_address_book_cursor_get_total (proxy));
+ g_object_unref (cursor);
+ }
+}
+
+static void
+proxy_position_changed_cb (EDBusAddressBookCursor *proxy,
+ GParamSpec *pspec,
+ GWeakRef *weak_ref)
+{
+ EBookClientCursor *cursor;
+
+ cursor = g_weak_ref_get (weak_ref);
+ if (cursor) {
+ notification_new_int (cursor, POSITION_CHANGED,
+ e_dbus_address_book_cursor_get_position (proxy));
+ g_object_unref (cursor);
+ }
+}
+
+/****************************************************
+ * Callbacks from EDBusAddressBookCursor *
+ ****************************************************/
+static void
+dra_total_changed_cb (EDataBookCursor *direct_cursor,
+ GParamSpec *pspec,
+ EBookClientCursor *cursor)
+{
+ notification_new_int (cursor, TOTAL_CHANGED,
+ e_data_book_cursor_get_total (direct_cursor));
+}
+
+static void
+dra_position_changed_cb (EDataBookCursor *direct_cursor,
+ GParamSpec *pspec,
+ EBookClientCursor *cursor)
+{
+ notification_new_int (cursor, POSITION_CHANGED,
+ e_data_book_cursor_get_position (direct_cursor));
+}
+
+/****************************************************
+ * Threaded method call contexts *
+ ****************************************************
+ *
+ * This subsystem is simply a toolbox of helper functions
+ * to execute synchronous D-Bus method calls while providing
+ * an asynchronous API.
+ *
+ * We choose this method of asynchronous D-Bus calls only
+ * to be consistent with the rest of the libebook library.
+ */
+struct _MoveByContext {
+ EBookCursorOrigin origin;
+ gint count;
+ gboolean fetch_results;
+ GSList *contacts;
+};
+
+struct _AlphabetIndexContext {
+ gint index;
+ gchar *locale;
+};
+
+struct _SetSexpContext {
+ gchar *sexp;
+};
+
+static SetSexpContext *
+set_sexp_context_new (const gchar *sexp)
+{
+ SetSexpContext *context = g_slice_new0 (SetSexpContext);
+
+ context->sexp = g_strdup (sexp);
+
+ return context;
+}
+
+static void
+set_sexp_context_free (SetSexpContext *context)
+{
+ if (context) {
+ g_free (context->sexp);
+ g_slice_free (SetSexpContext, context);
+ }
+}
+
+static void
+set_sexp_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable)
+{
+ SetSexpContext *context;
+ GError *local_error = NULL;
+
+ context = g_simple_async_result_get_op_res_gpointer (simple);
+
+ e_book_client_cursor_set_sexp_sync (E_BOOK_CLIENT_CURSOR (source_object),
+ context->sexp,
+ cancellable,
+ &local_error);
+
+ if (local_error != NULL)
+ g_simple_async_result_take_error (simple, local_error);
+}
+
+static MoveByContext *
+move_by_context_new (EBookCursorOrigin origin,
+ gint count,
+ gboolean fetch_results)
+{
+ MoveByContext *context = g_slice_new0 (MoveByContext);
+
+ context->origin = origin;
+ context->count = count;
+ context->fetch_results = fetch_results;
+
+ return context;
+}
+
+static void
+move_by_context_free (MoveByContext *context)
+{
+ if (context) {
+ g_slist_free_full (context->contacts, (GDestroyNotify)g_object_unref);
+ g_slice_free (MoveByContext, context);
+ }
+}
+
+static void
+move_by_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable)
+{
+ MoveByContext *context;
+ GError *local_error = NULL;
+
+ context = g_simple_async_result_get_op_res_gpointer (simple);
+
+ e_book_client_cursor_move_by_sync (E_BOOK_CLIENT_CURSOR (source_object),
+ context->origin,
+ context->count,
+ context->fetch_results ? &(context->contacts) : NULL,
+ cancellable, &local_error);
+
+ if (local_error != NULL)
+ g_simple_async_result_take_error (simple, local_error);
+}
+
+static AlphabetIndexContext *
+alphabet_index_context_new (gint index,
+ const gchar *locale)
+{
+ AlphabetIndexContext *context = g_slice_new0 (AlphabetIndexContext);
+
+ context->index = index;
+ context->locale = g_strdup (locale);
+
+ return context;
+}
+
+static void
+alphabet_index_context_free (AlphabetIndexContext *context)
+{
+ if (context) {
+ g_free (context->locale);
+ g_slice_free (AlphabetIndexContext, context);
+ }
+}
+
+static gboolean
+set_alphabetic_index_sync_internal (EBookClientCursor *cursor,
+ gint index,
+ const gchar *locale,
+ GCancellable *cancellable,
+ GError **error)
+{
+ GError *local_error = NULL;
+
+ e_dbus_address_book_cursor_call_set_alphabetic_index_sync (
+ cursor->priv->dbus_proxy,
+ index, locale,
+ cancellable,
+ &local_error);
+
+ if (local_error != NULL) {
+ g_dbus_error_strip_remote_error (local_error);
+ g_propagate_error (error, local_error);
+ return FALSE;
+ }
+
+ return TRUE;
+}
+
+static void
+alphabet_index_thread (GSimpleAsyncResult *simple,
+ GObject *source_object,
+ GCancellable *cancellable)
+{
+ AlphabetIndexContext *context;
+ GError *local_error = NULL;
+
+ context = g_simple_async_result_get_op_res_gpointer (simple);
+
+ set_alphabetic_index_sync_internal (E_BOOK_CLIENT_CURSOR (source_object),
+ context->index,
+ context->locale,
+ cancellable,
+ &local_error);
+
+ if (local_error != NULL)
+ g_simple_async_result_take_error (simple, local_error);
+}
+
+/****************************************************
+ * API *
+ ****************************************************/
+/**
+ * e_book_client_cursor_ref_client:
+ * @cursor: an #EBookClientCursor
+ *
+ * Returns the #EBookClientCursor:client associated with @cursor.
+ *
+ * The returned #EBookClient is referenced for thread-safety. Unreference
+ * the #EBookClient with g_object_unref() when finished with it.
+ *
+ * Returns: (transfer full): an #EBookClient
+ *
+ * Since: 3.10
+ */
+EBookClient *
+e_book_client_cursor_ref_client (EBookClientCursor *cursor)
+{
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), NULL);
+
+ return g_weak_ref_get (&cursor->priv->client);
+}
+
+/**
+ * e_book_client_cursor_get_alphabet:
+ * @cursor: an #EBookClientCursor
+ * @n_labels: (out) (allow-none): The number of labels in the active alphabet
+ * @underflow: (allow-none) (out): The underflow index, for any words which sort below the active alphabet
+ * @inflow: (allow-none) (out): The inflow index, for any words which sort between the active alphabets (if
there is more than one)
+ * @overflow: (allow-none) (out): The overflow index, for any words which sort above the active alphabet
+ *
+ * Fetches the displayable labels and index positions for the active alphabet.
+ *
+ * Returns: (array zero-terminated=1) (element-type utf8) (transfer none):
+ * The array of displayable labels for each index in the active alphabet.
+ *
+ * Since: 3.10
+ */
+const gchar * const *
+e_book_client_cursor_get_alphabet (EBookClientCursor *cursor,
+ gint *n_labels,
+ gint *underflow,
+ gint *inflow,
+ gint *overflow)
+{
+ EBookClientCursorPrivate *priv;
+
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), NULL);
+
+ priv = cursor->priv;
+
+ if (n_labels)
+ *n_labels = priv->n_labels;
+ if (underflow)
+ *underflow = priv->underflow;
+ if (inflow)
+ *inflow = priv->inflow;
+ if (overflow)
+ *overflow = priv->overflow;
+
+ return (const gchar *const *)priv->alphabet;
+}
+
+/**
+ * e_book_client_cursor_get_total:
+ * @cursor: an #EBookClientCursor
+ *
+ * Fetches the total number of contacts in the addressbook
+ * which match @cursor's query
+ *
+ * Returns: The total number of contacts matching @cursor's query
+ *
+ * Since: 3.10
+ */
+gint
+e_book_client_cursor_get_total (EBookClientCursor *cursor)
+{
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), -1);
+
+ return cursor->priv->total;
+}
+
+/**
+ * e_book_client_cursor_get_position:
+ * @cursor: an #EBookClientCursor
+ *
+ * Fetches the current cursor position within @cursor's
+ * query results.
+ *
+ * The position value can be any where from 0 to the total
+ * number of contacts at any given time, a value of 0 indicates
+ * that the cursor is positioned before the contact list, if
+ * the position is equal to the total, as returned by
+ * e_book_client_cursor_get_total(), then the cursor points
+ * to the last contact in @cursor's query results.
+ *
+ * Returns: The current cursor position
+ *
+ * Since: 3.10
+ */
+gint
+e_book_client_cursor_get_position (EBookClientCursor *cursor)
+{
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), -1);
+
+ return cursor->priv->position;
+}
+
+/**
+ * e_book_client_cursor_set_sexp:
+ * @cursor: an #EBookClientCursor
+ * @sexp: the new search expression for @cursor
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @callback: callback to call when a result is ready
+ * @user_data: user data for the @callback
+ *
+ * Sets the search expression for the cursor.
+ *
+ * A side effect of setting the search expression is that the
+ * #EBookClientCursor:position and and #EBookClientCursor:total
+ * properties will be updated asynchronously.
+ *
+ * This asynchronous call is completed with a call to
+ * e_book_client_cursor_set_sexp_finish() from the specified @callback.
+ *
+ * Since: 3.10
+ */
+void
+e_book_client_cursor_set_sexp (EBookClientCursor *cursor,
+ const gchar *sexp,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+
+
+ GSimpleAsyncResult *simple;
+ SetSexpContext *context;
+
+ g_return_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor));
+ g_return_if_fail (callback != NULL);
+
+ context = set_sexp_context_new (sexp);
+ simple = g_simple_async_result_new (G_OBJECT (cursor),
+ callback, user_data,
+ e_book_client_cursor_set_sexp);
+
+ g_simple_async_result_set_check_cancellable (simple, cancellable);
+ g_simple_async_result_set_op_res_gpointer (simple, context,
+ (GDestroyNotify) set_sexp_context_free);
+
+ g_simple_async_result_run_in_thread (
+ simple, set_sexp_thread,
+ G_PRIORITY_DEFAULT, cancellable);
+
+ g_object_unref (simple);
+}
+
+/**
+ * e_book_client_cursor_set_sexp_finish:
+ * @cursor: an #EBookClientCursor
+ * @result: a #GAsyncResult
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Completes an asynchronous call initiated by e_book_client_cursor_set_sexp(), reporting
+ * whether the new search expression was accepted.
+ *
+ * If the backend does not support the given search expression,
+ * an %E_CLIENT_ERROR_INVALID_QUERY error will be set.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Since: 3.10
+ */
+gboolean
+e_book_client_cursor_set_sexp_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GError **error)
+{
+ GSimpleAsyncResult *simple;
+
+ g_return_val_if_fail (
+ g_simple_async_result_is_valid (
+ result, G_OBJECT (cursor),
+ e_book_client_cursor_set_sexp), FALSE);
+
+ simple = G_SIMPLE_ASYNC_RESULT (result);
+
+ if (g_simple_async_result_propagate_error (simple, error))
+ return FALSE;
+
+ return TRUE;
+}
+
+/**
+ * e_book_client_cursor_set_sexp_sync:
+ * @cursor: an #EBookClientCursor
+ * @sexp: the new search expression for @cursor
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * A synchronous variation of the e_book_client_cursor_set_sexp() function.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Since: 3.10
+ */
+gboolean
+e_book_client_cursor_set_sexp_sync (EBookClientCursor *cursor,
+ const gchar *sexp,
+ GCancellable *cancellable,
+ GError **error)
+{
+ EBookClientCursorPrivate *priv;
+ gchar *utf8_sexp;
+ GError *local_error = NULL;
+
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), FALSE);
+
+ priv = cursor->priv;
+
+ if (priv->direct_cursor) {
+
+ if (!e_data_book_cursor_set_sexp (priv->direct_cursor,
+ sexp, error))
+ return FALSE;
+
+ return TRUE;
+ }
+
+ utf8_sexp = e_util_utf8_make_valid (sexp);
+ e_dbus_address_book_cursor_call_set_query_sync (
+ priv->dbus_proxy,
+ utf8_sexp,
+ cancellable,
+ &local_error);
+ g_free (utf8_sexp);
+
+ if (local_error != NULL) {
+ g_dbus_error_strip_remote_error (local_error);
+ g_propagate_error (error, local_error);
+ return FALSE;
+ }
+
+ return TRUE;
+}
+
+/**
+ * e_book_client_cursor_move_by:
+ * @cursor: an #EBookClientCursor
+ * @origin: the #EBookCursorOrigin for this move
+ * @count: a positive or negative amount of contacts to try and fetch
+ * @fetch_results: whether to fetch the list of results, if %FALSE then only the position and cursor value
is modified.
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @callback: callback to call when a result is ready
+ * @user_data: user data for the @callback
+ *
+ * Moves @cursor through the results by a maximum of @count
+ * and fetch the results traversed, if @fetch_results is %TRUE.
+ *
+ * If @count is negative, then the cursor will move backwards.
+ *
+ * If @cursor's position is %0, or @origin is %E_BOOK_CURSOR_ORIGIN_RESET,
+ * then @count contacts will be fetched from the beginning of the cursor's query
+ * results, or from the ending of the query results for a negative value of @count.
+ *
+ * If @cursor reaches the beginning or end of the query results, then the
+ * returned results might not contain the requested amount of contacts, or might
+ * return no results at all if the cursor currently points to the last contact.
+ * This is not considered an error condition, but will result in a cursor position
+ * of %0.
+ *
+ * This asynchronous call is completed with a call to
+ * e_book_client_cursor_move_by_finish() from the specified @callback.
+ *
+ * Since: 3.10
+ */
+void
+e_book_client_cursor_move_by (EBookClientCursor *cursor,
+ EBookCursorOrigin origin,
+ gint count,
+ gboolean fetch_results,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+ GSimpleAsyncResult *simple;
+ MoveByContext *context;
+
+ g_return_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor));
+ g_return_if_fail (count != 0 || origin == E_BOOK_CURSOR_ORIGIN_RESET);
+ g_return_if_fail (callback != NULL);
+
+ context = move_by_context_new (origin, count, fetch_results);
+ simple = g_simple_async_result_new (G_OBJECT (cursor),
+ callback, user_data,
+ e_book_client_cursor_move_by);
+
+ g_simple_async_result_set_check_cancellable (simple, cancellable);
+ g_simple_async_result_set_op_res_gpointer (simple, context,
+ (GDestroyNotify) move_by_context_free);
+
+ g_simple_async_result_run_in_thread (
+ simple, move_by_thread,
+ G_PRIORITY_DEFAULT, cancellable);
+
+ g_object_unref (simple);
+}
+
+/**
+ * e_book_client_cursor_move_by_finish:
+ * @cursor: an #EBookClientCursor
+ * @result: a #GAsyncResult
+ * @out_contacts: (element-type EContact) (out) (transfer full) (allow-none): return location for a #GSList
of #EContacts
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Completes an asynchronous call initiated by e_book_client_cursor_move_by(), fetching
+ * any contacts which might have been returned by the call.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Since: 3.10
+ */
+gboolean
+e_book_client_cursor_move_by_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GSList **out_contacts,
+ GError **error)
+{
+ GSimpleAsyncResult *simple;
+ MoveByContext *context;
+
+ g_return_val_if_fail (
+ g_simple_async_result_is_valid (
+ result, G_OBJECT (cursor),
+ e_book_client_cursor_move_by), FALSE);
+
+ simple = G_SIMPLE_ASYNC_RESULT (result);
+ context = g_simple_async_result_get_op_res_gpointer (simple);
+
+ if (g_simple_async_result_propagate_error (simple, error))
+ return FALSE;
+
+ if (out_contacts != NULL) {
+ *out_contacts = context->contacts;
+ context->contacts = NULL;
+ }
+
+ return TRUE;
+}
+
+/**
+ * e_book_client_cursor_move_by_sync:
+ * @cursor: an #EBookClientCursor
+ * @origin: the #EBookCursorOrigin for this move
+ * @count: a positive or negative amount of contacts to try and fetch
+ * @out_contacts: (element-type EContact) (out) (transfer full) (allow-none): return location for a #GSList
of #EContacts
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * A synchronous variation of the e_book_client_cursor_move_by() function.
+ *
+ * If @out_contacts is %NULL, the cursor will be moved but no results will be fetched from the addressbook.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Since: 3.10
+ */
+gboolean
+e_book_client_cursor_move_by_sync (EBookClientCursor *cursor,
+ EBookCursorOrigin origin,
+ gint count,
+ GSList **out_contacts,
+ GCancellable *cancellable,
+ GError **error)
+{
+ EBookClientCursorPrivate *priv;
+ GError *local_error = NULL;
+ gchar **vcards = NULL;
+
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), FALSE);
+ g_return_val_if_fail (count != 0 || origin == E_BOOK_CURSOR_ORIGIN_RESET, FALSE);
+
+ priv = cursor->priv;
+
+ if (priv->direct_cursor) {
+ GSList *results = NULL, *l;
+ GSList *contacts = NULL;
+
+ if (!e_data_book_cursor_move_by (priv->direct_cursor,
+ priv->revision,
+ origin,
+ count,
+ out_contacts ? &results : NULL,
+ error))
+ return FALSE;
+
+ for (l = results; l; l = l->next) {
+ gchar *vcard = l->data;
+ EContact *contact = e_contact_new_from_vcard (vcard);
+
+ contacts = g_slist_prepend (contacts, contact);
+ }
+
+ g_slist_free_full (results, (GDestroyNotify)g_free);
+
+ if (out_contacts)
+ *out_contacts = g_slist_reverse (contacts);
+ else
+ g_slist_free_full (contacts, (GDestroyNotify)g_object_unref);
+
+ return TRUE;
+ }
+
+ e_dbus_address_book_cursor_call_move_by_sync (
+ priv->dbus_proxy,
+ origin, count,
+ out_contacts != NULL,
+ &vcards,
+ cancellable,
+ &local_error);
+
+ if (local_error != NULL) {
+ g_dbus_error_strip_remote_error (local_error);
+ g_propagate_error (error, local_error);
+ return FALSE;
+ }
+
+ if (vcards != NULL) {
+ EContact *contact;
+ GSList *tmp = NULL;
+ gint i;
+
+ for (i = 0; vcards[i] != NULL; i++) {
+ contact = e_contact_new_from_vcard (vcards[i]);
+ tmp = g_slist_prepend (tmp, contact);
+ }
+
+ *out_contacts = g_slist_reverse (tmp);
+
+ g_strfreev (vcards);
+ }
+
+ return TRUE;
+}
+
+/**
+ * e_book_client_cursor_set_alphabetic_index:
+ * @cursor: an #EBookClientCursor
+ * @index: the alphabetic index
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @callback: callback to call when a result is ready
+ * @user_data: user data for the @callback
+ *
+ * Sets the current cursor position to point to an index into the active alphabet.
+ *
+ * After setting the target to an alphabetic index, for example the
+ * index for letter 'E', then further calls to e_book_client_cursor_move_by()
+ * will return results starting with the letter 'E' (or results starting
+ * with the last result in 'D', if moving in a negative direction).
+ *
+ * The passed index must be a valid index into the alphabet parameters
+ * returned by e_book_client_cursor_get_alphabet(). If by any chance
+ * the addressbook backend has changed into a new locale, causing the
+ * active alphabet to change, then an %E_CLIENT_ERROR_OUT_OF_SYNC error
+ * will be issued indicating that there was an alphabet mismatch.
+ *
+ * In the case of an alphabet change, the new active alphabet should
+ * be loaded and e_book_client_cursor_set_alphabetic_index() can be
+ * called again with a valid index into the new active alphabet.
+ *
+ * This asynchronous call is completed with a call to
+ * e_book_client_cursor_set_alphabetic_index_finish() from the specified @callback.
+ *
+ * Since: 3.10
+ */
+void
+e_book_client_cursor_set_alphabetic_index (EBookClientCursor *cursor,
+ gint index,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+ GSimpleAsyncResult *simple;
+ AlphabetIndexContext *context;
+
+ g_return_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor));
+ g_return_if_fail (index >= 0 && index < cursor->priv->n_labels);
+ g_return_if_fail (callback != NULL);
+
+ context = alphabet_index_context_new (index, cursor->priv->locale);
+ simple = g_simple_async_result_new (G_OBJECT (cursor),
+ callback, user_data,
+ e_book_client_cursor_set_alphabetic_index);
+
+ g_simple_async_result_set_check_cancellable (simple, cancellable);
+ g_simple_async_result_set_op_res_gpointer (simple, context,
+ (GDestroyNotify) alphabet_index_context_free);
+
+ g_simple_async_result_run_in_thread (
+ simple, alphabet_index_thread,
+ G_PRIORITY_DEFAULT, cancellable);
+
+ g_object_unref (simple);
+
+
+}
+
+/**
+ * e_book_client_cursor_set_alphabetic_index_finish:
+ * @cursor: an #EBookClientCursor
+ * @result: a #GAsyncResult
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * Completes an asynchronous call initiated by e_book_client_cursor_set_alphabetic_index().
+ *
+ * If there was a locale setting change, an %E_CLIENT_ERROR_OUT_OF_SYNC error will be issued.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ */
+gboolean
+e_book_client_cursor_set_alphabetic_index_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GError **error)
+{
+ GSimpleAsyncResult *simple;
+
+ g_return_val_if_fail (
+ g_simple_async_result_is_valid (
+ result, G_OBJECT (cursor),
+ e_book_client_cursor_set_alphabetic_index), FALSE);
+
+ simple = G_SIMPLE_ASYNC_RESULT (result);
+
+ if (g_simple_async_result_propagate_error (simple, error))
+ return FALSE;
+
+ return TRUE;
+}
+
+/**
+ * e_book_client_cursor_set_alphabetic_index_sync:
+ * @cursor: an #EBookClientCursor
+ * @index: the alphabetic index
+ * @cancellable: (allow-none): a #GCancellable to optionally cancel this operation while in progress
+ * @error: (out) (allow-none): return location for a #GError, or %NULL
+ *
+ * A synchronous variation of the e_book_client_cursor_set_alphabetic_index() function.
+ *
+ * Returns: %TRUE if successful, %FALSE otherwise.
+ *
+ * Since: 3.10
+ */
+gboolean
+e_book_client_cursor_set_alphabetic_index_sync (EBookClientCursor *cursor,
+ gint index,
+ GCancellable *cancellable,
+ GError **error)
+{
+ g_return_val_if_fail (E_IS_BOOK_CLIENT_CURSOR (cursor), FALSE);
+ g_return_val_if_fail (index >= 0 && index < cursor->priv->n_labels, FALSE);
+
+ return set_alphabetic_index_sync_internal (cursor, index, cursor->priv->locale,
+ cancellable, error);
+}
diff --git a/addressbook/libebook/e-book-client-cursor.h b/addressbook/libebook/e-book-client-cursor.h
new file mode 100644
index 0000000..f7fa502
--- /dev/null
+++ b/addressbook/libebook/e-book-client-cursor.h
@@ -0,0 +1,130 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*
+ * Copyright (C) 2013 Intel Corporation
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ * Author: Tristan Van Berkom <tristanvb openismus com>
+ */
+
+#if !defined (__LIBEBOOK_H_INSIDE__) && !defined (LIBEBOOK_COMPILATION)
+#error "Only <libebook/libebook.h> should be included directly."
+#endif
+
+#ifndef E_BOOK_CLIENT_CURSOR_H
+#define E_BOOK_CLIENT_CURSOR_H
+
+#include <glib-object.h>
+#include <libebook-contacts/libebook-contacts.h>
+
+/* Standard GObject macros */
+#define E_TYPE_BOOK_CLIENT_CURSOR \
+ (e_book_client_cursor_get_type ())
+#define E_BOOK_CLIENT_CURSOR(obj) \
+ (G_TYPE_CHECK_INSTANCE_CAST \
+ ((obj), E_TYPE_BOOK_CLIENT_CURSOR, EBookClientCursor))
+#define E_BOOK_CLIENT_CURSOR_CLASS(cls) \
+ (G_TYPE_CHECK_CLASS_CAST \
+ ((cls), E_TYPE_BOOK_CLIENT_CURSOR, EBookClientCursorClass))
+#define E_IS_BOOK_CLIENT_CURSOR(obj) \
+ (G_TYPE_CHECK_INSTANCE_TYPE \
+ ((obj), E_TYPE_BOOK_CLIENT_CURSOR))
+#define E_IS_BOOK_CLIENT_CURSOR_CLASS(cls) \
+ (G_TYPE_CHECK_CLASS_TYPE \
+ ((cls), E_TYPE_BOOK_CLIENT_CURSOR))
+#define E_BOOK_CLIENT_CURSOR_GET_CLASS(obj) \
+ (G_TYPE_INSTANCE_GET_CLASS \
+ ((obj), E_TYPE_BOOK_CLIENT_CURSOR, EBookClientCursorClass))
+
+G_BEGIN_DECLS
+
+typedef struct _EBookClientCursor EBookClientCursor;
+typedef struct _EBookClientCursorClass EBookClientCursorClass;
+typedef struct _EBookClientCursorPrivate EBookClientCursorPrivate;
+
+struct _EBookClient;
+
+/**
+ * EBookClientCursor:
+ *
+ * Contains only private data.
+ *
+ * Since: 3.10
+ **/
+struct _EBookClientCursor {
+ GObject parent;
+ EBookClientCursorPrivate *priv;
+};
+
+struct _EBookClientCursorClass {
+ GObjectClass parent_class;
+
+ /* Signals */
+ void (* refresh) (EBookClientCursor *cursor);
+};
+
+GType e_book_client_cursor_get_type (void) G_GNUC_CONST;
+struct _EBookClient *e_book_client_cursor_ref_client (EBookClientCursor *cursor);
+const gchar * const *e_book_client_cursor_get_alphabet (EBookClientCursor *cursor,
+ gint *n_labels,
+ gint *underflow,
+ gint *inflow,
+ gint *overflow);
+gint e_book_client_cursor_get_total (EBookClientCursor *cursor);
+gint e_book_client_cursor_get_position (EBookClientCursor *cursor);
+void e_book_client_cursor_set_sexp (EBookClientCursor *cursor,
+ const gchar *sexp,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean e_book_client_cursor_set_sexp_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GError **error);
+gboolean e_book_client_cursor_set_sexp_sync (EBookClientCursor *cursor,
+ const gchar *sexp,
+ GCancellable *cancellable,
+ GError **error);
+void e_book_client_cursor_move_by (EBookClientCursor *cursor,
+ EBookCursorOrigin origin,
+ gint count,
+ gboolean fetch_results,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean e_book_client_cursor_move_by_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GSList **out_contacts,
+ GError **error);
+gboolean e_book_client_cursor_move_by_sync (EBookClientCursor *cursor,
+ EBookCursorOrigin origin,
+ gint count,
+ GSList **out_contacts,
+ GCancellable *cancellable,
+ GError **error);
+void e_book_client_cursor_set_alphabetic_index (EBookClientCursor *cursor,
+ gint index,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean e_book_client_cursor_set_alphabetic_index_finish (EBookClientCursor *cursor,
+ GAsyncResult *result,
+ GError **error);
+gboolean e_book_client_cursor_set_alphabetic_index_sync (EBookClientCursor *cursor,
+ gint index,
+ GCancellable *cancellable,
+ GError **error);
+
+G_END_DECLS
+
+#endif /* E_BOOK_CLIENT_CURSOR_H */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
