camel-provider

camel-provider

Synopsis

#define             EDS_CAMEL_PROVIDER_DIR
                    CamelProvider;
enum                CamelProviderType;
enum                CamelProviderFlags;
#define             CAMEL_URL_PART_USER
#define             CAMEL_URL_PART_AUTH
#define             CAMEL_URL_PART_PASSWORD
#define             CAMEL_URL_PART_HOST
#define             CAMEL_URL_PART_PORT
#define             CAMEL_URL_PART_PATH
#define             CAMEL_URL_PART_PATH_DIR
#define             CAMEL_URL_PART_NEED
#define             CAMEL_URL_PART_HIDDEN
#define             CAMEL_PROVIDER_ALLOWS               (prov,
                                                         flags)
#define             CAMEL_PROVIDER_NEEDS                (prov,
                                                         flags)
#define             CAMEL_PROVIDER_HIDDEN               (prov,
                                                         flags)
enum                CamelProviderURLFlags;
#define             CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT(provider)
enum                CamelProviderConfType;
                    CamelProviderConfEntry;
                    CamelProviderPortEntry;
gint                (*CamelProviderAutoDetectFunc)      (CamelURL *url,
                                                         GHashTable **auto_detected,
                                                         GError **error);
struct              CamelProviderModule;
void                camel_provider_init                 (void);
gboolean            camel_provider_load                 (const gchar *path,
                                                         GError **error);
void                camel_provider_register             (CamelProvider *provider);
GList *             camel_provider_list                 (gboolean load);
CamelProvider *     camel_provider_get                  (const gchar *protocol,
                                                         GError **error);
void                camel_provider_module_init          (void);
gint                camel_provider_auto_detect          (CamelProvider *provider,
                                                         CamelURL *url,
                                                         GHashTable **auto_detected,
                                                         GError **error);

Description

Details

EDS_CAMEL_PROVIDER_DIR

#define EDS_CAMEL_PROVIDER_DIR    "EDS_CAMEL_PROVIDER_DIR"

This environment variable configures where the camel provider modules are loaded from.


CamelProvider

typedef struct {
	/* Provider protocol name (e.g. "imap", "smtp"). */
	const gchar *protocol;

	/* Provider name as used by people. (May be the same as protocol) */
	const gchar *name;

	/* Description of the provider. A novice user should be able
	 * to read this description, and the information provided by
	 * an ISP, IS department, etc, and determine whether or not
	 * this provider is relevant to him, and if so, which
	 * information goes with it.
	 */
	const gchar *description;

	/* The category of message that this provider works with.
	 * (evolution-mail will only list a provider in the store/transport
	 * config dialogs if its domain is "mail".)
	 */
	const gchar *domain;

	/* Flags describing the provider, flags describing its URLs */
	CamelProviderFlags flags;
	CamelProviderURLFlags url_flags;

	/* The ConfEntry and AutoDetect functions will probably be
	 * DEPRECATED in a future release */

	/* Extra configuration information */
	CamelProviderConfEntry *extra_conf;

	/* The list of CamelProviderPortEntry structs. Each struct contains 
	 * port number and a short string description ("Default IMAP port"
	 * or "POP3 over SSL" etc.
	 */
	CamelProviderPortEntry *port_entries;

	/* auto-detection function */
	CamelProviderAutoDetectFunc auto_detect;

	/* GType(s) of its store and/or transport. If both are
	 * set, then they are assumed to be linked together and the
	 * transport type can only be used in an account that also
	 * uses the store type (eg, Exchange or NNTP).
	 */
	GType object_types[CAMEL_NUM_PROVIDER_TYPES];

	/* GList of CamelServiceAuthTypes the provider supports */
	GList *authtypes;

	GHashFunc url_hash;
	GEqualFunc url_equal;

	/* gettext translation domain (NULL for providers in the
	 * evolution source tree).
	 */
	const gchar *translation_domain;

	/* Private to the provider */
	gpointer priv;
} CamelProvider;

