1 /*
2  * e-cal-backend.h
3  *
4  * This library is free software: you can redistribute it and/or modify it
5  * under the terms of the GNU Lesser General Public License as published by
6  * the Free Software Foundation.
7  *
8  * This library is distributed in the hope that it will be useful, but
9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11  * for more details.
12  *
13  * You should have received a copy of the GNU Lesser General Public License
14  * along with this library. If not, see <http://www.gnu.org/licenses/>.
15  *
16  */
17 
18 #if !defined (__LIBEDATA_CAL_H_INSIDE__) && !defined (LIBEDATA_CAL_COMPILATION)
19 #error "Only <libedata-cal/libedata-cal.h> should be included directly."
20 #endif
21 
22 #ifndef E_CAL_BACKEND_H
23 #define E_CAL_BACKEND_H
24 
25 #include <libecal/libecal.h>
26 #include <libebackend/libebackend.h>
27 
28 #include <libedata-cal/e-data-cal.h>
29 
30 /* Standard GObject macros */
31 #define E_TYPE_CAL_BACKEND \
32 	(e_cal_backend_get_type ())
33 #define E_CAL_BACKEND(obj) \
34 	(G_TYPE_CHECK_INSTANCE_CAST \
35 	((obj), E_TYPE_CAL_BACKEND, ECalBackend))
36 #define E_CAL_BACKEND_CLASS(cls) \
37 	(G_TYPE_CHECK_CLASS_CAST \
38 	((cls), E_TYPE_CAL_BACKEND, ECalBackendClass))
39 #define E_IS_CAL_BACKEND(obj) \
40 	(G_TYPE_CHECK_INSTANCE_TYPE \
41 	((obj), E_TYPE_CAL_BACKEND))
42 #define E_IS_CAL_BACKEND_CLASS(cls) \
43 	(G_TYPE_CHECK_CLASS_TYPE \
44 	((cls), E_TYPE_CAL_BACKEND))
45 #define E_CAL_BACKEND_GET_CLASS(obj) \
46 	(G_TYPE_INSTANCE_GET_CLASS \
47 	((obj), E_TYPE_CAL_BACKEND, ECalBackendClass))
48 
49 G_BEGIN_DECLS
50 
51 typedef struct _ECalBackend ECalBackend;
52 typedef struct _ECalBackendClass ECalBackendClass;
53 typedef struct _ECalBackendPrivate ECalBackendPrivate;
54 
55 /**
56  * ECalBackend:
57  *
58  * Contains only private data that should be read and manipulated using the
59  * functions below.
60  */
61 struct _ECalBackend {
62 	/*< private >*/
63 	EBackend parent;
64 	ECalBackendPrivate *priv;
65 };
66 
67 /**
68  * ECalBackendClass:
69  * @use_serial_dispatch_queue: Whether a serial dispatch queue should
70  *                             be used for this backend or not. The default is %TRUE.
71  * @impl_get_backend_property: Fetch a property value by name from the backend
72  * @impl_open: Open the backend
73  * @impl_refresh: Refresh the backend
74  * @impl_get_object: Fetch a calendar object
75  * @impl_get_object_list: FIXME: Document me
76  * @impl_get_free_busy: FIXME: Document me
77  * @impl_create_objects: FIXME: Document me
78  * @impl_modify_objects: FIXME: Document me
79  * @impl_remove_objects: FIXME: Document me
80  * @impl_receive_objects: FIXME: Document me
81  * @impl_send_objects: FIXME: Document me
82  * @impl_get_attachment_uris: FIXME: Document me
83  * @impl_discard_alarm: FIXME: Document me
84  * @impl_get_timezone: FIXME: Document me
85  * @impl_add_timezone: FIXME: Document me
86  * @impl_start_view: Start up the specified view
87  * @impl_stop_view: Stop the specified view
88  * @closed: A signal notifying that the backend was closed
89  * @shutdown: A signal notifying that the backend is being shut down
90  *
91  * Class structure for the #ECalBackend class.
92  *
93  * These virtual methods must be implemented when writing
94  * a calendar backend.
95  */
96 struct _ECalBackendClass {
97 	/*< private >*/
98 	EBackendClass parent_class;
99 
100 	/*< public >*/
101 
102 	/* Set this to TRUE to use a serial dispatch queue, instead
103 	 * of a concurrent dispatch queue.  A serial dispatch queue
104 	 * executes one method at a time in the order in which they
105 	 * were called.  This is generally slower than a concurrent
106 	 * dispatch queue, but helps avoid thread-safety issues. */
107 	gboolean use_serial_dispatch_queue;
108 
109 	/* Virtual methods */
110 	gchar *		(*impl_get_backend_property)
111 						(ECalBackend *backend,
112 						 const gchar *prop_name);
113 
114 	void		(*impl_open)		(ECalBackend *backend,
115 						 EDataCal *cal,
116 						 guint32 opid,
117 						 GCancellable *cancellable);
118 
119 	void		(*impl_refresh)		(ECalBackend *backend,
120 						 EDataCal *cal,
121 						 guint32 opid,
122 						 GCancellable *cancellable);
123 	void		(*impl_get_object)	(ECalBackend *backend,
124 						 EDataCal *cal,
125 						 guint32 opid,
126 						 GCancellable *cancellable,
127 						 const gchar *uid,
128 						 const gchar *rid);
129 	void		(*impl_get_object_list)	(ECalBackend *backend,
130 						 EDataCal *cal,
131 						 guint32 opid,
132 						 GCancellable *cancellable,
133 						 const gchar *sexp);
134 	void		(*impl_get_free_busy)	(ECalBackend *backend,
135 						 EDataCal *cal,
136 						 guint32 opid,
137 						 GCancellable *cancellable,
138 						 const GSList *users, /* gchar * */
139 						 time_t start,
140 						 time_t end);
141 	void		(*impl_create_objects)	(ECalBackend *backend,
142 						 EDataCal *cal,
143 						 guint32 opid,
144 						 GCancellable *cancellable,
145 						 const GSList *calobjs, /* gchar * */
146 						 ECalOperationFlags opflags);
147 	void		(*impl_modify_objects)	(ECalBackend *backend,
148 						 EDataCal *cal,
149 						 guint32 opid,
150 						 GCancellable *cancellable,
151 						 const GSList *calobjs, /* gchar * */
152 						 ECalObjModType mod,
153 						 ECalOperationFlags opflags);
154 	void		(*impl_remove_objects)	(ECalBackend *backend,
155 						 EDataCal *cal,
156 						 guint32 opid,
157 						 GCancellable *cancellable,
158 						 const GSList *ids, /* ECalComponentId * */
159 						 ECalObjModType mod,
160 						 ECalOperationFlags opflags);
161 	void		(*impl_receive_objects)	(ECalBackend *backend,
162 						 EDataCal *cal,
163 						 guint32 opid,
164 						 GCancellable *cancellable,
165 						 const gchar *calobj,
166 						 ECalOperationFlags opflags);
167 	void		(*impl_send_objects)	(ECalBackend *backend,
168 						 EDataCal *cal,
169 						 guint32 opid,
170 						 GCancellable *cancellable,
171 						 const gchar *calobj,
172 						 ECalOperationFlags opflags);
173 	void		(*impl_get_attachment_uris)
174 						(ECalBackend *backend,
175 						 EDataCal *cal,
176 						 guint32 opid,
177 						 GCancellable *cancellable,
178 						 const gchar *uid,
179 						 const gchar *rid);
180 	void		(*impl_discard_alarm)	(ECalBackend *backend,
181 						 EDataCal *cal,
182 						 guint32 opid,
183 						 GCancellable *cancellable,
184 						 const gchar *uid,
185 						 const gchar *rid,
186 						 const gchar *auid,
187 						 ECalOperationFlags opflags);
188 	void		(*impl_get_timezone)	(ECalBackend *backend,
189 						 EDataCal *cal,
190 						 guint32 opid,
191 						 GCancellable *cancellable,
192 						 const gchar *tzid);
193 	void		(*impl_add_timezone)	(ECalBackend *backend,
194 						 EDataCal *cal,
195 						 guint32 opid,
196 						 GCancellable *cancellable,
197 						 const gchar *tzobject);
198 
199 	void		(*impl_start_view)	(ECalBackend *backend,
200 						 EDataCalView *view);
201 	void		(*impl_stop_view)	(ECalBackend *backend,
202 						 EDataCalView *view);
203 
204 	/* Signals */
205 	void		(*closed)		(ECalBackend *backend,
206 						 const gchar *sender);
207 	void		(*shutdown)		(ECalBackend *backend);
208 
209 	/* Padding for future expansion */
210 	gpointer reserved_padding[20];
211 };
212 
213 GType		e_cal_backend_get_type		(void) G_GNUC_CONST;
214 ICalComponentKind
215 		e_cal_backend_get_kind		(ECalBackend *backend);
216 EDataCal *	e_cal_backend_ref_data_cal	(ECalBackend *backend);
217 void		e_cal_backend_set_data_cal	(ECalBackend *backend,
218 						 EDataCal *data_cal);
219 GProxyResolver *
220 		e_cal_backend_ref_proxy_resolver
221 						(ECalBackend *backend);
222 ESourceRegistry *
223 		e_cal_backend_get_registry	(ECalBackend *backend);
224 gboolean	e_cal_backend_get_writable	(ECalBackend *backend);
225 void		e_cal_backend_set_writable	(ECalBackend *backend,
226 						 gboolean writable);
227 gboolean	e_cal_backend_is_opened		(ECalBackend *backend);
228 gboolean	e_cal_backend_is_readonly	(ECalBackend *backend);
229 
230 const gchar *	e_cal_backend_get_cache_dir	(ECalBackend *backend);
231 gchar *		e_cal_backend_dup_cache_dir	(ECalBackend *backend);
232 void		e_cal_backend_set_cache_dir	(ECalBackend *backend,
233 						 const gchar *cache_dir);
234 gchar *		e_cal_backend_create_cache_filename
235 						(ECalBackend *backend,
236 						 const gchar *uid,
237 						 const gchar *filename,
238 						 gint fileindex);
239 
240 void		e_cal_backend_add_view		(ECalBackend *backend,
241 						 EDataCalView *view);
242 void		e_cal_backend_remove_view	(ECalBackend *backend,
243 						 EDataCalView *view);
244 GList *		e_cal_backend_list_views	(ECalBackend *backend);
245 
246 typedef gboolean (*ECalBackendForeachViewFunc)	(ECalBackend *backend,
247 						 EDataCalView *view,
248 						 gpointer user_data);
249 
250 gboolean	e_cal_backend_foreach_view	(ECalBackend *backend,
251 						 ECalBackendForeachViewFunc func,
252 						 gpointer user_data);
253 void		e_cal_backend_foreach_view_notify_progress
254 						(ECalBackend *backend,
255 						 gboolean only_completed_views,
256 						 gint percent,
257 						 const gchar *message);
258 
259 gchar *		e_cal_backend_get_backend_property
260 						(ECalBackend *backend,
261 						 const gchar *prop_name);
262 gboolean	e_cal_backend_open_sync		(ECalBackend *backend,
263 						 GCancellable *cancellable,
264 						 GError **error);
265 void		e_cal_backend_open		(ECalBackend *backend,
266 						 GCancellable *cancellable,
267 						 GAsyncReadyCallback callback,
268 						 gpointer user_data);
269 gboolean	e_cal_backend_open_finish	(ECalBackend *backend,
270 						 GAsyncResult *result,
271 						 GError **error);
272 gboolean	e_cal_backend_refresh_sync	(ECalBackend *backend,
273 						 GCancellable *cancellable,
274 						 GError **error);
275 void		e_cal_backend_refresh		(ECalBackend *backend,
276 						 GCancellable *cancellable,
277 						 GAsyncReadyCallback callback,
278 						 gpointer user_data);
279 gboolean	e_cal_backend_refresh_finish	(ECalBackend *backend,
280 						 GAsyncResult *result,
281 						 GError **error);
282 gchar *		e_cal_backend_get_object_sync	(ECalBackend *backend,
283 						 const gchar *uid,
284 						 const gchar *rid,
285 						 GCancellable *cancellable,
286 						 GError **error);
287 void		e_cal_backend_get_object	(ECalBackend *backend,
288 						 const gchar *uid,
289 						 const gchar *rid,
290 						 GCancellable *cancellable,
291 						 GAsyncReadyCallback callback,
292 						 gpointer user_data);
293 gchar *		e_cal_backend_get_object_finish	(ECalBackend *backend,
294 						 GAsyncResult *result,
295 						 GError **error);
296 gboolean	e_cal_backend_get_object_list_sync
297 						(ECalBackend *backend,
298 						 const gchar *query,
299 						 GQueue *out_objects, /* gchar * */
300 						 GCancellable *cancellable,
301 						 GError **error);
302 void		e_cal_backend_get_object_list	(ECalBackend *backend,
303 						 const gchar *query,
304 						 GCancellable *cancellable,
305 						 GAsyncReadyCallback callback,
306 						 gpointer user_data);
307 gboolean	e_cal_backend_get_object_list_finish
308 						(ECalBackend *backend,
309 						 GAsyncResult *result,
310 						 GQueue *out_objects, /* gchar * */
311 						 GError **error);
312 gboolean	e_cal_backend_get_free_busy_sync
313 						(ECalBackend *backend,
314 						 time_t start,
315 						 time_t end,
316 						 const gchar * const *users,
317 						 GSList **out_freebusy, /* gchar * */
318 						 GCancellable *cancellable,
319 						 GError **error);
320 void		e_cal_backend_get_free_busy	(ECalBackend *backend,
321 						 time_t start,
322 						 time_t end,
323 						 const gchar * const *users,
324 						 GCancellable *cancellable,
325 						 GAsyncReadyCallback callback,
326 						 gpointer user_data);
327 gboolean	e_cal_backend_get_free_busy_finish
328 						(ECalBackend *backend,
329 						 GAsyncResult *result,
330 						 GSList **out_freebusy, /* gchar * */
331 						 GError **error);
332 gboolean	e_cal_backend_create_objects_sync
333 						(ECalBackend *backend,
334 						 const gchar * const *calobjs,
335 						 ECalOperationFlags opflags,
336 						 GQueue *out_uids,
337 						 GCancellable *cancellable,
338 						 GError **error);
339 void		e_cal_backend_create_objects	(ECalBackend *backend,
340 						 const gchar * const *calobjs,
341 						 ECalOperationFlags opflags,
342 						 GCancellable *cancellable,
343 						 GAsyncReadyCallback callback,
344 						 gpointer user_data);
345 gboolean	e_cal_backend_create_objects_finish
346 						(ECalBackend *backend,
347 						 GAsyncResult *result,
348 						 GQueue *out_uids,
349 						 GError **error);
350 gboolean	e_cal_backend_modify_objects_sync
351 						(ECalBackend *backend,
352 						 const gchar * const *calobjs,
353 						 ECalObjModType mod,
354 						 ECalOperationFlags opflags,
355 						 GCancellable *cancellable,
356 						 GError **error);
357 void		e_cal_backend_modify_objects	(ECalBackend *backend,
358 						 const gchar * const *calobjs,
359 						 ECalObjModType mod,
360 						 ECalOperationFlags opflags,
361 						 GCancellable *cancellable,
362 						 GAsyncReadyCallback callback,
363 						 gpointer user_data);
364 gboolean	e_cal_backend_modify_objects_finish
365 						(ECalBackend *backend,
366 						 GAsyncResult *result,
367 						 GError **error);
368 gboolean	e_cal_backend_remove_objects_sync
369 						(ECalBackend *backend,
370 						 GList *component_ids, /* ECalComponentId * */
371 						 ECalObjModType mod,
372 						 ECalOperationFlags opflags,
373 						 GCancellable *cancellable,
374 						 GError **error);
375 void		e_cal_backend_remove_objects	(ECalBackend *backend,
376 						 GList *component_ids, /* ECalComponentId * */
377 						 ECalObjModType mod,
378 						 ECalOperationFlags opflags,
379 						 GCancellable *cancellable,
380 						 GAsyncReadyCallback callback,
381 						 gpointer user_data);
382 gboolean	e_cal_backend_remove_objects_finish
383 						(ECalBackend *backend,
384 						 GAsyncResult *result,
385 						 GError **error);
386 gboolean	e_cal_backend_receive_objects_sync
387 						(ECalBackend *backend,
388 						 const gchar *calobj,
389 						 ECalOperationFlags opflags,
390 						 GCancellable *cancellable,
391 						 GError **error);
392 void		e_cal_backend_receive_objects	(ECalBackend *backend,
393 						 const gchar *calobj,
394 						 ECalOperationFlags opflags,
395 						 GCancellable *cancellable,
396 						 GAsyncReadyCallback callback,
397 						 gpointer user_data);
398 gboolean	e_cal_backend_receive_objects_finish
399 						(ECalBackend *backend,
400 						 GAsyncResult *result,
401 						 GError **error);
402 gchar *		e_cal_backend_send_objects_sync	(ECalBackend *backend,
403 						 const gchar *calobj,
404 						 ECalOperationFlags opflags,
405 						 GQueue *out_users,
406 						 GCancellable *cancellable,
407 						 GError **error);
408 void		e_cal_backend_send_objects	(ECalBackend *backend,
409 						 const gchar *calobj,
410 						 ECalOperationFlags opflags,
411 						 GCancellable *cancellable,
412 						 GAsyncReadyCallback callback,
413 						 gpointer user_data);
414 gchar *		e_cal_backend_send_objects_finish
415 						(ECalBackend *backend,
416 						 GAsyncResult *result,
417 						 GQueue *out_users,
418 						 GError **error);
419 gboolean	e_cal_backend_get_attachment_uris_sync
420 						(ECalBackend *backend,
421 						 const gchar *uid,
422 						 const gchar *rid,
423 						 GQueue *out_attachment_uris,
424 						 GCancellable *cancellable,
425 						 GError **error);
426 void		e_cal_backend_get_attachment_uris
427 						(ECalBackend *backend,
428 						 const gchar *uid,
429 						 const gchar *rid,
430 						 GCancellable *cancellable,
431 						 GAsyncReadyCallback callback,
432 						 gpointer user_data);
433 gboolean	e_cal_backend_get_attachment_uris_finish
434 						(ECalBackend *backend,
435 						 GAsyncResult *result,
436 						 GQueue *out_attachment_uris,
437 						 GError **error);
438 gboolean	e_cal_backend_discard_alarm_sync
439 						(ECalBackend *backend,
440 						 const gchar *uid,
441 						 const gchar *rid,
442 						 const gchar *alarm_uid,
443 						 ECalOperationFlags opflags,
444 						 GCancellable *cancellable,
445 						 GError **error);
446 void		e_cal_backend_discard_alarm	(ECalBackend *backend,
447 						 const gchar *uid,
448 						 const gchar *rid,
449 						 const gchar *alarm_uid,
450 						 ECalOperationFlags opflags,
451 						 GCancellable *cancellable,
452 						 GAsyncReadyCallback callback,
453 						 gpointer user_data);
454 gboolean	e_cal_backend_discard_alarm_finish
455 						(ECalBackend *backend,
456 						 GAsyncResult *result,
457 						 GError **error);
458 gchar *		e_cal_backend_get_timezone_sync	(ECalBackend *backend,
459 						 const gchar *tzid,
460 						 GCancellable *cancellable,
461 						 GError **error);
462 void		e_cal_backend_get_timezone	(ECalBackend *backend,
463 						 const gchar *tzid,
464 						 GCancellable *cancellable,
465 						 GAsyncReadyCallback callback,
466 						 gpointer user_data);
467 gchar *		e_cal_backend_get_timezone_finish
468 						(ECalBackend *backend,
469 						 GAsyncResult *result,
470 						 GError **error);
471 gboolean	e_cal_backend_add_timezone_sync	(ECalBackend *backend,
472 						 const gchar *tzobject,
473 						 GCancellable *cancellable,
474 						 GError **error);
475 void		e_cal_backend_add_timezone	(ECalBackend *backend,
476 						 const gchar *tzobject,
477 						 GCancellable *cancellable,
478 						 GAsyncReadyCallback callback,
479 						 gpointer user_data);
480 gboolean	e_cal_backend_add_timezone_finish
481 						(ECalBackend *backend,
482 						 GAsyncResult *result,
483 						 GError **error);
484 void		e_cal_backend_start_view	(ECalBackend *backend,
485 						 EDataCalView *view);
486 void		e_cal_backend_stop_view		(ECalBackend *backend,
487 						 EDataCalView *view);
488 
489 void		e_cal_backend_notify_component_created
490 						(ECalBackend *backend,
491 						 ECalComponent *component);
492 void		e_cal_backend_notify_component_modified
493 						(ECalBackend *backend,
494 						 ECalComponent *old_component,
495 						 ECalComponent *new_component);
496 void		e_cal_backend_notify_component_removed
497 						(ECalBackend *backend,
498 						 const ECalComponentId *id,
499 						 ECalComponent *old_component,
500 						 ECalComponent *new_component);
501 
502 void		e_cal_backend_notify_error	(ECalBackend *backend,
503 						 const gchar *message);
504 void		e_cal_backend_notify_property_changed
505 						(ECalBackend *backend,
506 						 const gchar *prop_name,
507 						 const gchar *prop_value);
508 
509 GSimpleAsyncResult *
510 		e_cal_backend_prepare_for_completion
511 						(ECalBackend *backend,
512 						 guint opid,
513 						 GQueue **result_queue);
514 
515 /**
516  * ECalBackendCustomOpFunc:
517  * @cal_backend: an #ECalBackend
518  * @user_data: a function user data, as provided to e_cal_backend_schedule_custom_operation()
519  * @cancellable: an optional #GCancellable, as provided to e_cal_backend_schedule_custom_operation()
520  * @error: return location for a #GError, or %NULL
521  *
522  * A callback prototype being called in a dedicated thread, scheduled
523  * by e_cal_backend_schedule_custom_operation().
524  *
525  * Since: 3.26
526  **/
527 typedef void	(* ECalBackendCustomOpFunc)	(ECalBackend *cal_backend,
528 						 gpointer user_data,
529 						 GCancellable *cancellable,
530 						 GError **error);
531 
532 void		e_cal_backend_schedule_custom_operation
533 						(ECalBackend *cal_backend,
534 						 GCancellable *use_cancellable,
535 						 ECalBackendCustomOpFunc func,
536 						 gpointer user_data,
537 						 GDestroyNotify user_data_free);
538 
539 G_END_DECLS
540 
541 #endif /* E_CAL_BACKEND_H */
542