addressbook/libedata-book/e-data-book.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /*
   3  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
   4  * Copyright (C) 2006 OpenedHand Ltd
   5  * Copyright (C) 2009 Intel Corporation
   6  *
   7  * This library is free software; you can redistribute it and/or modify it under
   8  * the terms of version 2.1 of the GNU Lesser General Public License as
   9  * published by the Free Software Foundation.
  10  *
  11  * This library is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13  * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  14  * details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this library; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  19  *
  20  * Author: Ross Burton <ross@linux.intel.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_DATA_BOOK_H
  28 #define E_DATA_BOOK_H
  29
  30 #include <libedataserver/libedataserver.h>
  31
  32 /* Standard GObject macros */
  33 #define E_TYPE_DATA_BOOK \
  34         (e_data_book_get_type ())
  35 #define E_DATA_BOOK(obj) \
  36         (G_TYPE_CHECK_INSTANCE_CAST \
  37         ((obj), E_TYPE_DATA_BOOK, EDataBook))
  38 #define E_DATA_BOOK_CLASS(cls) \
  39         (G_TYPE_CHECK_CLASS_CAST \
  40         ((cls), E_TYPE_DATA_BOOK, EDataBookClass))
  41 #define E_IS_DATA_BOOK(obj) \
  42         (G_TYPE_CHECK_INSTANCE_TYPE \
  43         ((obj), E_TYPE_DATA_BOOK))
  44 #define E_IS_DATA_BOOK_CLASS(cls) \
  45         (G_TYPE_CHECK_CLASS_TYPE \
  46         ((cls), E_TYPE_DATA_BOOK))
  47 #define E_DATA_BOOK_GET_CLASS(obj) \
  48         (G_TYPE_INSTANCE_GET_CLASS \
  49         ((obj), E_TYPE_DATA_BOOK, EDataBookClass))
  50
  51 G_BEGIN_DECLS
  52
  53 struct _EBookBackend;
  54
  55 typedef struct _EDataBook EDataBook;
  56 typedef struct _EDataBookClass EDataBookClass;
  57 typedef struct _EDataBookPrivate EDataBookPrivate;
  58
  59 struct _EDataBook {
  60         GObject parent;
  61         EDataBookPrivate *priv;
  62 };
  63
  64 struct _EDataBookClass {
  65         GObjectClass parent_class;
  66 };
  67
  68 GQuark e_data_book_error_quark (void);
  69
  70 /**
  71  * E_DATA_BOOK_ERROR:
  72  *
  73  * Since: 2.30
  74  **/
  75 #define E_DATA_BOOK_ERROR e_data_book_error_quark ()
  76
  77 /**
  78  * e_data_book_create_error:
  79  * @status: #EDataBookStatus code
  80  * @custom_msg: Custom message to use for the error. When NULL,
  81  *              then uses a default message based on the @status code.
  82  *
  83  * Returns: NULL, when the @status is E_DATA_BOOK_STATUS_SUCCESS,
  84  *          or a newly allocated GError, which should be freed
  85  *          with g_error_free() call.
  86  **/
  87 GError *        e_data_book_create_error        (EDataBookStatus status,
  88                                                  const gchar *custom_msg);
  89
  90 /**
  91  * e_data_book_create_error_fmt:
  92  *
  93  * Similar as e_data_book_create_error(), only here, instead of custom_msg,
  94  * is used a printf() format to create a custom_msg for the error.
  95  **/
  96 GError *        e_data_book_create_error_fmt    (EDataBookStatus status,
  97                                                  const gchar *custom_msg_fmt,
  98                                                  ...) G_GNUC_PRINTF (2, 3);
  99
 100 const gchar *   e_data_book_status_to_string    (EDataBookStatus status);
 101
 102 /**
 103  * e_return_data_book_error_if_fail:
 104  *
 105  * Since: 2.32
 106  **/
 107 #define e_return_data_book_error_if_fail(expr, _code)                           \
 108         G_STMT_START {                                                          \
 109                 if (G_LIKELY (expr)) {                                          \
 110                 } else {                                                        \
 111                         g_log (G_LOG_DOMAIN,                                    \
 112                                 G_LOG_LEVEL_CRITICAL,                           \
 113                                 "file %s: line %d (%s): assertion `%s' failed", \
 114                                 __FILE__, __LINE__, G_STRFUNC, #expr);          \
 115                         g_set_error (error, E_DATA_BOOK_ERROR, (_code),         \
 116                                 "file %s: line %d (%s): assertion `%s' failed", \
 117                                 __FILE__, __LINE__, G_STRFUNC, #expr);          \
 118                         return;                                                 \
 119                 }                                                               \
 120         } G_STMT_END
 121
 122 /**
 123  * e_return_data_book_error_val_if_fail:
 124  *
 125  * Same as e_return_data_book_error_if_fail(), only returns FALSE on a failure
 126  *
 127  * Since: 3.2
 128  **/
 129 #define e_return_data_book_error_val_if_fail(expr, _code)                       \
 130         G_STMT_START {                                                          \
 131                 if (G_LIKELY (expr)) {                                          \
 132                 } else {                                                        \
 133                         g_log (G_LOG_DOMAIN,                                    \
 134                                 G_LOG_LEVEL_CRITICAL,                           \
 135                                 "file %s: line %d (%s): assertion `%s' failed", \
 136                                 __FILE__, __LINE__, G_STRFUNC, #expr);          \
 137                         g_set_error (error, E_DATA_BOOK_ERROR, (_code),         \
 138                                 "file %s: line %d (%s): assertion `%s' failed", \
 139                                 __FILE__, __LINE__, G_STRFUNC, #expr);          \
 140                         return FALSE;                                           \
 141                 }                                                               \
 142         } G_STMT_END
 143
 144 GType           e_data_book_get_type            (void) G_GNUC_CONST;
 145 EDataBook *     e_data_book_new                 (struct _EBookBackend *backend,
 146                                                  GDBusConnection *connection,
 147                                                  const gchar *object_path,
 148                                                  GError **error);
 149 EDataBook *     e_data_book_new_direct          (ESourceRegistry *registry,
 150                                                  ESource *source,
 151                                                  const gchar *backend_path,
 152                                                  const gchar *backend_name,
 153                                                  const gchar *config,
 154                                                  GError **error);
 155 struct _EBookBackend *
 156                 e_data_book_get_backend         (EDataBook *book);
 157 GDBusConnection *
 158                 e_data_book_get_connection      (EDataBook *book);
 159 const gchar *   e_data_book_get_object_path     (EDataBook *book);
 160
 161 void            e_data_book_respond_open        (EDataBook *book,
 162                                                  guint32 opid,
 163                                                  GError *error);
 164 void            e_data_book_respond_refresh     (EDataBook *book,
 165                                                  guint32 opid,
 166                                                  GError *error);
 167 void            e_data_book_respond_get_backend_property
 168                                                 (EDataBook *book,
 169                                                  guint32 opid,
 170                                                  GError *error,
 171                                                  const gchar *prop_value);
 172 void            e_data_book_respond_create_contacts
 173                                                 (EDataBook *book,
 174                                                  guint32 opid,
 175                                                  GError *error,
 176                                                  const GSList *contacts);
 177 void            e_data_book_respond_remove_contacts
 178                                                 (EDataBook *book,
 179                                                  guint32 opid,
 180                                                  GError *error,
 181                                                  const GSList *ids);
 182 void            e_data_book_respond_modify_contacts
 183                                                 (EDataBook *book,
 184                                                  guint32 opid,
 185                                                  GError *error,
 186                                                  const GSList *contacts);
 187 void            e_data_book_respond_get_contact (EDataBook *book,
 188                                                  guint32 opid,
 189                                                  GError *error,
 190                                                  const gchar *vcard);
 191 void            e_data_book_respond_get_contact_list
 192                                                 (EDataBook *book,
 193                                                  guint32 opid,
 194                                                  GError *error,
 195                                                  const GSList *cards);
 196 void            e_data_book_respond_get_contact_list_uids
 197                                                 (EDataBook *book,
 198                                                  guint32 opid,
 199                                                  GError *error,
 200                                                  const GSList *uids);
 201
 202 void            e_data_book_report_error        (EDataBook *book,
 203                                                  const gchar *message);
 204 void            e_data_book_report_backend_property_changed
 205                                                 (EDataBook *book,
 206                                                  const gchar *prop_name,
 207                                                  const gchar *prop_value);
 208
 209 gchar *         e_data_book_string_slist_to_comma_string
 210                                                 (const GSList *strings);
 211
 212 /* Direct read access apis */
 213 gboolean        e_data_book_open_sync           (EDataBook *book,
 214                                                  GCancellable *cancellable,
 215                                                  GError **error);
 216
 217 void            e_data_book_close               (EDataBook *book,
 218                                                  GCancellable *cancellable,
 219                                                  GAsyncReadyCallback callback,
 220                                                  gpointer user_data);
 221 gboolean        e_data_book_close_finish        (EDataBook *book,
 222                                                  GAsyncResult *result,
 223                                                  GError **error);
 224 gboolean        e_data_book_close_sync          (EDataBook *book,
 225                                                  GCancellable *cancellable,
 226                                                  GError **error);
 227
 228 void            e_data_book_get_contact         (EDataBook *book,
 229                                                  const gchar *uid,
 230                                                  GCancellable *cancellable,
 231                                                  GAsyncReadyCallback callback,
 232                                                  gpointer user_data);
 233 gboolean        e_data_book_get_contact_finish  (EDataBook *book,
 234                                                  GAsyncResult *result,
 235                                                  EContact **contact,
 236                                                  GError **error);
 237 gboolean        e_data_book_get_contact_sync    (EDataBook *book,
 238                                                  const gchar *uid,
 239                                                  EContact **contact,
 240                                                  GCancellable *cancellable,
 241                                                  GError **error);
 242
 243 void            e_data_book_get_contacts        (EDataBook *book,
 244                                                  const gchar *sexp,
 245                                                  GCancellable *cancellable,
 246                                                  GAsyncReadyCallback callback,
 247                                                  gpointer user_data);
 248 gboolean        e_data_book_get_contacts_finish (EDataBook *book,
 249                                                  GAsyncResult *result,
 250                                                  GSList **contacts,
 251                                                  GError **error);
 252 gboolean        e_data_book_get_contacts_sync   (EDataBook *book,
 253                                                  const gchar *sexp,
 254                                                  GSList **contacts,
 255                                                  GCancellable *cancellable,
 256                                                  GError **error);
 257
 258 void            e_data_book_get_contacts_uids   (EDataBook *book,
 259                                                  const gchar *sexp,
 260                                                  GCancellable *cancellable,
 261                                                  GAsyncReadyCallback callback,
 262                                                  gpointer user_data);
 263 gboolean        e_data_book_get_contacts_uids_finish
 264                                                 (EDataBook *book,
 265                                                  GAsyncResult *result,
 266                                                  GSList **contacts_uids,
 267                                                  GError **error);
 268 gboolean        e_data_book_get_contacts_uids_sync
 269                                                 (EDataBook *book,
 270                                                  const gchar *sexp,
 271                                                  GSList **contacts_uids,
 272                                                  GCancellable *cancellable,
 273                                                  GError **error);
 274
 275 #ifndef EDS_DISABLE_DEPRECATED
 276 void            e_data_book_respond_set_backend_property
 277                                                 (EDataBook *book,
 278                                                  guint32 opid,
 279                                                  GError *error);
 280 void            e_data_book_report_opened       (EDataBook *book,
 281                                                  const GError *error);
 282 void            e_data_book_report_readonly     (EDataBook *book,
 283                                                  gboolean readonly);
 284 void            e_data_book_report_online       (EDataBook *book,
 285                                                  gboolean is_online);
 286 #endif /* EDS_DISABLE_DEPRECATED */
 287
 288 G_END_DECLS
 289
 290 #endif /* E_DATA_BOOK_H */