1 /* 2 * e-client.h 3 * 4 * Copyright (C) 2011 Red Hat, Inc. (www.redhat.com) 5 * 6 * This library is free software: you can redistribute it and/or modify it 7 * under the terms of the GNU Lesser General Public License as published by 8 * the Free Software Foundation. 9 * 10 * This library is distributed in the hope that it will be useful, but 11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 13 * for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with this library. If not, see <http://www.gnu.org/licenses/>. 17 * 18 */ 19 20 #if !defined (__LIBEDATASERVER_H_INSIDE__) && !defined (LIBEDATASERVER_COMPILATION) 21 #error "Only <libedataserver/libedataserver.h> should be included directly." 22 #endif 23 24 #ifndef E_CLIENT_H 25 #define E_CLIENT_H 26 27 #include <gio/gio.h> 28 29 #include <libedataserver/e-source.h> 30 31 /* Standard GObject macros */ 32 #define E_TYPE_CLIENT \ 33 (e_client_get_type ()) 34 #define E_CLIENT(obj) \ 35 (G_TYPE_CHECK_INSTANCE_CAST \ 36 ((obj), E_TYPE_CLIENT, EClient)) 37 #define E_CLIENT_CLASS(cls) \ 38 (G_TYPE_CHECK_CLASS_CAST \ 39 ((cls), E_TYPE_CLIENT, EClientClass)) 40 #define E_IS_CLIENT(obj) \ 41 (G_TYPE_CHECK_INSTANCE_TYPE \ 42 ((obj), E_TYPE_CLIENT)) 43 #define E_IS_CLIENT_CLASS(cls) \ 44 (G_TYPE_CHECK_CLASS_TYPE \ 45 ((cls), E_TYPE_CLIENT)) 46 #define E_CLIENT_GET_CLASS(obj) \ 47 (G_TYPE_INSTANCE_GET_CLASS \ 48 ((obj), E_TYPE_CLIENT, EClientClass)) 49 50 /** 51 * CLIENT_BACKEND_PROPERTY_ONLINE: 52 * 53 * The "online" property is "TRUE" when the client is fully opened and 54 * online, "FALSE" at all other times. See also e_client_is_online(). 55 * 56 * Since: 3.2 57 **/ 58 #define CLIENT_BACKEND_PROPERTY_ONLINE "online" 59 60 /** 61 * CLIENT_BACKEND_PROPERTY_READONLY: 62 * 63 * The "online" property is "TRUE" if the backend has only read access 64 * to its data, "FALSE" if the backend can modify its data. See also 65 * e_client_is_readonly(). 66 * 67 * Since: 3.2 68 **/ 69 #define CLIENT_BACKEND_PROPERTY_READONLY "readonly" 70 71 /** 72 * CLIENT_BACKEND_PROPERTY_CACHE_DIR: 73 * 74 * The "cache-dir" property indicates the backend's local directory for 75 * cached data. 76 * 77 * Since: 3.2 78 **/ 79 #define CLIENT_BACKEND_PROPERTY_CACHE_DIR "cache-dir" 80 81 /** 82 * CLIENT_BACKEND_PROPERTY_CAPABILITIES: 83 * 84 * The "capabilities" property is a comma-separated list of capabilities 85 * supported by the backend. The preferred method of retrieving and working 86 * with capabilities is e_client_get_capabilities() and 87 * e_client_check_capability(). 88 * 89 * Since: 3.2 90 **/ 91 #define CLIENT_BACKEND_PROPERTY_CAPABILITIES "capabilities" 92 93 /** 94 * CLIENT_BACKEND_PROPERTY_REVISION: 95 * 96 * The current overall revision string, this can be used as 97 * a quick check to see if data has changed at all since the 98 * last time the revision was observed. 99 * 100 * Since: 3.4 101 **/ 102 #define CLIENT_BACKEND_PROPERTY_REVISION "revision" 103 104 /** 105 * E_CLIENT_ERROR: 106 * 107 * Error domain for #EClient operations. Errors in this domain will be 108 * from the #EClientError enumeration. See #GError for more information 109 * on error domains. 110 * 111 * Since: 3.2 112 **/ 113 #define E_CLIENT_ERROR e_client_error_quark () 114 115 G_BEGIN_DECLS 116 117 /** 118 * EClientError: 119 * @E_CLIENT_ERROR_INVALID_ARG: Invalid argument was used 120 * @E_CLIENT_ERROR_BUSY: The client is busy 121 * @E_CLIENT_ERROR_SOURCE_NOT_LOADED: The source is not loaded 122 * @E_CLIENT_ERROR_SOURCE_ALREADY_LOADED: The source is already loaded 123 * @E_CLIENT_ERROR_AUTHENTICATION_FAILED: Authentication failed 124 * @E_CLIENT_ERROR_AUTHENTICATION_REQUIRED: Authentication required 125 * @E_CLIENT_ERROR_REPOSITORY_OFFLINE: The repository (client) is offline 126 * @E_CLIENT_ERROR_OFFLINE_UNAVAILABLE: The operation is unavailable in offline mode 127 * @E_CLIENT_ERROR_PERMISSION_DENIED: Permission denied for the operation 128 * @E_CLIENT_ERROR_CANCELLED: The operation was cancelled 129 * @E_CLIENT_ERROR_COULD_NOT_CANCEL: The operation cannot be cancelled 130 * @E_CLIENT_ERROR_NOT_SUPPORTED: The operation is not supported 131 * @E_CLIENT_ERROR_TLS_NOT_AVAILABLE: TLS is not available 132 * @E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD: Requested authentication method is not supported 133 * @E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED: Search size limit exceeded 134 * @E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED: Search time limit exceeded 135 * @E_CLIENT_ERROR_INVALID_QUERY: The query was invalid 136 * @E_CLIENT_ERROR_QUERY_REFUSED: The query was refused by the server side 137 * @E_CLIENT_ERROR_DBUS_ERROR: A D-Bus error occurred 138 * @E_CLIENT_ERROR_OTHER_ERROR: Other error 139 * @E_CLIENT_ERROR_NOT_OPENED: The client is not opened 140 * @E_CLIENT_ERROR_OUT_OF_SYNC: The client is out of sync with the server 141 * 142 * Error codes for #EClient operations. 143 * 144 * Since: 3.2 145 **/ 146 typedef enum { 147 E_CLIENT_ERROR_INVALID_ARG, 148 E_CLIENT_ERROR_BUSY, 149 E_CLIENT_ERROR_SOURCE_NOT_LOADED, 150 E_CLIENT_ERROR_SOURCE_ALREADY_LOADED, 151 E_CLIENT_ERROR_AUTHENTICATION_FAILED, 152 E_CLIENT_ERROR_AUTHENTICATION_REQUIRED, 153 E_CLIENT_ERROR_REPOSITORY_OFFLINE, 154 E_CLIENT_ERROR_OFFLINE_UNAVAILABLE, 155 E_CLIENT_ERROR_PERMISSION_DENIED, 156 E_CLIENT_ERROR_CANCELLED, 157 E_CLIENT_ERROR_COULD_NOT_CANCEL, 158 E_CLIENT_ERROR_NOT_SUPPORTED, 159 E_CLIENT_ERROR_TLS_NOT_AVAILABLE, 160 E_CLIENT_ERROR_UNSUPPORTED_AUTHENTICATION_METHOD, 161 E_CLIENT_ERROR_SEARCH_SIZE_LIMIT_EXCEEDED, 162 E_CLIENT_ERROR_SEARCH_TIME_LIMIT_EXCEEDED, 163 E_CLIENT_ERROR_INVALID_QUERY, 164 E_CLIENT_ERROR_QUERY_REFUSED, 165 E_CLIENT_ERROR_DBUS_ERROR, 166 E_CLIENT_ERROR_OTHER_ERROR, 167 E_CLIENT_ERROR_NOT_OPENED, 168 E_CLIENT_ERROR_OUT_OF_SYNC 169 } EClientError; 170 171 GQuark e_client_error_quark (void) G_GNUC_CONST; 172 const gchar * e_client_error_to_string (EClientError code); 173 GError * e_client_error_create (EClientError code, 174 const gchar *custom_msg); 175 GError * e_client_error_create_fmt (EClientError code, 176 const gchar *format, 177 ...) G_GNUC_PRINTF (2, 3); 178 179 /** 180 * EClient: 181 * 182 * Contains only private data that should be read and manipulated using the 183 * functions below. 184 * 185 * Since: 3.2 186 **/ 187 typedef struct _EClient EClient; 188 typedef struct _EClientClass EClientClass; 189 typedef struct _EClientPrivate EClientPrivate; 190 191 struct _EClient { 192 /*< private >*/ 193 GObject parent; 194 EClientPrivate *priv; 195 }; 196 197 struct _EClientClass { 198 /*< private >*/ 199 GObjectClass parent; 200 201 /* This method is deprecated. */ 202 GDBusProxy * (*get_dbus_proxy) (EClient *client); 203 204 /* This method is deprecated. */ 205 void (*unwrap_dbus_error) (EClient *client, 206 GError *dbus_error, 207 GError **out_error); 208 209 /* This method is deprecated. */ 210 void (*retrieve_capabilities) 211 (EClient *client, 212 GCancellable *cancellable, 213 GAsyncReadyCallback callback, 214 gpointer user_data); 215 gboolean (*retrieve_capabilities_finish) 216 (EClient *client, 217 GAsyncResult *result, 218 gchar **capabilities, 219 GError **error); 220 gboolean (*retrieve_capabilities_sync) 221 (EClient *client, 222 gchar **capabilities, 223 GCancellable *cancellable, 224 GError **error); 225 226 void (*get_backend_property) (EClient *client, 227 const gchar *prop_name, 228 GCancellable *cancellable, 229 GAsyncReadyCallback callback, 230 gpointer user_data); 231 gboolean (*get_backend_property_finish) 232 (EClient *client, 233 GAsyncResult *result, 234 gchar **prop_value, 235 GError **error); 236 gboolean (*get_backend_property_sync) 237 (EClient *client, 238 const gchar *prop_name, 239 gchar **prop_value, 240 GCancellable *cancellable, 241 GError **error); 242 243 /* This method is deprecated. */ 244 void (*set_backend_property) (EClient *client, 245 const gchar *prop_name, 246 const gchar *prop_value, 247 GCancellable *cancellable, 248 GAsyncReadyCallback callback, 249 gpointer user_data); 250 gboolean (*set_backend_property_finish) 251 (EClient *client, 252 GAsyncResult *result, 253 GError **error); 254 gboolean (*set_backend_property_sync) 255 (EClient *client, 256 const gchar *prop_name, 257 const gchar *prop_value, 258 GCancellable *cancellable, 259 GError **error); 260 261 void (*open) (EClient *client, 262 gboolean only_if_exists, 263 GCancellable *cancellable, 264 GAsyncReadyCallback callback, 265 gpointer user_data); 266 gboolean (*open_finish) (EClient *client, 267 GAsyncResult *result, 268 GError **error); 269 gboolean (*open_sync) (EClient *client, 270 gboolean only_if_exists, 271 GCancellable *cancellable, 272 GError **error); 273 274 void (*remove) (EClient *client, 275 GCancellable *cancellable, 276 GAsyncReadyCallback callback, 277 gpointer user_data); 278 gboolean (*remove_finish) (EClient *client, 279 GAsyncResult *result, 280 GError **error); 281 gboolean (*remove_sync) (EClient *client, 282 GCancellable *cancellable, 283 GError **error); 284 285 void (*refresh) (EClient *client, 286 GCancellable *cancellable, 287 GAsyncReadyCallback callback, 288 gpointer user_data); 289 gboolean (*refresh_finish) (EClient *client, 290 GAsyncResult *result, 291 GError **error); 292 gboolean (*refresh_sync) (EClient *client, 293 GCancellable *cancellable, 294 GError **error); 295 gboolean (*retrieve_properties_sync) 296 (EClient *client, 297 GCancellable *cancellable, 298 GError **error); 299 300 void (*opened) (EClient *client, 301 const GError *error); 302 void (*backend_error) (EClient *client, 303 const gchar *error_msg); 304 void (*backend_died) (EClient *client); 305 void (*backend_property_changed) 306 (EClient *client, 307 const gchar *prop_name, 308 const gchar *prop_value); 309 }; 310 311 GType e_client_get_type (void) G_GNUC_CONST; 312 313 ESource * e_client_get_source (EClient *client); 314 const GSList * e_client_get_capabilities (EClient *client); 315 GMainContext * e_client_ref_main_context (EClient *client); 316 gboolean e_client_check_capability (EClient *client, 317 const gchar *capability); 318 gboolean e_client_check_refresh_supported 319 (EClient *client); 320 gboolean e_client_is_readonly (EClient *client); 321 gboolean e_client_is_online (EClient *client); 322 323 void e_client_get_backend_property (EClient *client, 324 const gchar *prop_name, 325 GCancellable *cancellable, 326 GAsyncReadyCallback callback, 327 gpointer user_data); 328 gboolean e_client_get_backend_property_finish 329 (EClient *client, 330 GAsyncResult *result, 331 gchar **prop_value, 332 GError **error); 333 gboolean e_client_get_backend_property_sync 334 (EClient *client, 335 const gchar *prop_name, 336 gchar **prop_value, 337 GCancellable *cancellable, 338 GError **error); 339 340 void e_client_refresh (EClient *client, 341 GCancellable *cancellable, 342 GAsyncReadyCallback callback, 343 gpointer user_data); 344 gboolean e_client_refresh_finish (EClient *client, 345 GAsyncResult *result, 346 GError **error); 347 gboolean e_client_refresh_sync (EClient *client, 348 GCancellable *cancellable, 349 GError **error); 350 351 void e_client_wait_for_connected (EClient *client, 352 guint32 timeout_seconds, 353 GCancellable *cancellable, 354 GAsyncReadyCallback callback, 355 gpointer user_data); 356 gboolean e_client_wait_for_connected_finish 357 (EClient *client, 358 GAsyncResult *result, 359 GError **error); 360 gboolean e_client_wait_for_connected_sync(EClient *client, 361 guint32 timeout_seconds, 362 GCancellable *cancellable, 363 GError **error); 364 365 GSList * e_client_util_parse_comma_strings 366 (const gchar *strings); 367 368 #ifndef EDS_DISABLE_DEPRECATED 369 /** 370 * CLIENT_BACKEND_PROPERTY_OPENED: 371 * 372 * The "opened" property is "TRUE" when the client is fully opened, 373 * "FALSE" at all other times. 374 * 375 * Since: 3.2 376 * 377 * Deprecated: 3.8: Clients don't need to care if they're fully opened 378 * anymore. This property will always return %TRUE. 379 **/ 380 #define CLIENT_BACKEND_PROPERTY_OPENED "opened" 381 382 /** 383 * CLIENT_BACKEND_PROPERTY_OPENING: 384 * 385 * The "opening" property is "TRUE" when the client is in the process of 386 * opening, "FALSE" at all other times. 387 * 388 * Since: 3.2 389 * 390 * Deprecated: 3.8: Clients don't need to care if they're fully opened 391 * anymore. This property will always return %FALSE. 392 **/ 393 #define CLIENT_BACKEND_PROPERTY_OPENING "opening" 394 395 gboolean e_client_is_opened (EClient *client); 396 void e_client_cancel_all (EClient *client); 397 void e_client_unwrap_dbus_error (EClient *client, 398 GError *dbus_error, 399 GError **out_error); 400 void e_client_retrieve_capabilities (EClient *client, 401 GCancellable *cancellable, 402 GAsyncReadyCallback callback, 403 gpointer user_data); 404 gboolean e_client_retrieve_capabilities_finish 405 (EClient *client, 406 GAsyncResult *result, 407 gchar **capabilities, 408 GError **error); 409 gboolean e_client_retrieve_capabilities_sync 410 (EClient *client, 411 gchar **capabilities, 412 GCancellable *cancellable, 413 GError **error); 414 void e_client_set_backend_property (EClient *client, 415 const gchar *prop_name, 416 const gchar *prop_value, 417 GCancellable *cancellable, 418 GAsyncReadyCallback callback, 419 gpointer user_data); 420 gboolean e_client_set_backend_property_finish 421 (EClient *client, 422 GAsyncResult *result, 423 GError **error); 424 gboolean e_client_set_backend_property_sync 425 (EClient *client, 426 const gchar *prop_name, 427 const gchar *prop_value, 428 GCancellable *cancellable, 429 GError **error); 430 void e_client_open (EClient *client, 431 gboolean only_if_exists, 432 GCancellable *cancellable, 433 GAsyncReadyCallback callback, 434 gpointer user_data); 435 gboolean e_client_open_finish (EClient *client, 436 GAsyncResult *result, 437 GError **error); 438 gboolean e_client_open_sync (EClient *client, 439 gboolean only_if_exists, 440 GCancellable *cancellable, 441 GError **error); 442 void e_client_remove (EClient *client, 443 GCancellable *cancellable, 444 GAsyncReadyCallback callback, 445 gpointer user_data); 446 gboolean e_client_remove_finish (EClient *client, 447 GAsyncResult *result, 448 GError **error); 449 gboolean e_client_remove_sync (EClient *client, 450 GCancellable *cancellable, 451 GError **error); 452 gboolean e_client_retrieve_properties_sync 453 (EClient *client, 454 GCancellable *cancellable, 455 GError **error); 456 void e_client_retrieve_properties (EClient *client, 457 GCancellable *cancellable, 458 GAsyncReadyCallback callback, 459 gpointer user_data); 460 gboolean e_client_retrieve_properties_finish 461 (EClient *client, 462 GAsyncResult *result, 463 GError **error); 464 gchar ** e_client_util_slist_to_strv (const GSList *strings); 465 GSList * e_client_util_strv_to_slist (const gchar * const *strv); 466 GSList * e_client_util_copy_string_slist (GSList *copy_to, 467 const GSList *strings); 468 GSList * e_client_util_copy_object_slist (GSList *copy_to, 469 const GSList *objects); 470 void e_client_util_free_string_slist (GSList *strings); 471 void e_client_util_free_object_slist (GSList *objects); 472 gchar * e_client_dup_bus_name (EClient *client); 473 void e_client_set_bus_name (EClient *client, 474 const gchar *bus_name); 475 476 477 typedef struct _EClientErrorsList EClientErrorsList; 478 479 /** 480 * EClientErrorsList: 481 * 482 * Since: 3.2 483 * 484 * Deprecated: 3.8: This structure is no longer used. 485 **/ 486 struct _EClientErrorsList { 487 /*< private >*/ 488 const gchar *name; 489 gint err_code; 490 }; 491 492 gboolean e_client_util_unwrap_dbus_error (GError *dbus_error, 493 GError **client_error, 494 const EClientErrorsList *known_errors, 495 guint known_errors_count, 496 GQuark known_errors_domain, 497 gboolean fail_when_none_matched); 498 499 #endif /* EDS_DISABLE_DEPRECATED */ 500 501 G_END_DECLS 502 503 #endif /* E_CLIENT_H */ 504