camel-provider: Camel Reference Manual

## camel-provider camel-provider |

## Functions

#define | CAMEL_URL_PART_PATH_DIR
#define | CAMEL_PROVIDER_ALLOWS()
#define | CAMEL_PROVIDER_NEEDS()
#define | CAMEL_PROVIDER_HIDDEN()
#define | CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT()
gint | (*CamelProviderAutoDetectFunc) ()
void | camel_provider_init ()
gboolean | camel_provider_load ()
void | camel_provider_register ()
GList * | camel_provider_list ()
CamelProvider * | camel_provider_get ()
void | camel_provider_module_init ()
gint | camel_provider_auto_detect ()

## Types and Values

#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_NEED
#define | CAMEL_URL_PART_HIDDEN
enum | CamelProviderURLFlags
enum | CamelProviderConfType
| CamelProviderConfEntry
| CamelProviderPortEntry
struct | CamelProviderModule

## Description

## Functions

### CAMEL_URL_PART_PATH_DIR

    #define CAMEL_URL_PART_PATH_DIR  (1 << 6)

### 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)

### CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT()

    #define             CAMEL_PROVIDER_IS_STORE_AND_TRANSPORT(provider)

### CamelProviderAutoDetectFunc ()

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

### 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` .

#### Parameters

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.

#### Parameters

provider | provider object |

### camel_provider_list ()

    GList *
    camel_provider_list (gboolean load);

This returns a list of available providers. If `load` is `TRUE`, it will first load in all available providers that haven't yet been loaded.

Free the returned list with `g_list_free()`. The CamelProvider structs in the list are owned by Camel and should not be modified or freed.

#### Parameters

load | whether or not to load in providers that are not already loaded |

#### Returns

a GList of CamelProvider structs

### 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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### 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

#### Members

CAMEL_PROVIDER_STORE |  |
CAMEL_PROVIDER_TRANSPORT |  |
CAMEL_NUM_PROVIDER_TYPES |  |

### enum CamelProviderFlags

#### Members

CAMEL_PROVIDER_IS_REMOTE | Provider works with remote data. |
CAMEL_PROVIDER_IS_LOCAL | Provider can be used as a backend for local folder tree folders. (Not just the opposite of CAMEL_PROVIDER_IS_REMOTE.) |
CAMEL_PROVIDER_IS_EXTERNAL | Provider appears in the folder tree but is not created by the mail component. |
CAMEL_PROVIDER_IS_SOURCE | Mail arrives there, so it should be offered as an option in the mail config dialog. |
CAMEL_PROVIDER_IS_STORAGE | Mail is stored there. It will appear in the folder tree. |
CAMEL_PROVIDER_SUPPORTS_SSL |  |
CAMEL_PROVIDER_HAS_LICENSE | Provider configuration first needs the license to be accepted. (No longer used.) |
CAMEL_PROVIDER_DISABLE_SENT_FOLDER |  |
CAMEL_PROVIDER_ALLOW_REAL_TRASH_FOLDER | Provider may use a real trash folder instead of a virtual folder. |
CAMEL_PROVIDER_ALLOW_REAL_JUNK_FOLDER | Provider may use a real junk folder instead of a virtual folder. |
CAMEL_PROVIDER_SUPPORTS_MOBILE_DEVICES | Download limited set of emails instead of operating on full cache. |
CAMEL_PROVIDER_SUPPORTS_BATCH_FETCH | Support to fetch messages in batch. |
CAMEL_PROVIDER_SUPPORTS_PURGE_MESSAGE_CACHE | Support to remove oldest downloaded messages to conserve space. |

### 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_NEED

    #define CAMEL_URL_PART_NEED	       8

### CAMEL_URL_PART_HIDDEN

    #define CAMEL_URL_PART_HIDDEN (CAMEL_URL_PART_NEED + 8)

### enum CamelProviderURLFlags

#### Members

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 |  |

### enum CamelProviderConfType

#### Members

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

### struct CamelProviderModule

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