camel/camel-service.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /* camel-service.h : Abstract class for an email service */
   3 /*
   4  *
   5  * Authors: Bertrand Guiheneuf <bertrand@helixcode.com>
   6  *          Michael Zucchi <notzed@ximian.com>
   7  *
   8  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of version 2 of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  22  * USA
  23  */
  24
  25 #if !defined (__CAMEL_H_INSIDE__) && !defined (CAMEL_COMPILATION)
  26 #error "Only <camel/camel.h> can be included directly."
  27 #endif
  28
  29 #ifndef CAMEL_SERVICE_H
  30 #define CAMEL_SERVICE_H
  31
  32 #include <camel/camel-enums.h>
  33 #include <camel/camel-object.h>
  34 #include <camel/camel-url.h>
  35 #include <camel/camel-provider.h>
  36 #include <camel/camel-operation.h>
  37 #include <camel/camel-settings.h>
  38
  39 /* Standard GObject macros */
  40 #define CAMEL_TYPE_SERVICE \
  41         (camel_service_get_type ())
  42 #define CAMEL_SERVICE(obj) \
  43         (G_TYPE_CHECK_INSTANCE_CAST \
  44         ((obj), CAMEL_TYPE_SERVICE, CamelService))
  45 #define CAMEL_SERVICE_CLASS(cls) \
  46         (G_TYPE_CHECK_CLASS_CAST \
  47         ((cls), CAMEL_TYPE_SERVICE, CamelServiceClass))
  48 #define CAMEL_IS_SERVICE(obj) \
  49         (G_TYPE_CHECK_INSTANCE_TYPE \
  50         ((obj), CAMEL_TYPE_SERVICE))
  51 #define CAMEL_IS_SERVICE_CLASS(obj) \
  52         (G_TYPE_CHECK_CLASS_TYPE \
  53         ((cls), CAMEL_TYPE_SERVICE))
  54 #define CAMEL_SERVICE_GET_CLASS(obj) \
  55         (G_TYPE_INSTANCE_GET_CLASS \
  56         ((obj), CAMEL_TYPE_SERVICE, CamelServiceClass))
  57
  58 /**
  59  * CAMEL_SERVICE_ERROR:
  60  *
  61  * Since: 2.32
  62  **/
  63 #define CAMEL_SERVICE_ERROR \
  64         (camel_service_error_quark ())
  65
  66 G_BEGIN_DECLS
  67
  68 struct _CamelSession;
  69
  70 typedef struct _CamelService CamelService;
  71 typedef struct _CamelServiceClass CamelServiceClass;
  72 typedef struct _CamelServicePrivate CamelServicePrivate;
  73
  74 /**
  75  * CamelServiceError:
  76  *
  77  * Since: 2.32
  78  **/
  79 typedef enum {
  80         CAMEL_SERVICE_ERROR_INVALID,
  81         CAMEL_SERVICE_ERROR_URL_INVALID,
  82         CAMEL_SERVICE_ERROR_UNAVAILABLE,
  83         CAMEL_SERVICE_ERROR_CANT_AUTHENTICATE,
  84         CAMEL_SERVICE_ERROR_NOT_CONNECTED
  85 } CamelServiceError;
  86
  87 struct _CamelService {
  88         CamelObject parent;
  89         CamelServicePrivate *priv;
  90 };
  91
  92 struct _CamelServiceClass {
  93         CamelObjectClass parent_class;
  94
  95         GType settings_type;
  96
  97         /* Non-Blocking Methods */
  98         gchar *         (*get_name)             (CamelService *service,
  99                                                  gboolean brief);
 100
 101         /* Synchronous I/O Methods */
 102         gboolean        (*connect_sync)         (CamelService *service,
 103                                                  GCancellable *cancellable,
 104                                                  GError **error);
 105         gboolean        (*disconnect_sync)      (CamelService *service,
 106                                                  gboolean clean,
 107                                                  GCancellable *cancellable,
 108                                                  GError **error);
 109         CamelAuthenticationResult
 110                         (*authenticate_sync)    (CamelService *service,
 111                                                  const gchar *mechanism,
 112                                                  GCancellable *cancellable,
 113                                                  GError **error);
 114         GList *         (*query_auth_types_sync)
 115                                                 (CamelService *service,
 116                                                  GCancellable *cancellable,
 117                                                  GError **error);
 118
 119         /* Asynchronous I/O Methods (all have defaults) */
 120         void            (*connect)              (CamelService *service,
 121                                                  gint io_priority,
 122                                                  GCancellable *cancellable,
 123                                                  GAsyncReadyCallback callback,
 124                                                  gpointer user_data);
 125         gboolean        (*connect_finish)       (CamelService *service,
 126                                                  GAsyncResult *result,
 127                                                  GError **error);
 128         void            (*disconnect)           (CamelService *service,
 129                                                  gboolean clean,
 130                                                  gint io_priority,
 131                                                  GCancellable *cancellable,
 132                                                  GAsyncReadyCallback callback,
 133                                                  gpointer user_data);
 134         gboolean        (*disconnect_finish)    (CamelService *service,
 135                                                  GAsyncResult *result,
 136                                                  GError **error);
 137         void            (*authenticate)         (CamelService *service,
 138                                                  const gchar *mechanism,
 139                                                  gint io_priority,
 140                                                  GCancellable *cancellable,
 141                                                  GAsyncReadyCallback callback,
 142                                                  gpointer user_data);
 143         CamelAuthenticationResult
 144                         (*authenticate_finish)  (CamelService *service,
 145                                                  GAsyncResult *result,
 146                                                  GError **error);
 147         void            (*query_auth_types)     (CamelService *service,
 148                                                  gint io_priority,
 149                                                  GCancellable *cancellable,
 150                                                  GAsyncReadyCallback callback,
 151                                                  gpointer user_data);
 152         GList *         (*query_auth_types_finish)
 153                                                 (CamelService *service,
 154                                                  GAsyncResult *result,
 155                                                  GError **error);
 156 };
 157
 158 /* query_auth_types returns a GList of these */
 159 typedef struct {
 160         const gchar *name;               /* user-friendly name */
 161         const gchar *description;
 162         const gchar *authproto;
 163
 164         gboolean need_password;   /* needs a password to authenticate */
 165 } CamelServiceAuthType;
 166
 167 GType           camel_service_get_type          (void);
 168 GQuark          camel_service_error_quark       (void) G_GNUC_CONST;
 169 void            camel_service_migrate_files     (CamelService *service);
 170 CamelURL *      camel_service_new_camel_url     (CamelService *service);
 171 CamelServiceConnectionStatus
 172                 camel_service_get_connection_status
 173                                                 (CamelService *service);
 174 const gchar *   camel_service_get_display_name  (CamelService *service);
 175 void            camel_service_set_display_name  (CamelService *service,
 176                                                  const gchar *display_name);
 177 const gchar *   camel_service_get_password      (CamelService *service);
 178 void            camel_service_set_password      (CamelService *service,
 179                                                  const gchar *password);
 180 const gchar *   camel_service_get_user_data_dir (CamelService *service);
 181 const gchar *   camel_service_get_user_cache_dir
 182                                                 (CamelService *service);
 183 gchar *         camel_service_get_name          (CamelService *service,
 184                                                  gboolean brief);
 185 CamelProvider * camel_service_get_provider      (CamelService *service);
 186 struct _CamelSession *
 187                 camel_service_get_session       (CamelService *service);
 188 CamelSettings * camel_service_ref_settings      (CamelService *service);
 189 void            camel_service_set_settings      (CamelService *service,
 190                                                  CamelSettings *settings);
 191 const gchar *   camel_service_get_uid           (CamelService *service);
 192
 193 gboolean        camel_service_connect_sync      (CamelService *service,
 194                                                  GCancellable *cancellable,
 195                                                  GError **error);
 196 void            camel_service_connect           (CamelService *service,
 197                                                  gint io_priority,
 198                                                  GCancellable *cancellable,
 199                                                  GAsyncReadyCallback callback,
 200                                                  gpointer user_data);
 201 gboolean        camel_service_connect_finish    (CamelService *service,
 202                                                  GAsyncResult *result,
 203                                                  GError **error);
 204 gboolean        camel_service_disconnect_sync   (CamelService *service,
 205                                                  gboolean clean,
 206                                                  GCancellable *cancellable,
 207                                                  GError **error);
 208 void            camel_service_disconnect        (CamelService *service,
 209                                                  gboolean clean,
 210                                                  gint io_priority,
 211                                                  GCancellable *cancellable,
 212                                                  GAsyncReadyCallback callback,
 213                                                  gpointer user_data);
 214 gboolean        camel_service_disconnect_finish (CamelService *service,
 215                                                  GAsyncResult *result,
 216                                                  GError **error);
 217 CamelAuthenticationResult
 218                 camel_service_authenticate_sync (CamelService *service,
 219                                                  const gchar *mechanism,
 220                                                  GCancellable *cancellable,
 221                                                  GError **error);
 222 void            camel_service_authenticate      (CamelService *service,
 223                                                  const gchar *mechanism,
 224                                                  gint io_priority,
 225                                                  GCancellable *cancellable,
 226                                                  GAsyncReadyCallback callback,
 227                                                  gpointer user_data);
 228 CamelAuthenticationResult
 229                 camel_service_authenticate_finish
 230                                                 (CamelService *service,
 231                                                  GAsyncResult *result,
 232                                                  GError **error);
 233 GList *         camel_service_query_auth_types_sync
 234                                                 (CamelService *service,
 235                                                  GCancellable *cancellable,
 236                                                  GError **error);
 237 void            camel_service_query_auth_types  (CamelService *service,
 238                                                  gint io_priority,
 239                                                  GCancellable *cancellable,
 240                                                  GAsyncReadyCallback callback,
 241                                                  gpointer user_data);
 242 GList *         camel_service_query_auth_types_finish
 243                                                 (CamelService *service,
 244                                                  GAsyncResult *result,
 245                                                  GError **error);
 246
 247 G_END_DECLS
 248
 249 #endif /* CAMEL_SERVICE_H */