1 /* 2 * e-book-backend.h 3 * 4 * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com) 5 * Copyright (C) 2012 Intel Corporation 6 * 7 * This library is free software: you can redistribute it and/or modify it 8 * under the terms of the GNU Lesser General Public License as published by 9 * the Free Software Foundation. 10 * 11 * This library is distributed in the hope that it will be useful, but 12 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 13 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 14 * for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public License 17 * along with this library. If not, see <http://www.gnu.org/licenses/>. 18 * 19 * Authors: Nat Friedman (nat@ximian.com) 20 * Tristan Van Berkom <tristanvb@openismus.com> 21 */ 22 23 #if !defined (__LIBEDATA_BOOK_H_INSIDE__) && !defined (LIBEDATA_BOOK_COMPILATION) 24 #error "Only <libedata-book/libedata-book.h> should be included directly." 25 #endif 26 27 #ifndef E_BOOK_BACKEND_H 28 #define E_BOOK_BACKEND_H 29 30 #include <libebook-contacts/libebook-contacts.h> 31 #include <libebackend/libebackend.h> 32 33 #include <libedata-book/e-data-book.h> 34 #include <libedata-book/e-data-book-cursor.h> 35 #include <libedata-book/e-data-book-direct.h> 36 #include <libedata-book/e-data-book-view.h> 37 38 /* Standard GObject macros */ 39 #define E_TYPE_BOOK_BACKEND \ 40 (e_book_backend_get_type ()) 41 #define E_BOOK_BACKEND(obj) \ 42 (G_TYPE_CHECK_INSTANCE_CAST \ 43 ((obj), E_TYPE_BOOK_BACKEND, EBookBackend)) 44 #define E_BOOK_BACKEND_CLASS(cls) \ 45 (G_TYPE_CHECK_CLASS_CAST \ 46 ((cls), E_TYPE_BOOK_BACKEND, EBookBackendClass)) 47 #define E_IS_BOOK_BACKEND(obj) \ 48 (G_TYPE_CHECK_INSTANCE_TYPE \ 49 ((obj), E_TYPE_BOOK_BACKEND)) 50 #define E_IS_BOOK_BACKEND_CLASS(cls) \ 51 (G_TYPE_CHECK_CLASS_TYPE \ 52 ((cls), E_TYPE_BOOK_BACKEND)) 53 #define E_BOOK_BACKEND_GET_CLASS(obj) \ 54 (G_TYPE_INSTANCE_GET_CLASS \ 55 ((obj), E_TYPE_BOOK_BACKEND, EBookBackendClass)) 56 57 G_BEGIN_DECLS 58 59 typedef struct _EBookBackend EBookBackend; 60 typedef struct _EBookBackendClass EBookBackendClass; 61 typedef struct _EBookBackendPrivate EBookBackendPrivate; 62 63 /** 64 * EBookBackend: 65 * 66 * Contains only private data that should be read and manipulated using the 67 * functions below. 68 */ 69 struct _EBookBackend { 70 /*< private >*/ 71 EBackend parent; 72 EBookBackendPrivate *priv; 73 }; 74 75 /** 76 * EBookBackendClass: 77 * @use_serial_dispatch_queue: Whether a serial dispatch queue should 78 * be used for this backend or not. The default is %TRUE. 79 * @impl_get_backend_property: Fetch a property value by name from the backend 80 * @impl_open: Open the backend 81 * @impl_refresh: Refresh the backend 82 * @impl_create_contacts: Add and store the passed vcards 83 * @impl_modify_contacts: Modify the existing contacts using the passed vcards 84 * @impl_remove_contacts: Remove the contacts specified by the passed UIDs 85 * @impl_get_contact: Fetch a contact by UID 86 * @impl_get_contact_list: Fetch a list of contacts based on a search expression 87 * @impl_get_contact_list_uids: Fetch a list of contact UIDs based on a search expression 88 * @impl_start_view: Start up the specified view 89 * @impl_stop_view: Stop the specified view 90 * @impl_notify_update: Notify changes which might have occured for a given contact 91 * @impl_get_direct_book: For addressbook backends which support Direct Read Access, 92 * report some information on how to access the addressbook persistance directly 93 * @impl_configure_direct: For addressbook backends which support Direct Read Access, configure a 94 * backend instantiated on the client side for Direct Read Access, using data 95 * reported from the server via the @get_direct_book method. 96 * @impl_set_locale: Store & remember the passed locale setting 97 * @impl_dup_locale: Return the currently set locale setting (must be a string duplicate, for thread safety). 98 * @impl_create_cursor: Create an #EDataBookCursor 99 * @impl_delete_cursor: Delete an #EDataBookCursor previously created by this backend 100 * @closed: A signal notifying that the backend was closed 101 * @shutdown: A signal notifying that the backend is being shut down 102 * 103 * Class structure for the #EBookBackend class. 104 * 105 * These virtual methods must be implemented when writing 106 * an addressbook backend. 107 */ 108 struct _EBookBackendClass { 109 /*< private >*/ 110 EBackendClass parent_class; 111 112 /*< public >*/ 113 114 /* Set this to TRUE to use a serial dispatch queue, instead 115 * of a concurrent dispatch queue. A serial dispatch queue 116 * executes one method at a time in the order in which they 117 * were called. This is generally slower than a concurrent 118 * dispatch queue, but helps avoid thread-safety issues. */ 119 gboolean use_serial_dispatch_queue; 120 121 gchar * (*impl_get_backend_property) 122 (EBookBackend *backend, 123 const gchar *prop_name); 124 125 void (*impl_open) (EBookBackend *backend, 126 EDataBook *book, 127 guint32 opid, 128 GCancellable *cancellable); 129 void (*impl_refresh) (EBookBackend *backend, 130 EDataBook *book, 131 guint32 opid, 132 GCancellable *cancellable); 133 void (*impl_create_contacts) (EBookBackend *backend, 134 EDataBook *book, 135 guint32 opid, 136 GCancellable *cancellable, 137 const gchar * const *vcards, 138 guint32 opflags); /* bit-or of EBookOperationFlags */ 139 void (*impl_modify_contacts) (EBookBackend *backend, 140 EDataBook *book, 141 guint32 opid, 142 GCancellable *cancellable, 143 const gchar * const *vcards, 144 guint32 opflags); /* bit-or of EBookOperationFlags */ 145 void (*impl_remove_contacts) (EBookBackend *backend, 146 EDataBook *book, 147 guint32 opid, 148 GCancellable *cancellable, 149 const gchar * const *uids, 150 guint32 opflags); /* bit-or of EBookOperationFlags */ 151 void (*impl_get_contact) (EBookBackend *backend, 152 EDataBook *book, 153 guint32 opid, 154 GCancellable *cancellable, 155 const gchar *id); 156 void (*impl_get_contact_list)(EBookBackend *backend, 157 EDataBook *book, 158 guint32 opid, 159 GCancellable *cancellable, 160 const gchar *query); 161 void (*impl_get_contact_list_uids) 162 (EBookBackend *backend, 163 EDataBook *book, 164 guint32 opid, 165 GCancellable *cancellable, 166 const gchar *query); 167 168 void (*impl_start_view) (EBookBackend *backend, 169 EDataBookView *view); 170 void (*impl_stop_view) (EBookBackend *backend, 171 EDataBookView *view); 172 173 void (*impl_notify_update) (EBookBackend *backend, 174 const EContact *contact); 175 176 EDataBookDirect * 177 (*impl_get_direct_book) (EBookBackend *backend); 178 void (*impl_configure_direct)(EBookBackend *backend, 179 const gchar *config); 180 181 gboolean (*impl_set_locale) (EBookBackend *backend, 182 const gchar *locale, 183 GCancellable *cancellable, 184 GError **error); 185 gchar * (*impl_dup_locale) (EBookBackend *backend); 186 EDataBookCursor * 187 (*impl_create_cursor) (EBookBackend *backend, 188 EContactField *sort_fields, 189 EBookCursorSortType *sort_types, 190 guint n_fields, 191 GError **error); 192 gboolean (*impl_delete_cursor) (EBookBackend *backend, 193 EDataBookCursor *cursor, 194 GError **error); 195 196 /* Signals */ 197 void (*closed) (EBookBackend *backend, 198 const gchar *sender); 199 void (*shutdown) (EBookBackend *backend); 200 201 /* Padding for future expansion */ 202 gpointer reserved_padding[20]; 203 }; 204 205 GType e_book_backend_get_type (void) G_GNUC_CONST; 206 207 const gchar * e_book_backend_get_cache_dir (EBookBackend *backend); 208 gchar * e_book_backend_dup_cache_dir (EBookBackend *backend); 209 void e_book_backend_set_cache_dir (EBookBackend *backend, 210 const gchar *cache_dir); 211 EDataBook * e_book_backend_ref_data_book (EBookBackend *backend); 212 void e_book_backend_set_data_book (EBookBackend *backend, 213 EDataBook *data_book); 214 GProxyResolver * 215 e_book_backend_ref_proxy_resolver 216 (EBookBackend *backend); 217 ESourceRegistry * 218 e_book_backend_get_registry (EBookBackend *backend); 219 gboolean e_book_backend_get_writable (EBookBackend *backend); 220 void e_book_backend_set_writable (EBookBackend *backend, 221 gboolean writable); 222 223 gboolean e_book_backend_is_opened (EBookBackend *backend); 224 gboolean e_book_backend_is_readonly (EBookBackend *backend); 225 226 gchar * e_book_backend_get_backend_property 227 (EBookBackend *backend, 228 const gchar *prop_name); 229 gboolean e_book_backend_open_sync (EBookBackend *backend, 230 GCancellable *cancellable, 231 GError **error); 232 void e_book_backend_open (EBookBackend *backend, 233 GCancellable *cancellable, 234 GAsyncReadyCallback callback, 235 gpointer user_data); 236 gboolean e_book_backend_open_finish (EBookBackend *backend, 237 GAsyncResult *result, 238 GError **error); 239 gboolean e_book_backend_refresh_sync (EBookBackend *backend, 240 GCancellable *cancellable, 241 GError **error); 242 void e_book_backend_refresh (EBookBackend *backend, 243 GCancellable *cancellable, 244 GAsyncReadyCallback callback, 245 gpointer user_data); 246 gboolean e_book_backend_refresh_finish (EBookBackend *backend, 247 GAsyncResult *result, 248 GError **error); 249 gboolean e_book_backend_create_contacts_sync 250 (EBookBackend *backend, 251 const gchar * const *vcards, 252 guint32 opflags, /* bit-or of EBookOperationFlags */ 253 GQueue *out_contacts, 254 GCancellable *cancellable, 255 GError **error); 256 void e_book_backend_create_contacts (EBookBackend *backend, 257 const gchar * const *vcards, 258 guint32 opflags, /* bit-or of EBookOperationFlags */ 259 GCancellable *cancellable, 260 GAsyncReadyCallback callback, 261 gpointer user_data); 262 gboolean e_book_backend_create_contacts_finish 263 (EBookBackend *backend, 264 GAsyncResult *result, 265 GQueue *out_contacts, 266 GError **error); 267 gboolean e_book_backend_modify_contacts_sync 268 (EBookBackend *backend, 269 const gchar * const *vcards, 270 guint32 opflags, /* bit-or of EBookOperationFlags */ 271 GCancellable *cancellable, 272 GError **error); 273 void e_book_backend_modify_contacts (EBookBackend *backend, 274 const gchar * const *vcards, 275 guint32 opflags, /* bit-or of EBookOperationFlags */ 276 GCancellable *cancellable, 277 GAsyncReadyCallback callback, 278 gpointer user_data); 279 gboolean e_book_backend_modify_contacts_finish 280 (EBookBackend *backend, 281 GAsyncResult *result, 282 GError **error); 283 gboolean e_book_backend_remove_contacts_sync 284 (EBookBackend *backend, 285 const gchar * const *uids, 286 guint32 opflags, /* bit-or of EBookOperationFlags */ 287 GCancellable *cancellable, 288 GError **error); 289 void e_book_backend_remove_contacts (EBookBackend *backend, 290 const gchar * const *uids, 291 guint32 opflags, /* bit-or of EBookOperationFlags */ 292 GCancellable *cancellable, 293 GAsyncReadyCallback callback, 294 gpointer user_data); 295 gboolean e_book_backend_remove_contacts_finish 296 (EBookBackend *backend, 297 GAsyncResult *result, 298 GError **error); 299 EContact * e_book_backend_get_contact_sync (EBookBackend *backend, 300 const gchar *uid, 301 GCancellable *cancellable, 302 GError **error); 303 void e_book_backend_get_contact (EBookBackend *backend, 304 const gchar *uid, 305 GCancellable *cancellable, 306 GAsyncReadyCallback callback, 307 gpointer user_data); 308 EContact * e_book_backend_get_contact_finish 309 (EBookBackend *backend, 310 GAsyncResult *result, 311 GError **error); 312 gboolean e_book_backend_get_contact_list_sync 313 (EBookBackend *backend, 314 const gchar *query, 315 GQueue *out_contacts, 316 GCancellable *cancellable, 317 GError **error); 318 void e_book_backend_get_contact_list (EBookBackend *backend, 319 const gchar *query, 320 GCancellable *cancellable, 321 GAsyncReadyCallback callback, 322 gpointer user_data); 323 gboolean e_book_backend_get_contact_list_finish 324 (EBookBackend *backend, 325 GAsyncResult *result, 326 GQueue *out_contacts, 327 GError **error); 328 gboolean e_book_backend_get_contact_list_uids_sync 329 (EBookBackend *backend, 330 const gchar *query, 331 GQueue *out_uids, 332 GCancellable *cancellable, 333 GError **error); 334 void e_book_backend_get_contact_list_uids 335 (EBookBackend *backend, 336 const gchar *query, 337 GCancellable *cancellable, 338 GAsyncReadyCallback callback, 339 gpointer user_data); 340 gboolean e_book_backend_get_contact_list_uids_finish 341 (EBookBackend *backend, 342 GAsyncResult *result, 343 GQueue *out_uids, 344 GError **error); 345 346 void e_book_backend_start_view (EBookBackend *backend, 347 EDataBookView *view); 348 void e_book_backend_stop_view (EBookBackend *backend, 349 EDataBookView *view); 350 void e_book_backend_add_view (EBookBackend *backend, 351 EDataBookView *view); 352 void e_book_backend_remove_view (EBookBackend *backend, 353 EDataBookView *view); 354 GList * e_book_backend_list_views (EBookBackend *backend); 355 356 typedef gboolean (*EBookBackendForeachViewFunc) (EBookBackend *backend, 357 EDataBookView *view, 358 gpointer user_data); 359 360 gboolean e_book_backend_foreach_view (EBookBackend *backend, 361 EBookBackendForeachViewFunc func, 362 gpointer user_data); 363 void e_book_backend_foreach_view_notify_progress 364 (EBookBackend *backend, 365 gboolean only_completed_views, 366 gint percent, 367 const gchar *message); 368 369 void e_book_backend_notify_update (EBookBackend *backend, 370 const EContact *contact); 371 void e_book_backend_notify_remove (EBookBackend *backend, 372 const gchar *id); 373 void e_book_backend_notify_complete (EBookBackend *backend); 374 375 void e_book_backend_notify_error (EBookBackend *backend, 376 const gchar *message); 377 void e_book_backend_notify_property_changed 378 (EBookBackend *backend, 379 const gchar *prop_name, 380 const gchar *prop_value); 381 382 EDataBookDirect * 383 e_book_backend_get_direct_book (EBookBackend *backend); 384 void e_book_backend_configure_direct (EBookBackend *backend, 385 const gchar *config); 386 387 void e_book_backend_sync (EBookBackend *backend); 388 389 gboolean e_book_backend_set_locale (EBookBackend *backend, 390 const gchar *locale, 391 GCancellable *cancellable, 392 GError **error); 393 gchar * e_book_backend_dup_locale (EBookBackend *backend); 394 395 EDataBookCursor * 396 e_book_backend_create_cursor (EBookBackend *backend, 397 EContactField *sort_fields, 398 EBookCursorSortType *sort_types, 399 guint n_fields, 400 GError **error); 401 gboolean e_book_backend_delete_cursor (EBookBackend *backend, 402 EDataBookCursor *cursor, 403 GError **error); 404 405 GSimpleAsyncResult * 406 e_book_backend_prepare_for_completion 407 (EBookBackend *backend, 408 guint32 opid, 409 GQueue **result_queue); 410 /** 411 * EBookBackendCustomOpFunc: 412 * @book_backend: an #EBookBackend 413 * @user_data: a function user data, as provided to e_book_backend_schedule_custom_operation() 414 * @cancellable: an optional #GCancellable, as provided to e_book_backend_schedule_custom_operation() 415 * @error: return location for a #GError, or %NULL 416 * 417 * A callback prototype being called in a dedicated thread, scheduled 418 * by e_book_backend_schedule_custom_operation(). 419 * 420 * Since: 3.26 421 **/ 422 typedef void (* EBookBackendCustomOpFunc) (EBookBackend *book_backend, 423 gpointer user_data, 424 GCancellable *cancellable, 425 GError **error); 426 427 void e_book_backend_schedule_custom_operation 428 (EBookBackend *book_backend, 429 GCancellable *use_cancellable, 430 EBookBackendCustomOpFunc func, 431 gpointer user_data, 432 GDestroyNotify user_data_free); 433 434 435 G_END_DECLS 436 437 #endif /* E_BOOK_BACKEND_H */ 438