camel/camel-provider.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
   2 /* camel-provider.h :  provider definition  */
   3
   4 /*
   5  *
   6  * Authors:
   7  *  Bertrand Guiheneuf <bertrand@helixcode.com>
   8  *  Jeffrey Stedfast <fejj@ximian.com>
   9  *
  10  * Copyright (C) 1999-2008 Novell, Inc. (www.novell.com)
  11  *
  12  * This program is free software; you can redistribute it and/or
  13  * modify it under the terms of version 2 of the GNU Lesser General Public
  14  * License as published by the Free Software Foundation.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
  24  * USA
  25  */
  26
  27 #if !defined (__CAMEL_H_INSIDE__) && !defined (CAMEL_COMPILATION)
  28 #error "Only <camel/camel.h> can be included directly."
  29 #endif
  30
  31 #ifndef CAMEL_PROVIDER_H
  32 #define CAMEL_PROVIDER_H
  33
  34 #include <camel/camel-enums.h>
  35 #include <camel/camel-object.h>
  36 #include <camel/camel-object-bag.h>
  37 #include <camel/camel-url.h>
  38
  39 #define CAMEL_PROVIDER(obj) ((CamelProvider *)(obj))
  40
  41 G_BEGIN_DECLS
  42
  43 extern gchar *camel_provider_type_name[CAMEL_NUM_PROVIDER_TYPES];
  44
  45 /* Flags for url_flags. "ALLOW" means the config dialog will let the
  46  * user configure it. "NEED" implies "ALLOW" but means the user must
  47  * configure it. Service code can assume that any url part for which
  48  * it has set the NEED flag will be set when the service is
  49  * created. "HIDE" also implies "ALLOW", but the setting will be
  50  * hidden/no widgets created for it.
  51  */
  52 #define CAMEL_URL_PART_USER      (1 << 0)
  53 #define CAMEL_URL_PART_AUTH      (1 << 1)
  54 #define CAMEL_URL_PART_PASSWORD  (1 << 2)
  55 #define CAMEL_URL_PART_HOST      (1 << 3)
  56 #define CAMEL_URL_PART_PORT      (1 << 4)
  57 #define CAMEL_URL_PART_PATH      (1 << 5)
  58 #define CAMEL_URL_PART_PATH_DIR  (1 << 6)
  59
  60 #define CAMEL_URL_PART_NEED            8
  61 #define CAMEL_URL_PART_HIDDEN   (CAMEL_URL_PART_NEED + 8)
  62
  63 /* Use these macros to test a provider's url_flags */
  64 #define CAMEL_PROVIDER_ALLOWS(prov, flags) \
  65         (prov->url_flags & (flags | (flags << CAMEL_URL_PART_NEED) | (flags << CAMEL_URL_PART_HIDDEN)))
  66 #define CAMEL_PROVIDER_NEEDS(prov, flags) \
  67         (prov->url_flags & (flags << CAMEL_URL_PART_NEED))
  68 #define CAMEL_PROVIDER_HIDDEN(prov, flags) \
  69         (prov->url_flags & (flags << CAMEL_URL_PART_HIDDEN))
  70
  71 /* Providers use these macros to actually define their url_flags */
  72 typedef enum {
  73         CAMEL_URL_ALLOW_USER       = CAMEL_URL_PART_USER,
  74         CAMEL_URL_ALLOW_AUTH       = CAMEL_URL_PART_AUTH,
  75         CAMEL_URL_ALLOW_PASSWORD   = CAMEL_URL_PART_PASSWORD,
  76         CAMEL_URL_ALLOW_HOST       = CAMEL_URL_PART_HOST,
  77         CAMEL_URL_ALLOW_PORT       = CAMEL_URL_PART_PORT,
  78         CAMEL_URL_ALLOW_PATH       = CAMEL_URL_PART_PATH,
  79
  80         CAMEL_URL_NEED_USER        = CAMEL_URL_PART_USER << CAMEL_URL_PART_NEED,
  81         CAMEL_URL_NEED_AUTH        = CAMEL_URL_PART_AUTH << CAMEL_URL_PART_NEED,
  82         CAMEL_URL_NEED_PASSWORD    = CAMEL_URL_PART_PASSWORD << CAMEL_URL_PART_NEED,
  83         CAMEL_URL_NEED_HOST        = CAMEL_URL_PART_HOST << CAMEL_URL_PART_NEED,
  84         CAMEL_URL_NEED_PORT        = CAMEL_URL_PART_PORT << CAMEL_URL_PART_NEED,
  85         CAMEL_URL_NEED_PATH        = CAMEL_URL_PART_PATH << CAMEL_URL_PART_NEED,
  86         CAMEL_URL_NEED_PATH_DIR    = CAMEL_URL_PART_PATH_DIR << CAMEL_URL_PART_NEED,
  87
  88         CAMEL_URL_HIDDEN_USER      = CAMEL_URL_PART_USER << CAMEL_URL_PART_HIDDEN,
  89         CAMEL_URL_HIDDEN_AUTH      = CAMEL_URL_PART_AUTH << CAMEL_URL_PART_HIDDEN,
  90         CAMEL_URL_HIDDEN_PASSWORD  = CAMEL_URL_PART_PASSWORD << CAMEL_URL_PART_HIDDEN,
  91         CAMEL_URL_HIDDEN_HOST      = CAMEL_URL_PART_HOST << CAMEL_URL_PART_HIDDEN,
  92         CAMEL_URL_HIDDEN_PORT      = CAMEL_URL_PART_PORT << CAMEL_URL_PART_HIDDEN,
  93         CAMEL_URL_HIDDEN_PATH      = CAMEL_URL_PART_PATH << CAMEL_URL_PART_HIDDEN,
  94
  95         CAMEL_URL_FRAGMENT_IS_PATH = 1 << 30, /* url uses fragment for folder name path, not path */
  96         CAMEL_URL_PATH_IS_ABSOLUTE = 1 << 31,
  97 } CamelProviderURLFlags;
  98
  99 #define CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT(provider) \
 100         ((provider != NULL) && \
 101         (provider->object_types[CAMEL_PROVIDER_STORE] != G_TYPE_INVALID) && \
 102         (provider->object_types[CAMEL_PROVIDER_TRANSPORT] != G_TYPE_INVALID))
 103
 104 /* Generic extra config stuff */
 105
 106 typedef struct {
 107         CamelProviderConfType type;
 108         const gchar *name, *depname;
 109         const gchar *text, *value;
 110 } CamelProviderConfEntry;
 111
 112 /**
 113  * CamelProviderPortEntry:
 114  *
 115  * Since: 3.2
 116  **/
 117 typedef struct {
 118         gint port;
 119         const gchar *desc;
 120         gboolean is_ssl;
 121 } CamelProviderPortEntry;
 122
 123 typedef gint (*CamelProviderAutoDetectFunc) (CamelURL *url, GHashTable **auto_detected, GError **error);
 124
 125 typedef struct {
 126         /* Provider protocol name (e.g. "imap", "smtp"). */
 127         const gchar *protocol;
 128
 129         /* Provider name as used by people. (May be the same as protocol) */
 130         const gchar *name;
 131
 132         /* Description of the provider. A novice user should be able
 133          * to read this description, and the information provided by
 134          * an ISP, IS department, etc, and determine whether or not
 135          * this provider is relevant to him, and if so, which
 136          * information goes with it.
 137          */
 138         const gchar *description;
 139
 140         /* The category of message that this provider works with.
 141          * (evolution-mail will only list a provider in the store/transport
 142          * config dialogs if its domain is "mail".)
 143          */
 144         const gchar *domain;
 145
 146         /* Flags describing the provider, flags describing its URLs */
 147         CamelProviderFlags flags;
 148         CamelProviderURLFlags url_flags;
 149
 150         /* The ConfEntry and AutoDetect functions will probably be
 151          * DEPRECATED in a future release */
 152
 153         /* Extra configuration information */
 154         CamelProviderConfEntry *extra_conf;
 155
 156         /* The list of CamelProviderPortEntry structs. Each struct contains
 157          * port number and a short string description ("Default IMAP port"
 158          * or "POP3 over SSL" etc.
 159          */
 160         CamelProviderPortEntry *port_entries;
 161
 162         /* auto-detection function */
 163         CamelProviderAutoDetectFunc auto_detect;
 164
 165         /* GType(s) of its store and/or transport. If both are
 166          * set, then they are assumed to be linked together and the
 167          * transport type can only be used in an account that also
 168          * uses the store type (eg, Exchange or NNTP).
 169          */
 170         GType object_types[CAMEL_NUM_PROVIDER_TYPES];
 171
 172         /* GList of CamelServiceAuthTypes the provider supports */
 173         GList *authtypes;
 174
 175         GHashFunc url_hash;
 176         GEqualFunc url_equal;
 177
 178         /* gettext translation domain (NULL for providers in the
 179          * evolution source tree).
 180          */
 181         const gchar *translation_domain;
 182
 183         /* Private to the provider */
 184         gpointer priv;
 185 } CamelProvider;
 186
 187 typedef struct _CamelProviderModule CamelProviderModule;
 188
 189 struct _CamelProviderModule {
 190         gchar *path;
 191         GSList *types;
 192         guint loaded : 1;
 193 };
 194
 195 void            camel_provider_init             (void);
 196 gboolean        camel_provider_load             (const gchar *path,
 197                                                  GError **error);
 198 void            camel_provider_register         (CamelProvider *provider);
 199 GList *         camel_provider_list             (gboolean load);
 200 CamelProvider * camel_provider_get              (const gchar *protocol,
 201                                                  GError **error);
 202
 203 /* This is defined by each module, not by camel-provider.c. */
 204 void            camel_provider_module_init      (void);
 205
 206 gint            camel_provider_auto_detect      (CamelProvider *provider,
 207                                                  CamelURL *url,
 208                                                  GHashTable **auto_detected,
 209                                                  GError **error);
 210
 211 G_END_DECLS
 212
 213 #endif /* CAMEL_PROVIDER_H */