4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) version 3.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with the program; if not, see <http://www.gnu.org/licenses/>
18 * Copyright (C) 2011 Red Hat, Inc. (www.redhat.com)
22 /* TODO The next time we have a good excuse to break libedataserver's API,
23 * I'd like to purge all the deprecated cruft here and convert EClient
24 * from a GObjectClass to a GTypeInterface, implemented by EBookClient
25 * and ECalClient. Then we could just bind the "online", "readonly"
26 * and "capabilities" properties to equivalent GDBusProxy properties
27 * and kill e-client-private.h. Would simplify things. --mbarnes
34 #include <glib/gi18n-lib.h>
37 #include <libedataserver/e-data-server-util.h>
39 #include "e-gdbus-marshallers.h"
42 #include "e-client-private.h"
44 #define E_CLIENT_GET_PRIVATE(obj) \
45 (G_TYPE_INSTANCE_GET_PRIVATE \
46 ((obj), E_TYPE_CLIENT, EClientPrivate))
48 typedef struct _AsyncContext AsyncContext;
50 struct _EClientPrivate {
57 GMainContext *main_context;
60 struct _AsyncContext {
64 gboolean only_if_exists;
81 BACKEND_PROPERTY_CHANGED,
85 static guint signals[LAST_SIGNAL];
87 G_DEFINE_ABSTRACT_TYPE (EClient, e_client, G_TYPE_OBJECT)
90 async_context_free (AsyncContext *async_context)
92 g_free (async_context->capabilities);
93 g_free (async_context->prop_name);
94 g_free (async_context->prop_value);
96 g_slice_free (AsyncContext, async_context);
100 * Well-known client backend properties, which are common for each #EClient:
101 * @CLIENT_BACKEND_PROPERTY_OPENED: Is set to "TRUE" or "FALSE" depending
102 * whether the backend is fully opened.
103 * @CLIENT_BACKEND_PROPERTY_OPENING: Is set to "TRUE" or "FALSE" depending
104 * whether the backend is processing its opening phase.
105 * @CLIENT_BACKEND_PROPERTY_ONLINE: Is set to "TRUE" or "FALSE" depending
106 * on the backend's loaded state. See also e_client_is_online().
107 * @CLIENT_BACKEND_PROPERTY_READONLY: Is set to "TRUE" or "FALSE" depending
108 * on the backend's readonly state. See also e_client_is_readonly().
109 * @CLIENT_BACKEND_PROPERTY_CACHE_DIR: Local folder with cached data used
111 * @CLIENT_BACKEND_PROPERTY_CAPABILITIES: Retrieves comma-separated list
112 * of capabilities supported by the backend. Preferred method of retreiving
113 * and working with capabilities is e_client_get_capabilities() and
114 * e_client_check_capability().
117 G_DEFINE_QUARK (e-client-error-quark, e_client_error)
120 * e_client_error_to_string:
122 * FIXME: Document me.
127 e_client_error_to_string (EClientError code)
130 case E_CLIENT_ERROR_INVALID_ARG:
131 return _("Invalid argument");
132 case E_CLIENT_ERROR_BUSY:
133 return _("Backend is busy");
134 case E_CLIENT_ERROR_SOURCE_NOT_LOADED:
135 return _("Source not loaded");
136 case E_CLIENT_ERROR_SOURCE_ALREADY_LOADED:
137 return _("Source already loaded");
138 case E_CLIENT_ERROR_AUTHENTICATION_FAILED:
139 return _("Authentication failed");
140 case E_CLIENT_ERROR_AUTHENTICATION_REQUIRED:
141 return _("Authentication required");
142 case E_CLIENT_ERROR_REPOSITORY_OFFLINE:
143 return _("Repository offline");
144 case E_CLIENT_ERROR_OFFLINE_UNAVAILABLE:
145 /* Translators: This means that the EClient does not
146 * support offline mode, or it's not set to by a user,
147 * thus it is unavailable while user is not connected. */
148 return _("Offline unavailable");
149 case E_CLIENT_ERROR_PERMISSION_DENIED:
150 return _("Permission denied");
151 case E_CLIENT_ERROR_CANCELLED:
152 return _("Cancelled");
153 case E_CLIENT_ERROR_COULD_NOT_CANCEL:
154 return _("Could not cancel");
155 case E_CLIENT_ERROR_NOT_SUPPORTED:
156 return _("Not supported");
157 case E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD:
158 return _("Unsupported authentication method");
159 case E_CLIENT_ERROR_TLS_NOT_AVAILABLE:
160 return _("TLS not available");
161 case E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED:
162 return _("Search size limit exceeded");
163 case E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED:
164 return _("Search time limit exceeded");
165 case E_CLIENT_ERROR_INVALID_QUERY:
166 return _("Invalid query");
167 case E_CLIENT_ERROR_QUERY_REFUSED:
168 return _("Query refused");
169 case E_CLIENT_ERROR_DBUS_ERROR:
170 return _("D-Bus error");
171 case E_CLIENT_ERROR_OTHER_ERROR:
172 return _("Other error");
173 case E_CLIENT_ERROR_NOT_OPENED:
174 return _("Backend is not opened yet");
175 case E_CLIENT_ERROR_OUT_OF_SYNC:
176 return _("Object is out of sync");
179 return _("Unknown error");
183 * e_client_error_create:
184 * @code: an #EClientError code to create
185 * @custom_msg: custom message to use for the error; can be %NULL
187 * Returns: a new #GError containing an E_CLIENT_ERROR of the given
188 * @code. If the @custom_msg is NULL, then the error message is
189 * the one returned from e_client_error_to_string() for the @code,
190 * otherwise the given message is used.
192 * Returned pointer should be freed with g_error_free().
196 * Deprecated: 3.8: Just use the #GError API directly.
199 e_client_error_create (EClientError code,
200 const gchar *custom_msg)
202 if (custom_msg == NULL)
203 custom_msg = e_client_error_to_string (code);
205 return g_error_new_literal (E_CLIENT_ERROR, code, custom_msg);
209 client_set_source (EClient *client,
212 g_return_if_fail (E_IS_SOURCE (source));
213 g_return_if_fail (client->priv->source == NULL);
215 client->priv->source = g_object_ref (source);
219 client_set_property (GObject *object,
224 switch (property_id) {
226 e_client_set_online (
228 g_value_get_boolean (value));
234 g_value_get_object (value));
238 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
242 client_get_property (GObject *object,
247 switch (property_id) {
248 case PROP_CAPABILITIES:
249 g_value_set_pointer (
251 (gpointer) e_client_get_capabilities (
255 case PROP_MAIN_CONTEXT:
258 e_client_ref_main_context (
263 g_value_set_boolean (
270 g_value_set_boolean (
277 g_value_set_boolean (
279 e_client_is_readonly (
286 e_client_get_source (
291 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
295 client_dispose (GObject *object)
297 EClientPrivate *priv;
299 priv = E_CLIENT_GET_PRIVATE (object);
301 if (priv->main_context != NULL) {
302 g_main_context_unref (priv->main_context);
303 priv->main_context = NULL;
306 g_clear_object (&priv->source);
308 /* Chain up to parent's dispose() method. */
309 G_OBJECT_CLASS (e_client_parent_class)->dispose (object);
313 client_finalize (GObject *object)
315 EClientPrivate *priv;
317 priv = E_CLIENT_GET_PRIVATE (object);
319 g_slist_free_full (priv->capabilities, (GDestroyNotify) g_free);
321 g_rec_mutex_clear (&priv->prop_mutex);
323 /* Chain up to parent's finalize() method. */
324 G_OBJECT_CLASS (e_client_parent_class)->finalize (object);
328 client_unwrap_dbus_error (EClient *client,
332 /* This method is deprecated. Make it a no-op. */
334 if (out_error != NULL)
335 *out_error = dbus_error;
338 /* Helper for client_retrieve_capabilities() */
340 client_retrieve_capabilities_thread (GSimpleAsyncResult *simple,
341 GObject *source_object,
342 GCancellable *cancellable)
344 AsyncContext *async_context;
345 GError *error = NULL;
347 async_context = g_simple_async_result_get_op_res_gpointer (simple);
349 e_client_retrieve_capabilities_sync (
350 E_CLIENT (source_object),
351 &async_context->capabilities,
352 cancellable, &error);
355 g_simple_async_result_take_error (simple, error);
359 client_retrieve_capabilities (EClient *client,
360 GCancellable *cancellable,
361 GAsyncReadyCallback callback,
364 GSimpleAsyncResult *simple;
365 AsyncContext *async_context;
367 async_context = g_slice_new0 (AsyncContext);
369 simple = g_simple_async_result_new (
370 G_OBJECT (client), callback,
371 user_data, client_retrieve_capabilities);
373 g_simple_async_result_set_check_cancellable (simple, cancellable);
375 g_simple_async_result_set_op_res_gpointer (
376 simple, async_context, (GDestroyNotify) async_context_free);
378 g_simple_async_result_run_in_thread (
379 simple, client_retrieve_capabilities_thread,
380 G_PRIORITY_DEFAULT, cancellable);
382 g_object_unref (simple);
386 client_retrieve_capabilities_finish (EClient *client,
387 GAsyncResult *result,
388 gchar **capabilities,
391 GSimpleAsyncResult *simple;
392 AsyncContext *async_context;
394 g_return_val_if_fail (
395 g_simple_async_result_is_valid (
396 result, G_OBJECT (client),
397 client_retrieve_capabilities), FALSE);
399 simple = G_SIMPLE_ASYNC_RESULT (result);
400 async_context = g_simple_async_result_get_op_res_gpointer (simple);
402 if (g_simple_async_result_propagate_error (simple, error))
405 g_return_val_if_fail (async_context->capabilities != NULL, FALSE);
407 if (capabilities != NULL) {
408 *capabilities = async_context->capabilities;
409 async_context->capabilities = NULL;
416 client_retrieve_capabilities_sync (EClient *client,
417 gchar **capabilities,
418 GCancellable *cancellable,
421 return e_client_get_backend_property_sync (
422 client, CLIENT_BACKEND_PROPERTY_CAPABILITIES,
423 capabilities, cancellable, error);
426 /* Helper for client_get_backend_property() */
428 client_get_backend_property_thread (GSimpleAsyncResult *simple,
429 GObject *source_object,
430 GCancellable *cancellable)
432 AsyncContext *async_context;
433 GError *error = NULL;
435 async_context = g_simple_async_result_get_op_res_gpointer (simple);
437 e_client_get_backend_property_sync (
438 E_CLIENT (source_object),
439 async_context->prop_name,
440 &async_context->prop_value,
441 cancellable, &error);
444 g_simple_async_result_take_error (simple, error);
448 client_get_backend_property (EClient *client,
449 const gchar *prop_name,
450 GCancellable *cancellable,
451 GAsyncReadyCallback callback,
454 GSimpleAsyncResult *simple;
455 AsyncContext *async_context;
457 async_context = g_slice_new0 (AsyncContext);
458 async_context->prop_name = g_strdup (prop_name);
460 simple = g_simple_async_result_new (
461 G_OBJECT (client), callback,
462 user_data, client_get_backend_property);
464 g_simple_async_result_set_check_cancellable (simple, cancellable);
466 g_simple_async_result_set_op_res_gpointer (
467 simple, async_context, (GDestroyNotify) async_context_free);
469 g_simple_async_result_run_in_thread (
470 simple, client_get_backend_property_thread,
471 G_PRIORITY_DEFAULT, cancellable);
473 g_object_unref (simple);
477 client_get_backend_property_finish (EClient *client,
478 GAsyncResult *result,
482 GSimpleAsyncResult *simple;
483 AsyncContext *async_context;
485 g_return_val_if_fail (
486 g_simple_async_result_is_valid (
487 result, G_OBJECT (client),
488 client_get_backend_property), FALSE);
490 simple = G_SIMPLE_ASYNC_RESULT (result);
491 async_context = g_simple_async_result_get_op_res_gpointer (simple);
493 if (g_simple_async_result_propagate_error (simple, error))
496 g_return_val_if_fail (async_context->prop_value != NULL, FALSE);
498 if (prop_value != NULL) {
499 *prop_value = async_context->prop_value;
500 async_context->prop_value = NULL;
506 /* Helper for client_set_backend_property() */
508 client_set_backend_property_thread (GSimpleAsyncResult *simple,
509 GObject *source_object,
510 GCancellable *cancellable)
512 AsyncContext *async_context;
513 GError *error = NULL;
515 async_context = g_simple_async_result_get_op_res_gpointer (simple);
517 e_client_set_backend_property_sync (
518 E_CLIENT (source_object),
519 async_context->prop_name,
520 async_context->prop_value,
521 cancellable, &error);
524 g_simple_async_result_take_error (simple, error);
528 client_set_backend_property (EClient *client,
529 const gchar *prop_name,
530 const gchar *prop_value,
531 GCancellable *cancellable,
532 GAsyncReadyCallback callback,
535 GSimpleAsyncResult *simple;
536 AsyncContext *async_context;
538 async_context = g_slice_new0 (AsyncContext);
539 async_context->prop_name = g_strdup (prop_name);
540 async_context->prop_value = g_strdup (prop_value);
542 simple = g_simple_async_result_new (
543 G_OBJECT (client), callback,
544 user_data, client_set_backend_property);
546 g_simple_async_result_set_check_cancellable (simple, cancellable);
548 g_simple_async_result_set_op_res_gpointer (
549 simple, async_context, (GDestroyNotify) async_context_free);
551 g_simple_async_result_run_in_thread (
552 simple, client_set_backend_property_thread,
553 G_PRIORITY_DEFAULT, cancellable);
555 g_object_unref (simple);
559 client_set_backend_property_finish (EClient *client,
560 GAsyncResult *result,
563 GSimpleAsyncResult *simple;
565 g_return_val_if_fail (
566 g_simple_async_result_is_valid (
567 result, G_OBJECT (client),
568 client_set_backend_property), FALSE);
570 simple = G_SIMPLE_ASYNC_RESULT (result);
572 /* Assume success unless a GError is set. */
573 return !g_simple_async_result_propagate_error (simple, error);
576 /* Helper for client_open() */
578 client_open_thread (GSimpleAsyncResult *simple,
579 GObject *source_object,
580 GCancellable *cancellable)
582 AsyncContext *async_context;
583 GError *error = NULL;
585 async_context = g_simple_async_result_get_op_res_gpointer (simple);
588 E_CLIENT (source_object),
589 async_context->only_if_exists,
590 cancellable, &error);
593 g_simple_async_result_take_error (simple, error);
597 client_open (EClient *client,
598 gboolean only_if_exists,
599 GCancellable *cancellable,
600 GAsyncReadyCallback callback,
603 GSimpleAsyncResult *simple;
604 AsyncContext *async_context;
606 async_context = g_slice_new0 (AsyncContext);
607 async_context->only_if_exists = only_if_exists;
609 simple = g_simple_async_result_new (
610 G_OBJECT (client), callback, user_data, client_open);
612 g_simple_async_result_set_check_cancellable (simple, cancellable);
614 g_simple_async_result_set_op_res_gpointer (
615 simple, async_context, (GDestroyNotify) async_context_free);
617 g_simple_async_result_run_in_thread (
618 simple, client_open_thread,
619 G_PRIORITY_DEFAULT, cancellable);
621 g_object_unref (simple);
625 client_open_finish (EClient *client,
626 GAsyncResult *result,
629 GSimpleAsyncResult *simple;
631 g_return_val_if_fail (
632 g_simple_async_result_is_valid (
633 result, G_OBJECT (client), client_open), FALSE);
635 simple = G_SIMPLE_ASYNC_RESULT (result);
637 /* Assume success unless a GError is set. */
638 return !g_simple_async_result_propagate_error (simple, error);
641 /* Helper for client_remove() */
643 client_remove_thread (GSimpleAsyncResult *simple,
644 GObject *source_object,
645 GCancellable *cancellable)
647 GError *error = NULL;
649 e_client_remove_sync (
650 E_CLIENT (source_object), cancellable, &error);
653 g_simple_async_result_take_error (simple, error);
657 client_remove (EClient *client,
658 GCancellable *cancellable,
659 GAsyncReadyCallback callback,
662 GSimpleAsyncResult *simple;
664 simple = g_simple_async_result_new (
665 G_OBJECT (client), callback, user_data, client_remove);
667 g_simple_async_result_set_check_cancellable (simple, cancellable);
669 g_simple_async_result_run_in_thread (
670 simple, client_remove_thread,
671 G_PRIORITY_DEFAULT, cancellable);
673 g_object_unref (simple);
677 client_remove_finish (EClient *client,
678 GAsyncResult *result,
681 GSimpleAsyncResult *simple;
683 g_return_val_if_fail (
684 g_simple_async_result_is_valid (
685 result, G_OBJECT (client), client_remove), FALSE);
687 simple = G_SIMPLE_ASYNC_RESULT (result);
689 /* Assume success unless a GError is set. */
690 return !g_simple_async_result_propagate_error (simple, error);
694 client_remove_sync (EClient *client,
695 GCancellable *cancellable,
700 source = e_client_get_source (client);
702 return e_source_remove_sync (source, cancellable, error);
705 /* Helper for client_refresh() */
707 client_refresh_thread (GSimpleAsyncResult *simple,
708 GObject *source_object,
709 GCancellable *cancellable)
711 GError *error = NULL;
713 e_client_refresh_sync (
714 E_CLIENT (source_object), cancellable, &error);
717 g_simple_async_result_take_error (simple, error);
721 client_refresh (EClient *client,
722 GCancellable *cancellable,
723 GAsyncReadyCallback callback,
726 GSimpleAsyncResult *simple;
728 simple = g_simple_async_result_new (
729 G_OBJECT (client), callback, user_data, client_refresh);
731 g_simple_async_result_set_check_cancellable (simple, cancellable);
733 g_simple_async_result_run_in_thread (
734 simple, client_refresh_thread,
735 G_PRIORITY_DEFAULT, cancellable);
737 g_object_unref (simple);
741 client_refresh_finish (EClient *client,
742 GAsyncResult *result,
745 GSimpleAsyncResult *simple;
747 g_return_val_if_fail (
748 g_simple_async_result_is_valid (
749 result, G_OBJECT (client), client_refresh), FALSE);
751 simple = G_SIMPLE_ASYNC_RESULT (result);
753 /* Assume success unless a GError is set. */
754 return !g_simple_async_result_propagate_error (simple, error);
758 e_client_class_init (EClientClass *class)
760 GObjectClass *object_class;
762 g_type_class_add_private (class, sizeof (EClientPrivate));
764 object_class = G_OBJECT_CLASS (class);
765 object_class->set_property = client_set_property;
766 object_class->get_property = client_get_property;
767 object_class->dispose = client_dispose;
768 object_class->finalize = client_finalize;
770 class->unwrap_dbus_error = client_unwrap_dbus_error;
771 class->retrieve_capabilities = client_retrieve_capabilities;
772 class->retrieve_capabilities_finish = client_retrieve_capabilities_finish;
773 class->retrieve_capabilities_sync = client_retrieve_capabilities_sync;
774 class->get_backend_property = client_get_backend_property;
775 class->get_backend_property_finish = client_get_backend_property_finish;
776 class->set_backend_property = client_set_backend_property;
777 class->set_backend_property_finish = client_set_backend_property_finish;
778 class->open = client_open;
779 class->open_finish = client_open_finish;
780 class->remove = client_remove;
781 class->remove_finish = client_remove_finish;
782 class->remove_sync = client_remove_sync;
783 class->refresh = client_refresh;
784 class->refresh_finish = client_refresh_finish;
786 g_object_class_install_property (
789 g_param_spec_pointer (
794 G_PARAM_STATIC_STRINGS));
796 g_object_class_install_property (
802 "The main loop context on "
803 "which to attach event sources",
806 G_PARAM_STATIC_STRINGS));
808 g_object_class_install_property (
811 g_param_spec_boolean (
817 G_PARAM_STATIC_STRINGS));
819 g_object_class_install_property (
822 g_param_spec_boolean (
828 G_PARAM_STATIC_STRINGS));
830 g_object_class_install_property (
833 g_param_spec_boolean (
839 G_PARAM_STATIC_STRINGS));
841 g_object_class_install_property (
844 g_param_spec_object (
850 G_PARAM_CONSTRUCT_ONLY |
851 G_PARAM_STATIC_STRINGS));
856 * Deprecated: 3.8: This signal is no longer emitted.
858 signals[OPENED] = g_signal_new (
860 G_OBJECT_CLASS_TYPE (class),
863 G_STRUCT_OFFSET (EClientClass, opened),
865 g_cclosure_marshal_VOID__BOXED,
869 signals[BACKEND_ERROR] = g_signal_new (
871 G_OBJECT_CLASS_TYPE (class),
873 G_STRUCT_OFFSET (EClientClass, backend_error),
875 g_cclosure_marshal_VOID__STRING,
879 signals[BACKEND_DIED] = g_signal_new (
881 G_OBJECT_CLASS_TYPE (class),
883 G_STRUCT_OFFSET (EClientClass, backend_died),
885 g_cclosure_marshal_VOID__VOID,
888 signals[BACKEND_PROPERTY_CHANGED] = g_signal_new (
889 "backend-property-changed",
890 G_OBJECT_CLASS_TYPE (class),
892 G_STRUCT_OFFSET (EClientClass, backend_property_changed),
894 e_gdbus_marshallers_VOID__STRING_STRING,
895 G_TYPE_NONE, 2, G_TYPE_STRING, G_TYPE_STRING);
899 e_client_init (EClient *client)
901 client->priv = E_CLIENT_GET_PRIVATE (client);
903 client->priv->readonly = TRUE;
904 client->priv->main_context = g_main_context_ref_thread_default ();
906 g_rec_mutex_init (&client->priv->prop_mutex);
910 * e_client_get_source:
911 * @client: an #EClient
913 * Get the #ESource that this client has assigned.
915 * Returns: (transfer none): The source.
920 e_client_get_source (EClient *client)
922 g_return_val_if_fail (E_IS_CLIENT (client), NULL);
924 return client->priv->source;
928 client_ensure_capabilities (EClient *client)
930 gchar *capabilities = NULL;
932 g_return_if_fail (E_IS_CLIENT (client));
934 if (client->priv->capabilities != NULL)
937 /* Despite appearances this function does not actually block. */
938 e_client_get_backend_property_sync (
939 client, CLIENT_BACKEND_PROPERTY_CAPABILITIES,
940 &capabilities, NULL, NULL);
941 e_client_set_capabilities (client, capabilities);
942 g_free (capabilities);
946 * e_client_get_capabilities:
947 * @client: an #EClient
949 * Get list of strings with capabilities advertised by a backend.
950 * This list, together with inner strings, is owned by the @client.
951 * To check for individual capabilities use e_client_check_capability().
953 * Returns: (element-type utf8) (transfer none): #GSList of const strings
959 e_client_get_capabilities (EClient *client)
961 g_return_val_if_fail (E_IS_CLIENT (client), NULL);
963 client_ensure_capabilities (client);
965 return client->priv->capabilities;
969 * e_client_ref_main_context:
970 * @client: an #EClient
972 * Returns the #GMainContext on which event sources for @client are to
975 * The returned #GMainContext is referenced for thread-safety and must be
976 * unreferenced with g_main_context_unref() when finished with it.
978 * Returns: (transfer full): a #GMainContext
983 e_client_ref_main_context (EClient *client)
985 g_return_val_if_fail (E_IS_CLIENT (client), NULL);
987 return g_main_context_ref (client->priv->main_context);
991 * e_client_check_capability:
992 * @client: an #EClient
993 * @capability: a capability
995 * Check if backend supports particular capability.
996 * To get all capabilities use e_client_get_capabilities().
998 * Returns: #GSList of const strings of capabilities
1003 e_client_check_capability (EClient *client,
1004 const gchar *capability)
1008 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1009 g_return_val_if_fail (capability, FALSE);
1011 g_rec_mutex_lock (&client->priv->prop_mutex);
1013 client_ensure_capabilities (client);
1015 for (iter = client->priv->capabilities; iter; iter = g_slist_next (iter)) {
1016 const gchar *cap = iter->data;
1018 if (cap && g_ascii_strcasecmp (cap, capability) == 0) {
1019 g_rec_mutex_unlock (&client->priv->prop_mutex);
1024 g_rec_mutex_unlock (&client->priv->prop_mutex);
1030 * e_client_check_refresh_supported:
1031 * @client: A client.
1033 * Checks whether a client supports explicit refreshing
1034 * (see e_client_refresh()).
1036 * Returns: TRUE if the client supports refreshing, FALSE otherwise.
1041 e_client_check_refresh_supported (EClient *client)
1043 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1045 return e_client_check_capability (client, "refresh-supported");
1048 /* capabilities - comma-separated list of capabilities; can be NULL to unset */
1050 e_client_set_capabilities (EClient *client,
1051 const gchar *capabilities)
1053 g_return_if_fail (E_IS_CLIENT (client));
1055 g_rec_mutex_lock (&client->priv->prop_mutex);
1057 g_slist_foreach (client->priv->capabilities, (GFunc) g_free, NULL);
1058 g_slist_free (client->priv->capabilities);
1059 client->priv->capabilities = e_client_util_parse_comma_strings (capabilities);
1061 g_rec_mutex_unlock (&client->priv->prop_mutex);
1063 g_object_notify (G_OBJECT (client), "capabilities");
1067 * e_client_is_readonly:
1068 * @client: an #EClient
1070 * Check if this @client is read-only.
1072 * Returns: %TRUE if this @client is read-only, otherwise %FALSE.
1077 e_client_is_readonly (EClient *client)
1079 g_return_val_if_fail (E_IS_CLIENT (client), TRUE);
1081 return client->priv->readonly;
1085 e_client_set_readonly (EClient *client,
1088 g_return_if_fail (E_IS_CLIENT (client));
1090 g_rec_mutex_lock (&client->priv->prop_mutex);
1091 if (client->priv->readonly == readonly) {
1092 g_rec_mutex_unlock (&client->priv->prop_mutex);
1096 client->priv->readonly = readonly;
1098 g_rec_mutex_unlock (&client->priv->prop_mutex);
1100 g_object_notify (G_OBJECT (client), "readonly");
1104 * e_client_is_online:
1105 * @client: an #EClient
1107 * Check if this @client is connected.
1109 * Returns: %TRUE if this @client is connected, otherwise %FALSE.
1114 e_client_is_online (EClient *client)
1116 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1118 return client->priv->online;
1122 e_client_set_online (EClient *client,
1125 g_return_if_fail (E_IS_CLIENT (client));
1127 /* newly connected/disconnected => make sure capabilities will be correct */
1128 e_client_set_capabilities (client, NULL);
1130 g_rec_mutex_lock (&client->priv->prop_mutex);
1131 if (client->priv->online == is_online) {
1132 g_rec_mutex_unlock (&client->priv->prop_mutex);
1136 client->priv->online = is_online;
1138 g_rec_mutex_unlock (&client->priv->prop_mutex);
1140 g_object_notify (G_OBJECT (client), "online");
1144 * e_client_is_opened:
1145 * @client: an #EClient
1147 * Check if this @client is fully opened. This includes
1148 * everything from e_client_open() call up to the authentication,
1149 * if required by a backend. Client cannot do any other operation
1150 * during the opening phase except of authenticate or cancel it.
1151 * Every other operation results in an %E_CLIENT_ERROR_BUSY error.
1153 * Returns: always %TRUE
1157 * Deprecated: 3.8: Clients don't need to care if they're fully opened
1158 * anymore. This function always returns %TRUE.
1161 e_client_is_opened (EClient *client)
1163 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1169 * e_client_cancel_all:
1170 * @client: an #EClient
1172 * Cancels all pending operations started on @client.
1176 * Deprecated: 3.8: The function no longer does anything.
1179 e_client_cancel_all (EClient *client)
1185 * e_client_retrieve_capabilities:
1186 * @client: an #EClient
1187 * @cancellable: a #GCancellable; can be %NULL
1188 * @callback: callback to call when a result is ready
1189 * @user_data: user data for the @callback
1191 * Initiates retrieval of capabilities on the @client. This is usually
1192 * required only once, after the @client is opened. The returned value
1193 * is cached and any subsequent call of e_client_get_capabilities() and
1194 * e_client_check_capability() is using the cached value.
1195 * The call is finished by e_client_retrieve_capabilities_finish()
1196 * from the @callback.
1200 * Deprecated: 3.8: Use e_client_get_capabilities() instead.
1203 e_client_retrieve_capabilities (EClient *client,
1204 GCancellable *cancellable,
1205 GAsyncReadyCallback callback,
1208 EClientClass *class;
1210 g_return_if_fail (E_IS_CLIENT (client));
1211 g_return_if_fail (callback != NULL);
1213 class = E_CLIENT_GET_CLASS (client);
1214 g_return_if_fail (class != NULL);
1215 g_return_if_fail (class->retrieve_capabilities != NULL);
1217 class->retrieve_capabilities (client, cancellable, callback, user_data);
1221 * e_client_retrieve_capabilities_finish:
1222 * @client: an #EClient
1223 * @result: a #GAsyncResult
1224 * @capabilities: (out): Comma-separated list of capabilities of the @client
1225 * @error: (out): a #GError to set an error, if any
1227 * Finishes previous call of e_client_retrieve_capabilities().
1228 * Returned value of @capabilities should be freed with g_free(),
1229 * when no longer needed.
1231 * Returns: %TRUE if successful, %FALSE otherwise.
1235 * Deprecated: 3.8: Use e_client_get_capabilities() instead.
1238 e_client_retrieve_capabilities_finish (EClient *client,
1239 GAsyncResult *result,
1240 gchar **capabilities,
1243 EClientClass *class;
1246 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1247 g_return_val_if_fail (capabilities != NULL, FALSE);
1249 class = E_CLIENT_GET_CLASS (client);
1250 g_return_val_if_fail (class != NULL, FALSE);
1251 g_return_val_if_fail (class->retrieve_capabilities_finish != NULL, FALSE);
1253 *capabilities = NULL;
1254 res = class->retrieve_capabilities_finish (
1255 client, result, capabilities, error);
1257 e_client_set_capabilities (client, res ? *capabilities : NULL);
1263 * e_client_retrieve_capabilities_sync:
1264 * @client: an #EClient
1265 * @capabilities: (out): Comma-separated list of capabilities of the @client
1266 * @cancellable: a #GCancellable; can be %NULL
1267 * @error: (out): a #GError to set an error, if any
1269 * Initiates retrieval of capabilities on the @client. This is usually
1270 * required only once, after the @client is opened. The returned value
1271 * is cached and any subsequent call of e_client_get_capabilities() and
1272 * e_client_check_capability() is using the cached value. Returned value
1273 * of @capabilities should be freed with g_free(), when no longer needed.
1275 * Returns: %TRUE if successful, %FALSE otherwise.
1279 * Deprecated: 3.8: Use e_client_get_capabilities() instead.
1282 e_client_retrieve_capabilities_sync (EClient *client,
1283 gchar **capabilities,
1284 GCancellable *cancellable,
1287 EClientClass *class;
1288 gboolean res = FALSE;
1290 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1291 g_return_val_if_fail (capabilities != NULL, FALSE);
1293 class = E_CLIENT_GET_CLASS (client);
1294 g_return_val_if_fail (class != NULL, FALSE);
1295 g_return_val_if_fail (class->retrieve_capabilities_sync != NULL, FALSE);
1297 *capabilities = NULL;
1298 res = class->retrieve_capabilities_sync (
1299 client, capabilities, cancellable, error);
1301 e_client_set_capabilities (client, res ? *capabilities : NULL);
1307 * e_client_get_backend_property:
1308 * @client: an #EClient
1309 * @prop_name: property name, whose value to retrieve; cannot be %NULL
1310 * @cancellable: a #GCancellable; can be %NULL
1311 * @callback: callback to call when a result is ready
1312 * @user_data: user data for the @callback
1314 * Queries @client's backend for a property of name @prop_name.
1315 * The call is finished by e_client_get_backend_property_finish()
1316 * from the @callback.
1321 e_client_get_backend_property (EClient *client,
1322 const gchar *prop_name,
1323 GCancellable *cancellable,
1324 GAsyncReadyCallback callback,
1327 EClientClass *class;
1329 g_return_if_fail (callback != NULL);
1330 g_return_if_fail (E_IS_CLIENT (client));
1331 g_return_if_fail (prop_name != NULL);
1333 class = E_CLIENT_GET_CLASS (client);
1334 g_return_if_fail (class != NULL);
1335 g_return_if_fail (class->get_backend_property != NULL);
1337 class->get_backend_property (
1338 client, prop_name, cancellable, callback, user_data);
1342 * e_client_get_backend_property_finish:
1343 * @client: an #EClient
1344 * @result: a #GAsyncResult
1345 * @prop_value: (out): Retrieved backend property value; cannot be %NULL
1346 * @error: (out): a #GError to set an error, if any
1348 * Finishes previous call of e_client_get_backend_property().
1350 * Returns: %TRUE if successful, %FALSE otherwise.
1355 e_client_get_backend_property_finish (EClient *client,
1356 GAsyncResult *result,
1360 EClientClass *class;
1362 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1363 g_return_val_if_fail (prop_value != NULL, FALSE);
1365 class = E_CLIENT_GET_CLASS (client);
1366 g_return_val_if_fail (class != NULL, FALSE);
1367 g_return_val_if_fail (class->get_backend_property_finish != NULL, FALSE);
1369 return class->get_backend_property_finish (
1370 client, result, prop_value, error);
1374 * e_client_get_backend_property_sync:
1375 * @client: an #EClient
1376 * @prop_name: property name, whose value to retrieve; cannot be %NULL
1377 * @prop_value: (out): Retrieved backend property value; cannot be %NULL
1378 * @cancellable: a #GCancellable; can be %NULL
1379 * @error: (out): a #GError to set an error, if any
1381 * Queries @client's backend for a property of name @prop_name.
1383 * Returns: %TRUE if successful, %FALSE otherwise.
1388 e_client_get_backend_property_sync (EClient *client,
1389 const gchar *prop_name,
1391 GCancellable *cancellable,
1394 EClientClass *class;
1396 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1397 g_return_val_if_fail (prop_name != NULL, FALSE);
1398 g_return_val_if_fail (prop_value != NULL, FALSE);
1400 class = E_CLIENT_GET_CLASS (client);
1401 g_return_val_if_fail (class != NULL, FALSE);
1402 g_return_val_if_fail (class->get_backend_property_sync != NULL, FALSE);
1404 return class->get_backend_property_sync (
1405 client, prop_name, prop_value, cancellable, error);
1409 * e_client_set_backend_property:
1410 * @client: an #EClient
1411 * @prop_name: property name, whose value to change; cannot be %NULL
1412 * @prop_value: property value, to set; cannot be %NULL
1413 * @cancellable: a #GCancellable; can be %NULL
1414 * @callback: callback to call when a result is ready
1415 * @user_data: user data for the @callback
1417 * Sets @client's backend property of name @prop_name
1418 * to value @prop_value. The call is finished
1419 * by e_client_set_backend_property_finish() from the @callback.
1423 * Deprecated: 3.8: Clients cannot set backend properties. Any attempt
1424 * will fail with an %E_CLIENT_ERROR_NOT_SUPPORTED error.
1427 e_client_set_backend_property (EClient *client,
1428 const gchar *prop_name,
1429 const gchar *prop_value,
1430 GCancellable *cancellable,
1431 GAsyncReadyCallback callback,
1434 EClientClass *class;
1436 g_return_if_fail (callback != NULL);
1437 g_return_if_fail (E_IS_CLIENT (client));
1438 g_return_if_fail (prop_name != NULL);
1439 g_return_if_fail (prop_value != NULL);
1441 class = E_CLIENT_GET_CLASS (client);
1442 g_return_if_fail (class != NULL);
1443 g_return_if_fail (class->set_backend_property != NULL);
1445 class->set_backend_property (
1446 client, prop_name, prop_value,
1447 cancellable, callback, user_data);
1451 * e_client_set_backend_property_finish:
1452 * @client: an #EClient
1453 * @result: a #GAsyncResult
1454 * @error: (out): a #GError to set an error, if any
1456 * Finishes previous call of e_client_set_backend_property().
1458 * Returns: %TRUE if successful, %FALSE otherwise.
1462 * Deprecated: 3.8: Clients cannot set backend properties. Any attempt
1463 * will fail with an %E_CLIENT_ERROR_NOT_SUPPORTED error.
1466 e_client_set_backend_property_finish (EClient *client,
1467 GAsyncResult *result,
1470 EClientClass *class;
1472 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1474 class = E_CLIENT_GET_CLASS (client);
1475 g_return_val_if_fail (class != NULL, FALSE);
1476 g_return_val_if_fail (class->set_backend_property_finish != NULL, FALSE);
1478 return class->set_backend_property_finish (client, result, error);
1482 * e_client_set_backend_property_sync:
1483 * @client: an #EClient
1484 * @prop_name: property name, whose value to change; cannot be %NULL
1485 * @prop_value: property value, to set; cannot be %NULL
1486 * @cancellable: a #GCancellable; can be %NULL
1487 * @error: (out): a #GError to set an error, if any
1489 * Sets @client's backend property of name @prop_name
1490 * to value @prop_value.
1492 * Returns: %TRUE if successful, %FALSE otherwise.
1496 * Deprecated: 3.8: Clients cannot set backend properties. Any attempt
1497 * will fail with an %E_CLIENT_ERROR_NOT_SUPPORTED error.
1500 e_client_set_backend_property_sync (EClient *client,
1501 const gchar *prop_name,
1502 const gchar *prop_value,
1503 GCancellable *cancellable,
1506 EClientClass *class;
1508 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1509 g_return_val_if_fail (prop_name != NULL, FALSE);
1510 g_return_val_if_fail (prop_value != NULL, FALSE);
1512 class = E_CLIENT_GET_CLASS (client);
1513 g_return_val_if_fail (class != NULL, FALSE);
1514 g_return_val_if_fail (class->set_backend_property_sync != NULL, FALSE);
1516 return class->set_backend_property_sync (
1517 client, prop_name, prop_value, cancellable, error);
1522 * @client: an #EClient
1523 * @only_if_exists: if %TRUE, fail if this book doesn't already exist,
1524 * otherwise create it first
1525 * @cancellable: a #GCancellable; can be %NULL
1526 * @callback: callback to call when a result is ready
1527 * @user_data: user data for the @callback
1529 * Opens the @client, making it ready for queries and other operations.
1530 * The call is finished by e_client_open_finish() from the @callback.
1534 * Deprecated: 3.8: Use e_book_client_connect() and
1535 * e_book_client_connect_finish() or
1536 * e_cal_client_connect() and
1537 * e_cal_client_connect_finish() instead.
1540 e_client_open (EClient *client,
1541 gboolean only_if_exists,
1542 GCancellable *cancellable,
1543 GAsyncReadyCallback callback,
1546 EClientClass *class;
1548 g_return_if_fail (callback != NULL);
1549 g_return_if_fail (E_IS_CLIENT (client));
1551 class = E_CLIENT_GET_CLASS (client);
1552 g_return_if_fail (class != NULL);
1553 g_return_if_fail (class->open != NULL);
1555 class->open (client, only_if_exists, cancellable, callback, user_data);
1559 * e_client_open_finish:
1560 * @client: an #EClient
1561 * @result: a #GAsyncResult
1562 * @error: (out): a #GError to set an error, if any
1564 * Finishes previous call of e_client_open().
1566 * Returns: %TRUE if successful, %FALSE otherwise.
1570 * Deprecated: 3.8: Use e_book_client_connect() and
1571 * e_book_client_connect_finish() or
1572 * e_cal_client_connect() and
1573 * e_cal_client_connect_finish() instead.
1576 e_client_open_finish (EClient *client,
1577 GAsyncResult *result,
1580 EClientClass *class;
1582 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1584 class = E_CLIENT_GET_CLASS (client);
1585 g_return_val_if_fail (class != NULL, FALSE);
1586 g_return_val_if_fail (class->open_finish != NULL, FALSE);
1588 return class->open_finish (client, result, error);
1592 * e_client_open_sync:
1593 * @client: an #EClient
1594 * @only_if_exists: if %TRUE, fail if this book doesn't already exist,
1595 * otherwise create it first
1596 * @cancellable: a #GCancellable; can be %NULL
1597 * @error: (out): a #GError to set an error, if any
1599 * Opens the @client, making it ready for queries and other operations.
1601 * Returns: %TRUE if successful, %FALSE otherwise.
1605 * Deprecated: 3.8: Use e_book_client_connect_sync() or
1606 * e_cal_client_connect_sync() instead.
1609 e_client_open_sync (EClient *client,
1610 gboolean only_if_exists,
1611 GCancellable *cancellable,
1614 EClientClass *class;
1616 class = E_CLIENT_GET_CLASS (client);
1617 g_return_val_if_fail (class != NULL, FALSE);
1618 g_return_val_if_fail (class->open_sync != NULL, FALSE);
1620 return class->open_sync (client, only_if_exists, cancellable, error);
1625 * @client: an #EClient
1626 * @cancellable: a #GCancellable; can be %NULL
1627 * @callback: callback to call when a result is ready
1628 * @user_data: user data for the @callback
1630 * Removes the backing data for this #EClient. For example, with the file
1631 * backend this deletes the database file. You cannot get it back!
1632 * The call is finished by e_client_remove_finish() from the @callback.
1636 * Deprecated: 3.6: Use e_source_remove() instead.
1639 e_client_remove (EClient *client,
1640 GCancellable *cancellable,
1641 GAsyncReadyCallback callback,
1644 EClientClass *class;
1646 g_return_if_fail (E_IS_CLIENT (client));
1647 g_return_if_fail (callback != NULL);
1649 class = E_CLIENT_GET_CLASS (client);
1650 g_return_if_fail (class != NULL);
1651 g_return_if_fail (class->remove != NULL);
1653 class->remove (client, cancellable, callback, user_data);
1657 * e_client_remove_finish:
1658 * @client: an #EClient
1659 * @result: a #GAsyncResult
1660 * @error: (out): a #GError to set an error, if any
1662 * Finishes previous call of e_client_remove().
1664 * Returns: %TRUE if successful, %FALSE otherwise.
1668 * Deprecated: 3.6: Use e_source_remove_finish() instead.
1671 e_client_remove_finish (EClient *client,
1672 GAsyncResult *result,
1675 EClientClass *class;
1677 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1679 class = E_CLIENT_GET_CLASS (client);
1680 g_return_val_if_fail (class != NULL, FALSE);
1681 g_return_val_if_fail (class->remove_finish != NULL, FALSE);
1683 return class->remove_finish (client, result, error);
1687 * e_client_remove_sync:
1688 * @client: an #EClient
1689 * @cancellable: a #GCancellable; can be %NULL
1690 * @error: (out): a #GError to set an error, if any
1692 * Removes the backing data for this #EClient. For example, with the file
1693 * backend this deletes the database file. You cannot get it back!
1695 * Returns: %TRUE if successful, %FALSE otherwise.
1699 * Deprecated: 3.6: Use e_source_remove_sync() instead.
1702 e_client_remove_sync (EClient *client,
1703 GCancellable *cancellable,
1706 EClientClass *class;
1708 class = E_CLIENT_GET_CLASS (client);
1709 g_return_val_if_fail (class != NULL, FALSE);
1710 g_return_val_if_fail (class->remove_sync != NULL, FALSE);
1712 return class->remove_sync (client, cancellable, error);
1717 * @client: an #EClient
1718 * @cancellable: a #GCancellable; can be %NULL
1719 * @callback: callback to call when a result is ready
1720 * @user_data: user data for the @callback
1722 * Initiates refresh on the @client. Finishing the method doesn't mean
1723 * that the refresh is done, backend only notifies whether it started
1724 * refreshing or not. Use e_client_check_refresh_supported() to check
1725 * whether the backend supports this method.
1726 * The call is finished by e_client_refresh_finish() from the @callback.
1731 e_client_refresh (EClient *client,
1732 GCancellable *cancellable,
1733 GAsyncReadyCallback callback,
1736 EClientClass *class;
1738 g_return_if_fail (E_IS_CLIENT (client));
1739 g_return_if_fail (callback != NULL);
1741 class = E_CLIENT_GET_CLASS (client);
1742 g_return_if_fail (class != NULL);
1743 g_return_if_fail (class->refresh != NULL);
1745 class->refresh (client, cancellable, callback, user_data);
1749 * e_client_refresh_finish:
1750 * @client: an #EClient
1751 * @result: a #GAsyncResult
1752 * @error: (out): a #GError to set an error, if any
1754 * Finishes previous call of e_client_refresh().
1756 * Returns: %TRUE if successful, %FALSE otherwise.
1761 e_client_refresh_finish (EClient *client,
1762 GAsyncResult *result,
1765 EClientClass *class;
1767 g_return_val_if_fail (E_IS_CLIENT (client), FALSE);
1769 class = E_CLIENT_GET_CLASS (client);
1770 g_return_val_if_fail (class != NULL, FALSE);
1771 g_return_val_if_fail (class->refresh_finish != NULL, FALSE);
1773 return class->refresh_finish (client, result, error);
1777 * e_client_refresh_sync:
1778 * @client: an #EClient
1779 * @cancellable: a #GCancellable; can be %NULL
1780 * @error: (out): a #GError to set an error, if any
1782 * Initiates refresh on the @client. Finishing the method doesn't mean
1783 * that the refresh is done, backend only notifies whether it started
1784 * refreshing or not. Use e_client_check_refresh_supported() to check
1785 * whether the backend supports this method.
1787 * Returns: %TRUE if successful, %FALSE otherwise.
1792 e_client_refresh_sync (EClient *client,
1793 GCancellable *cancellable,
1796 EClientClass *class;
1798 class = E_CLIENT_GET_CLASS (client);
1799 g_return_val_if_fail (class != NULL, FALSE);
1800 g_return_val_if_fail (class->refresh_sync != NULL, FALSE);
1802 return class->refresh_sync (client, cancellable, error);
1806 * e_client_util_slist_to_strv:
1807 * @strings: (element-type utf8): a #GSList of strings (const gchar *)
1809 * Convert a list of strings into a %NULL-terminated array of strings.
1811 * Returns: (transfer full): Newly allocated %NULL-terminated array of strings.
1812 * The returned pointer should be freed with g_strfreev().
1814 * Note: Paired function for this is e_client_util_strv_to_slist().
1818 * Deprecated: 3.8: Use e_util_slist_to_strv() instead.
1821 e_client_util_slist_to_strv (const GSList *strings)
1823 return e_util_slist_to_strv (strings);
1827 * e_client_util_strv_to_slist:
1828 * @strv: a %NULL-terminated array of strings (const gchar *)
1830 * Convert a %NULL-terminated array of strings to a list of strings.
1832 * Returns: (transfer full) (element-type utf8): Newly allocated #GSList of
1833 * newly allocated strings. The returned pointer should be freed with
1834 * e_client_util_free_string_slist().
1836 * Note: Paired function for this is e_client_util_slist_to_strv().
1840 * Deprecated: 3.8: Use e_util_strv_to_slist() instead.
1843 e_client_util_strv_to_slist (const gchar * const *strv)
1845 return e_util_strv_to_slist (strv);
1849 * e_client_util_copy_string_slist:
1850 * @copy_to: (element-type utf8) (allow-none): Where to copy; may be %NULL
1851 * @strings: (element-type utf8): #GSList of strings to be copied
1853 * Copies the #GSList of strings to the end of @copy_to.
1855 * Returns: (transfer full) (element-type utf8): New head of @copy_to.
1856 * The returned pointer can be freed with e_client_util_free_string_slist().
1860 * Deprecated: 3.8: Use e_util_copy_string_slist() instead.
1863 e_client_util_copy_string_slist (GSList *copy_to,
1864 const GSList *strings)
1866 return e_util_copy_string_slist (copy_to, strings);
1870 * e_client_util_copy_object_slist:
1871 * @copy_to: (element-type GObject) (allow-none): Where to copy; may be %NULL
1872 * @objects: (element-type GObject): #GSList of #GObject<!-- -->s to be copied
1874 * Copies a #GSList of #GObject<!-- -->s to the end of @copy_to.
1876 * Returns: (transfer full) (element-type GObject): New head of @copy_to.
1877 * The returned pointer can be freed with e_client_util_free_object_slist().
1881 * Deprecated: 3.8: Use e_util_copy_object_slist() instead.
1884 e_client_util_copy_object_slist (GSList *copy_to,
1885 const GSList *objects)
1887 return e_util_copy_object_slist (copy_to, objects);
1891 * e_client_util_free_string_slist:
1892 * @strings: (element-type utf8): a #GSList of strings (gchar *)
1894 * Frees memory previously allocated by e_client_util_strv_to_slist().
1898 * Deprecated: 3.8: Use g_slist_free_full() instead.
1901 e_client_util_free_string_slist (GSList *strings)
1903 e_util_free_string_slist (strings);
1907 * e_client_util_free_object_slist:
1908 * @objects: (element-type GObject): a #GSList of #GObject<!-- -->s
1910 * Calls g_object_unref() on each member of @objects and then frees @objects
1915 * Deprecated: 3.8: Use g_slist_free_full() instead.
1918 e_client_util_free_object_slist (GSList *objects)
1920 e_util_free_object_slist (objects);
1924 * e_client_util_parse_comma_strings:
1925 * @strings: string of comma-separated values
1927 * Parses comma-separated list of values into #GSList.
1929 * Returns: (transfer full) (element-type utf8): Newly allocated #GSList of
1930 * newly allocated strings corresponding to values parsed from @strings.
1931 * Free the returned pointer with e_client_util_free_string_slist().
1936 e_client_util_parse_comma_strings (const gchar *strings)
1938 GSList *strs_slist = NULL;
1939 gchar **strs_strv = NULL;
1942 if (!strings || !*strings)
1945 strs_strv = g_strsplit (strings, ",", -1);
1946 g_return_val_if_fail (strs_strv != NULL, NULL);
1948 for (ii = 0; strs_strv && strs_strv[ii]; ii++) {
1949 gchar *str = g_strstrip (strs_strv[ii]);
1952 strs_slist = g_slist_prepend (strs_slist, g_strdup (str));
1955 g_strfreev (strs_strv);
1957 return g_slist_reverse (strs_slist);
1961 * e_client_unwrap_dbus_error:
1962 * @client: an #EClient
1963 * @dbus_error: a #GError returned bu D-Bus
1964 * @out_error: a #GError variable where to store the result
1966 * Unwraps D-Bus error to local error. @dbus_error is automatically freed.
1967 * @dbus_erorr and @out_error can point to the same variable.
1971 * Deprecated: 3.8: Use g_dbus_error_strip_remote_error() instead.
1974 e_client_unwrap_dbus_error (EClient *client,
1978 EClientClass *class;
1980 g_return_if_fail (E_IS_CLIENT (client));
1982 class = E_CLIENT_GET_CLASS (client);
1983 g_return_if_fail (class != NULL);
1984 g_return_if_fail (class->unwrap_dbus_error != NULL);
1986 if (!dbus_error || !out_error) {
1988 g_error_free (dbus_error);
1990 class->unwrap_dbus_error (client, dbus_error, out_error);
1995 * e_client_util_unwrap_dbus_error:
1996 * @dbus_error: DBus #GError to unwrap
1997 * @client_error: (out): Resulting #GError; can be %NULL
1998 * @known_errors: List of known errors against which try to match
1999 * @known_errors_count: How many items are stored in @known_errors
2000 * @known_errors_domain: Error domain for @known_errors
2001 * @fail_when_none_matched: Whether to fail when none of @known_errors matches
2003 * The function takes a @dbus_error and tries to find a match in @known_errors
2004 * for it, if it is a G_IO_ERROR, G_IO_ERROR_DBUS_ERROR. If it is anything else
2005 * then the @dbus_error is moved to @client_error.
2007 * The @fail_when_none_matched influences behaviour. If it's %TRUE, and none of
2008 * @known_errors matches, or this is not a G_IO_ERROR_DBUS_ERROR, then %FALSE
2009 * is returned and the @client_error is left without change. Otherwise, the
2010 * @fail_when_none_matched is %FALSE, the error is always processed and will
2011 * result in E_CLIENT_ERROR, E_CLIENT_ERROR_OTHER_ERROR if none of @known_error
2014 * Returns: Whether was @dbus_error processed into @client_error.
2016 * Note: The @dbus_error is automatically freed if returned %TRUE.
2020 * Deprecated: 3.8: This function is no longer used.
2023 e_client_util_unwrap_dbus_error (GError *dbus_error,
2024 GError **client_error,
2025 const EClientErrorsList *known_errors,
2026 guint known_errors_count,
2027 GQuark known_errors_domain,
2028 gboolean fail_when_none_matched)
2030 if (!client_error) {
2032 g_error_free (dbus_error);
2037 *client_error = NULL;
2041 if (dbus_error->domain == known_errors_domain) {
2042 *client_error = dbus_error;
2047 if (g_error_matches (dbus_error, G_IO_ERROR, G_IO_ERROR_DBUS_ERROR)) {
2051 name = g_dbus_error_get_remote_error (dbus_error);
2053 for (ii = 0; ii < known_errors_count; ii++) {
2054 if (g_ascii_strcasecmp (known_errors[ii].name, name) == 0) {
2057 g_dbus_error_strip_remote_error (dbus_error);
2058 *client_error = g_error_new_literal (
2059 known_errors_domain,
2060 known_errors[ii].err_code,
2061 dbus_error->message);
2062 g_error_free (dbus_error);
2071 if (fail_when_none_matched)
2074 if (g_error_matches (dbus_error, G_IO_ERROR, G_IO_ERROR_DBUS_ERROR)) {
2075 g_dbus_error_strip_remote_error (dbus_error);
2076 *client_error = g_error_new_literal (
2078 E_CLIENT_ERROR_OTHER_ERROR,
2079 dbus_error->message);
2080 g_error_free (dbus_error);
2082 g_dbus_error_strip_remote_error (dbus_error);
2083 *client_error = dbus_error;