1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */ 2 /* 3 * Copyright (C) 2013 Intel Corporation 4 * 5 * This library is free software: you can redistribute it and/or modify it 6 * under the terms of the GNU Lesser General Public License as published by 7 * the Free Software Foundation. 8 * 9 * This library is distributed in the hope that it will be useful, but 10 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 11 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 12 * for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public License 15 * along with this library. If not, see <http://www.gnu.org/licenses/>. 16 * 17 * Authors: Tristan Van Berkom <tristanvb@openismus.com> 18 */ 19 20 #if !defined (__LIBEDATA_BOOK_H_INSIDE__) && !defined (LIBEDATA_BOOK_COMPILATION) 21 #error "Only <libedata-book/libedata-book.h> should be included directly." 22 #endif 23 24 #ifndef E_BOOK_CACHE_H 25 #define E_BOOK_CACHE_H 26 27 #include <libebackend/libebackend.h> 28 #include <libebook-contacts/libebook-contacts.h> 29 30 /* Standard GObject macros */ 31 #define E_TYPE_BOOK_CACHE \ 32 (e_book_cache_get_type ()) 33 #define E_BOOK_CACHE(obj) \ 34 (G_TYPE_CHECK_INSTANCE_CAST \ 35 ((obj), E_TYPE_BOOK_CACHE, EBookCache)) 36 #define E_BOOK_CACHE_CLASS(cls) \ 37 (G_TYPE_CHECK_CLASS_CAST \ 38 ((cls), E_TYPE_BOOK_CACHE, EBookCacheClass)) 39 #define E_IS_BOOK_CACHE(obj) \ 40 (G_TYPE_CHECK_INSTANCE_TYPE \ 41 ((obj), E_TYPE_BOOK_CACHE)) 42 #define E_IS_BOOK_CACHE_CLASS(cls) \ 43 (G_TYPE_CHECK_CLASS_TYPE \ 44 ((cls), E_TYPE_BOOK_CACHE)) 45 #define E_BOOK_CACHE_GET_CLASS(obj) \ 46 (G_TYPE_INSTANCE_GET_CLASS \ 47 ((obj), E_TYPE_BOOK_CACHE, EBookCacheClass)) 48 49 G_BEGIN_DECLS 50 51 typedef struct _EBookCache EBookCache; 52 typedef struct _EBookCacheClass EBookCacheClass; 53 typedef struct _EBookCachePrivate EBookCachePrivate; 54 55 /** 56 * EBookCacheSearchData: 57 * @uid: The %E_CONTACT_UID field of this contact 58 * @vcard: The vcard string 59 * @extra: Any extra data associated with the vcard 60 * 61 * This structure is used to represent contacts returned 62 * by the #EBookCache from various functions 63 * such as e_book_cache_search(). 64 * 65 * The @extra parameter will contain any data which was 66 * previously passed for this contact in e_book_cache_put_contact() 67 * or set with e_book_cache_set_contact_extra(). 68 * 69 * These should be freed with e_book_cache_search_data_free(). 70 * 71 * Since: 3.26 72 **/ 73 typedef struct { 74 gchar *uid; 75 gchar *vcard; 76 gchar *extra; 77 } EBookCacheSearchData; 78 79 #define E_TYPE_BOOK_CACHE_SEARCH_DATA (e_book_cache_search_data_get_type ()) 80 81 GType e_book_cache_search_data_get_type 82 (void) G_GNUC_CONST; 83 EBookCacheSearchData * 84 e_book_cache_search_data_new (const gchar *uid, 85 const gchar *vcard, 86 const gchar *extra); 87 EBookCacheSearchData * 88 e_book_cache_search_data_copy (const EBookCacheSearchData *data); 89 void e_book_cache_search_data_free (/* EBookCacheSearchData * */ gpointer data); 90 91 /** 92 * EBookCacheSearchFunc: 93 * @book_cache: an #EBookCache 94 * @uid: a unique object identifier 95 * @revision: the object revision 96 * @object: the object itself 97 * @extra: extra data stored with the object 98 * @custom_flags: object's custom flags 99 * @offline_state: object's offline state, one of #EOfflineState 100 * @user_data: user data, as used in e_book_cache_search_with_callback() 101 * 102 * A callback called for each object row when using 103 * e_book_cache_search_with_callback() function. 104 * 105 * Returns: %TRUE to continue, %FALSE to stop walk through. 106 * 107 * Since: 3.26 108 **/ 109 typedef gboolean (* EBookCacheSearchFunc) (EBookCache *book_cache, 110 const gchar *uid, 111 const gchar *revision, 112 const gchar *object, 113 const gchar *extra, 114 guint32 custom_flags, 115 EOfflineState offline_state, 116 gpointer user_data); 117 118 /** 119 * EBookCache: 120 * 121 * Contains only private data that should be read and manipulated using 122 * the functions below. 123 * 124 * Since: 3.26 125 **/ 126 struct _EBookCache { 127 /*< private >*/ 128 ECache parent; 129 EBookCachePrivate *priv; 130 }; 131 132 /** 133 * EBookCacheClass: 134 * 135 * Class structure for the #EBookCache class. 136 * 137 * Since: 3.26 138 */ 139 struct _EBookCacheClass { 140 /*< private >*/ 141 ECacheClass parent_class; 142 143 /* Signals */ 144 void (* e164_changed) (EBookCache *book_cache, 145 EContact *contact, 146 gboolean is_replace); 147 148 gchar * (* dup_contact_revision) 149 (EBookCache *book_cache, 150 EContact *contact); 151 152 /* Padding for future expansion */ 153 gpointer reserved[10]; 154 }; 155 156 /** 157 * EBookCacheCursor: 158 * 159 * An opaque cursor pointer 160 * 161 * Since: 3.26 162 */ 163 typedef struct _EBookCacheCursor EBookCacheCursor; 164 165 /** 166 * EBookCacheCursorOrigin: 167 * @E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT: The current cursor position. 168 * @E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN: The beginning of the cursor results. 169 * @E_BOOK_CACHE_CURSOR_ORIGIN_END: The end of the cursor results. 170 * 171 * Specifies the start position to in the list of traversed contacts 172 * in calls to e_book_cache_cursor_step(). 173 * 174 * When an #EBookCacheCursor is created, the current position implied by %E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT 175 * is the same as %E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN. 176 * 177 * Since: 3.26 178 */ 179 typedef enum { 180 E_BOOK_CACHE_CURSOR_ORIGIN_CURRENT = 0, 181 E_BOOK_CACHE_CURSOR_ORIGIN_BEGIN, 182 E_BOOK_CACHE_CURSOR_ORIGIN_END 183 } EBookCacheCursorOrigin; 184 185 /** 186 * EBookCacheCursorStepFlags: 187 * @E_BOOK_CACHE_CURSOR_STEP_MOVE: The cursor position should be modified while stepping. 188 * @E_BOOK_CACHE_CURSOR_STEP_FETCH: Traversed contacts should be listed and returned while stepping. 189 * 190 * Defines the behaviour of e_book_cache_cursor_step(). 191 * 192 * Since: 3.26 193 */ 194 typedef enum { 195 E_BOOK_CACHE_CURSOR_STEP_MOVE = (1 << 0), 196 E_BOOK_CACHE_CURSOR_STEP_FETCH = (1 << 1) 197 } EBookCacheCursorStepFlags; 198 199 GType e_book_cache_get_type (void) G_GNUC_CONST; 200 201 EBookCache * e_book_cache_new (const gchar *filename, 202 ESource *source, 203 GCancellable *cancellable, 204 GError **error); 205 EBookCache * e_book_cache_new_full (const gchar *filename, 206 ESource *source, 207 ESourceBackendSummarySetup *setup, 208 GCancellable *cancellable, 209 GError **error); 210 ESource * e_book_cache_ref_source (EBookCache *book_cache); 211 gchar * e_book_cache_dup_contact_revision 212 (EBookCache *book_cache, 213 EContact *contact); 214 gboolean e_book_cache_set_locale (EBookCache *book_cache, 215 const gchar *lc_collate, 216 GCancellable *cancellable, 217 GError **error); 218 gchar * e_book_cache_dup_locale (EBookCache *book_cache); 219 220 ECollator * e_book_cache_ref_collator (EBookCache *book_cache); 221 222 /* Adding / Removing / Searching contacts */ 223 gboolean e_book_cache_put_contact (EBookCache *book_cache, 224 EContact *contact, 225 const gchar *extra, 226 guint32 custom_flags, 227 ECacheOfflineFlag offline_flag, 228 GCancellable *cancellable, 229 GError **error); 230 gboolean e_book_cache_put_contacts (EBookCache *book_cache, 231 const GSList *contacts, /* EContact * */ 232 const GSList *extras, /* gchar * */ 233 const GSList *custom_flags, /* guint32, through GUINT_TO_POINTER() */ 234 ECacheOfflineFlag offline_flag, 235 GCancellable *cancellable, 236 GError **error); 237 gboolean e_book_cache_remove_contact (EBookCache *book_cache, 238 const gchar *uid, 239 guint32 custom_flags, 240 ECacheOfflineFlag offline_flag, 241 GCancellable *cancellable, 242 GError **error); 243 gboolean e_book_cache_remove_contacts (EBookCache *book_cache, 244 const GSList *uids, /* gchar * */ 245 const GSList *custom_flags, /* guint32, through GUINT_TO_POINTER() */ 246 ECacheOfflineFlag offline_flag, 247 GCancellable *cancellable, 248 GError **error); 249 gboolean e_book_cache_get_contact (EBookCache *book_cache, 250 const gchar *uid, 251 gboolean meta_contact, 252 EContact **out_contact, 253 GCancellable *cancellable, 254 GError **error); 255 gboolean e_book_cache_get_vcard (EBookCache *book_cache, 256 const gchar *uid, 257 gboolean meta_contact, 258 gchar **out_vcard, 259 GCancellable *cancellable, 260 GError **error); 261 gboolean e_book_cache_set_contact_custom_flags 262 (EBookCache *book_cache, 263 const gchar *uid, 264 guint32 custom_flags, 265 GCancellable *cancellable, 266 GError **error); 267 gboolean e_book_cache_get_contact_custom_flags 268 (EBookCache *book_cache, 269 const gchar *uid, 270 guint32 *out_custom_flags, 271 GCancellable *cancellable, 272 GError **error); 273 gboolean e_book_cache_set_contact_extra (EBookCache *book_cache, 274 const gchar *uid, 275 const gchar *extra, 276 GCancellable *cancellable, 277 GError **error); 278 gboolean e_book_cache_get_contact_extra (EBookCache *book_cache, 279 const gchar *uid, 280 gchar **out_extra, 281 GCancellable *cancellable, 282 GError **error); 283 gboolean e_book_cache_get_uids_with_extra 284 (EBookCache *book_cache, 285 const gchar *extra, 286 GSList **out_uids, /* gchar * */ 287 GCancellable *cancellable, 288 GError **error); 289 gboolean e_book_cache_search (EBookCache *book_cache, 290 const gchar *sexp, 291 gboolean meta_contacts, 292 GSList **out_list, /* EBookCacheSearchData * */ 293 GCancellable *cancellable, 294 GError **error); 295 gboolean e_book_cache_search_uids (EBookCache *book_cache, 296 const gchar *sexp, 297 GSList **out_list, /* gchar * */ 298 GCancellable *cancellable, 299 GError **error); 300 gboolean e_book_cache_search_with_callback 301 (EBookCache *book_cache, 302 const gchar *sexp, 303 EBookCacheSearchFunc func, 304 gpointer user_data, 305 GCancellable *cancellable, 306 GError **error); 307 /* Cursor API */ 308 GType e_book_cache_cursor_get_type (void) G_GNUC_CONST; 309 310 EBookCacheCursor * 311 e_book_cache_cursor_new (EBookCache *book_cache, 312 const gchar *sexp, 313 const EContactField *sort_fields, 314 const EBookCursorSortType *sort_types, 315 guint n_sort_fields, 316 GError **error); 317 void e_book_cache_cursor_free (EBookCache *book_cache, 318 EBookCacheCursor *cursor); 319 gint e_book_cache_cursor_step (EBookCache *book_cache, 320 EBookCacheCursor *cursor, 321 EBookCacheCursorStepFlags flags, 322 EBookCacheCursorOrigin origin, 323 gint count, 324 GSList **out_results, 325 GCancellable *cancellable, 326 GError **error); 327 void e_book_cache_cursor_set_target_alphabetic_index 328 (EBookCache *book_cache, 329 EBookCacheCursor *cursor, 330 gint idx); 331 gboolean e_book_cache_cursor_set_sexp (EBookCache *book_cache, 332 EBookCacheCursor *cursor, 333 const gchar *sexp, 334 GError **error); 335 gboolean e_book_cache_cursor_calculate (EBookCache *book_cache, 336 EBookCacheCursor *cursor, 337 gint *out_total, 338 gint *out_position, 339 GCancellable *cancellable, 340 GError **error); 341 gint e_book_cache_cursor_compare_contact 342 (EBookCache *book_cache, 343 EBookCacheCursor *cursor, 344 EContact *contact, 345 gboolean *out_matches_sexp); 346 347 G_END_DECLS 348 349 #endif /* E_BOOK_CACHE_H */ 350