enum CamelProviderType

typedef enum {
	CAMEL_PROVIDER_STORE,
	CAMEL_PROVIDER_TRANSPORT,
	CAMEL_NUM_PROVIDER_TYPES  /*< skip >*/
} CamelProviderType;

CAMEL_PROVIDER_STORE

CAMEL_PROVIDER_TRANSPORT

CAMEL_NUM_PROVIDER_TYPES


enum CamelProviderFlags

typedef enum {
 /*< flags >*/
	CAMEL_PROVIDER_IS_REMOTE = 1 << 0,
	CAMEL_PROVIDER_IS_LOCAL = 1 << 1,
	CAMEL_PROVIDER_IS_EXTERNAL = 1 << 2,
	CAMEL_PROVIDER_IS_SOURCE = 1 << 3,
	CAMEL_PROVIDER_IS_STORAGE = 1 << 4,
	CAMEL_PROVIDER_SUPPORTS_SSL = 1 << 5,
	CAMEL_PROVIDER_HAS_LICENSE = 1 << 6,
	CAMEL_PROVIDER_DISABLE_SENT_FOLDER = 1 << 7,
	CAMEL_PROVIDER_ALLOW_REAL_TRASH_FOLDER = 1 << 8,
	CAMEL_PROVIDER_ALLOW_REAL_JUNK_FOLDER = 1 << 9,
	CAMEL_PROVIDER_SUPPORTS_MOBILE_DEVICES = 1 << 10,
	CAMEL_PROVIDER_SUPPORTS_BATCH_FETCH = 1 << 11,
	CAMEL_PROVIDER_SUPPORTS_PURGE_MESSAGE_CACHE = 1 << 12
} CamelProviderFlags;

CAMEL_PROVIDER_IS_REMOTE

CAMEL_PROVIDER_IS_LOCAL

CAMEL_PROVIDER_IS_EXTERNAL

CAMEL_PROVIDER_IS_SOURCE

CAMEL_PROVIDER_IS_STORAGE

CAMEL_PROVIDER_SUPPORTS_SSL

CAMEL_PROVIDER_HAS_LICENSE

CAMEL_PROVIDER_DISABLE_SENT_FOLDER

CAMEL_PROVIDER_ALLOW_REAL_TRASH_FOLDER

CAMEL_PROVIDER_ALLOW_REAL_JUNK_FOLDER

CAMEL_PROVIDER_SUPPORTS_MOBILE_DEVICES

CAMEL_PROVIDER_SUPPORTS_BATCH_FETCH

CAMEL_PROVIDER_SUPPORTS_PURGE_MESSAGE_CACHE


CAMEL_URL_PART_USER

#define CAMEL_URL_PART_USER	 (1 << 0)

CAMEL_URL_PART_AUTH

#define CAMEL_URL_PART_AUTH	 (1 << 1)

CAMEL_URL_PART_PASSWORD

#define CAMEL_URL_PART_PASSWORD	 (1 << 2)

CAMEL_URL_PART_HOST

#define CAMEL_URL_PART_HOST	 (1 << 3)

CAMEL_URL_PART_PORT

#define CAMEL_URL_PART_PORT	 (1 << 4)

CAMEL_URL_PART_PATH

#define CAMEL_URL_PART_PATH	 (1 << 5)

CAMEL_URL_PART_PATH_DIR

#define CAMEL_URL_PART_PATH_DIR  (1 << 6)

CAMEL_URL_PART_NEED

#define CAMEL_URL_PART_NEED	       8

CAMEL_URL_PART_HIDDEN

#define CAMEL_URL_PART_HIDDEN (CAMEL_URL_PART_NEED + 8)

CAMEL_PROVIDER_ALLOWS()

#define             CAMEL_PROVIDER_ALLOWS(prov, flags)

CAMEL_PROVIDER_NEEDS()

