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