#define             CAMEL_PROVIDER_NEEDS(prov, flags)

CAMEL_PROVIDER_HIDDEN()

#define             CAMEL_PROVIDER_HIDDEN(prov, flags)

enum CamelProviderURLFlags

typedef enum {
	CAMEL_URL_ALLOW_USER = CAMEL_URL_PART_USER,
	CAMEL_URL_ALLOW_AUTH = CAMEL_URL_PART_AUTH,
	CAMEL_URL_ALLOW_PASSWORD = CAMEL_URL_PART_PASSWORD,
	CAMEL_URL_ALLOW_HOST = CAMEL_URL_PART_HOST,
	CAMEL_URL_ALLOW_PORT = CAMEL_URL_PART_PORT,
	CAMEL_URL_ALLOW_PATH = CAMEL_URL_PART_PATH,

	CAMEL_URL_NEED_USER = CAMEL_URL_PART_USER << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_AUTH = CAMEL_URL_PART_AUTH << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_PASSWORD = CAMEL_URL_PART_PASSWORD << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_HOST = CAMEL_URL_PART_HOST << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_PORT = CAMEL_URL_PART_PORT << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_PATH = CAMEL_URL_PART_PATH << CAMEL_URL_PART_NEED,
	CAMEL_URL_NEED_PATH_DIR = CAMEL_URL_PART_PATH_DIR << CAMEL_URL_PART_NEED,

	CAMEL_URL_HIDDEN_USER = CAMEL_URL_PART_USER << CAMEL_URL_PART_HIDDEN,
	CAMEL_URL_HIDDEN_AUTH = CAMEL_URL_PART_AUTH << CAMEL_URL_PART_HIDDEN,
	CAMEL_URL_HIDDEN_PASSWORD = CAMEL_URL_PART_PASSWORD << CAMEL_URL_PART_HIDDEN,
	CAMEL_URL_HIDDEN_HOST = CAMEL_URL_PART_HOST << CAMEL_URL_PART_HIDDEN,
	CAMEL_URL_HIDDEN_PORT = CAMEL_URL_PART_PORT << CAMEL_URL_PART_HIDDEN,
	CAMEL_URL_HIDDEN_PATH = CAMEL_URL_PART_PATH << CAMEL_URL_PART_HIDDEN,

	CAMEL_URL_FRAGMENT_IS_PATH = 1 << 30, /* url uses fragment for folder name path, not path */
	CAMEL_URL_PATH_IS_ABSOLUTE = 1 << 31,
} CamelProviderURLFlags;

CAMEL_URL_ALLOW_USER

CAMEL_URL_ALLOW_AUTH

CAMEL_URL_ALLOW_PASSWORD

CAMEL_URL_ALLOW_HOST

CAMEL_URL_ALLOW_PORT

CAMEL_URL_ALLOW_PATH

CAMEL_URL_NEED_USER

CAMEL_URL_NEED_AUTH

CAMEL_URL_NEED_PASSWORD

CAMEL_URL_NEED_HOST

CAMEL_URL_NEED_PORT

CAMEL_URL_NEED_PATH

CAMEL_URL_NEED_PATH_DIR

CAMEL_URL_HIDDEN_USER

CAMEL_URL_HIDDEN_AUTH

CAMEL_URL_HIDDEN_PASSWORD

CAMEL_URL_HIDDEN_HOST

CAMEL_URL_HIDDEN_PORT

CAMEL_URL_HIDDEN_PATH

CAMEL_URL_FRAGMENT_IS_PATH

CAMEL_URL_PATH_IS_ABSOLUTE


CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT()

#define             CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT(provider)

enum CamelProviderConfType

typedef enum {
	CAMEL_PROVIDER_CONF_END,
	CAMEL_PROVIDER_CONF_SECTION_START,
	CAMEL_PROVIDER_CONF_SECTION_END,
	CAMEL_PROVIDER_CONF_CHECKBOX,
	CAMEL_PROVIDER_CONF_CHECKSPIN,
	CAMEL_PROVIDER_CONF_ENTRY,
	CAMEL_PROVIDER_CONF_LABEL,
	CAMEL_PROVIDER_CONF_HIDDEN,
	CAMEL_PROVIDER_CONF_OPTIONS
} CamelProviderConfType;

CAMEL_PROVIDER_CONF_END

CAMEL_PROVIDER_CONF_SECTION_START

CAMEL_PROVIDER_CONF_SECTION_END

CAMEL_PROVIDER_CONF_CHECKBOX

CAMEL_PROVIDER_CONF_CHECKSPIN

CAMEL_PROVIDER_CONF_ENTRY

CAMEL_PROVIDER_CONF_LABEL

CAMEL_PROVIDER_CONF_HIDDEN

CAMEL_PROVIDER_CONF_OPTIONS


CamelProviderConfEntry

typedef struct {
	CamelProviderConfType type;
	const gchar *name, *depname;
	const gchar *text, *value;
} CamelProviderConfEntry;

CamelProviderPortEntry

typedef struct {
	gint port;
	const gchar *desc;
	gboolean is_ssl;
} CamelProviderPortEntry;

Since 3.2


CamelProviderAutoDetectFunc ()

gint                (*CamelProviderAutoDetectFunc)      (CamelURL *url,
                                                         GHashTable **auto_detected,
                                                         GError **error);

struct CamelProviderModule

struct CamelProviderModule {
	gchar *path;
	GSList *types;
	guint loaded : 1;
};

camel_provider_init ()

void                camel_provider_init                 (void);

Initialize the Camel provider system by reading in the .urls files in the provider directory and creating a hash table mapping URLs to module names.

A .urls file has the same initial prefix as the shared library it correspond to, and consists of a series of lines containing the URL protocols that that library handles.

TODO: This should be pathed? TODO: This should be plugin-d?


camel_provider_load ()

gboolean            camel_provider_load                 (const gchar *path,
                                                         GError **error);

Loads the provider at path, and calls its initialization function, passing session as an argument. The provider should then register itself with session.

path :

the path to a shared library

error :

return location for a GError, or NULL

Returns :

TRUE on success, FALSE on failure

camel_provider_register ()

void                camel_provider_register             (CamelProvider *provider);

Registers a provider.

provider :

provider object

camel_provider_list ()

GList *             camel_provider_list                 (gboolean load);

camel_provider_get ()

CamelProvider *     camel_provider_get                  (const gchar *protocol,
                                                         GError **error);

Returns the registered CamelProvider for protocol, loading it from disk if necessary. If no CamelProvider can be found for protocol, or the provider module fails to load, the function sets error and returns NULL.

The returned CamelProvider is owned by Camel and should not be modified or freed.

protocol :

a CamelProvider protocol name

error :

return location for a GError, or NULL

Returns :

a CamelProvider for protocol, or NULL

camel_provider_module_init ()

void                camel_provider_module_init          (void);

camel_provider_auto_detect ()

gint                camel_provider_auto_detect          (CamelProvider *provider,
                                                         CamelURL *url,
                                                         GHashTable **auto_detected,
                                                         GError **error);

After filling in the standard Username/Hostname/Port/Path settings (which must be set in url), if the provider supports it, you may wish to have the provider auto-detect further settings based on the aformentioned settings.

If the provider does not support auto-detection, auto_detected will be set to NULL. Otherwise the provider will attempt to auto-detect whatever it can and file them into auto_detected. If for some reason it cannot auto-detect anything (not enough information provided in url?) then auto_detected will be set to NULL and an exception may be set to explain why it failed.

provider :

camel provider

url :

a CamelURL

auto_detected :

output hash table of auto-detected values

error :

return location for a GError, or NULL

Returns :

0 on success or -1 on fail.