## ESourceCamel

ESourceCamel — ESource extension for CamelSettings

## Synopsis

    #include <libedataserver/libedataserver.h>

    struct              ESourceCamel;
    void                e_source_camel_register_types       (void);
    GType               e_source_camel_generate_subtype     (const gchar *protocol,
                                                             GType settings_type);
    CamelSettings *     e_source_camel_get_settings         (ESourceCamel *extension);
    const gchar *       e_source_camel_get_type_name        (const gchar *protocol);
    const gchar *       e_source_camel_get_extension_name   (const gchar *protocol);
    void                e_source_camel_configure_service    (ESource *source,
                                                             CamelService *service);

## Object Hierarchy

      GObject
       +----ESourceExtension
             +----ESourceCamel

## Properties

      "settings"                 CamelSettings*        : Read

## Description

ESourceCamel itself is abstract. Its sole function is to bridge GObject properties from the CamelSettings framework to the ESource framework. It does this by procedurally registering an ESourceCamel subtype for each available CamelService subtype, and then registering GObject properties to proxy the properties in the corresponding CamelSettings subtype. The ESourceCamel owns an instance of the appropriate CamelSettings subtype, and redirects all get/set operations on its own GObject properties to its CamelSettings instance. The CamelSettings instance, now fully initialized from a key file, can then be inserted into a new CamelService instance using `camel_service_set_settings()`.

Ultimately, this is all just implementation detail for glueing two unrelated class hierarchies together. If you need to access provider specific settings, use the CamelSettings API, not this.

## Details

### struct ESourceCamel

    struct ESourceCamel;

Contains only private data that should be read and manipulated using the functions below.

Since 3.6

### e_source_camel_register_types ()

    void                e_source_camel_register_types       (void);

Creates and registers subclasses of ESourceCamel for each available CamelProvider. This function should be called once during application or library initialization.

Since 3.6

### e_source_camel_generate_subtype ()

    GType               e_source_camel_generate_subtype     (const gchar *protocol,
                                                             GType settings_type);

Generates a custom ESourceCamel subtype for `protocol`. Instances of the new subtype will contain a CamelSettings instance of type `settings_type`.

This function is called as part of `e_source_camel_register_types()` and should not be called explicitly, except by some groupware packages that need to share package-specific settings across their mail, calendar and address book components. In that case the groupware package may choose to subclass CamelSettings rather than ESourceExtension since libcamel is the lowest common denominator across all components. This function provides a way for the calendar and address book components of such a package to generate an ESourceCamel subtype for its CamelSettings subtype without having to load all available CamelProvider modules.

`protocol` : | a CamelProvider protocol
`settings_type` : | a subtype of CamelSettings
Returns : | the GType of the generated ESourceCamel subtype

Since 3.6

### e_source_camel_get_settings ()

    CamelSettings *     e_source_camel_get_settings         (ESourceCamel *extension);

Returns `extension`'s "settings" instance, pre-configured from the ESource to which `extension` belongs. Changes to the ESource will automatically propagate to the "settings" instance and vice versa.

This is essentially the glue that binds ESource to CamelService. See `e_source_camel_configure_service()`.

`extension` : | an ESourceCamel
Returns : | a configured CamelSettings instance

Since 3.6

### e_source_camel_get_type_name ()

    const gchar *       e_source_camel_get_type_name        (const gchar *protocol);

Returns the GType name of the registered ESourceCamel subtype for `protocol`.

For example, given a protocol named "imap" the function would return "ESourceCamelImap".

`protocol` : | a CamelProvider protocol
Returns : | the ESourceCamel type name for `protocol`

Since 3.6

### e_source_camel_get_extension_name ()

    const gchar *       e_source_camel_get_extension_name   (const gchar *protocol);

Returns the extension name for the ESourceCamel subtype for `protocol`. The extension name can then be passed to `e_source_get_extension()` to obtain an instance of the ESourceCamel subtype.

For example, given a protocol named "imap" the function would return "Imap Backend".

`protocol` : | a CamelProvider protocol
Returns : | the ESourceCamel extension name for `protocol`

Since 3.6

### e_source_camel_configure_service ()

    void                e_source_camel_configure_service    (ESource *source,
                                                             CamelService *service);

This function essentially glues together `source` and `serivce` so their configuration settings stay synchronized. The glue itself is a shared CamelSettings instance.

Call this function immediately after creating a new CamelService with `camel_session_add_service()`.

`source` : | an ESource
`service` : | a CamelService

Since 3.6

## Property Details

### The `"settings"` property

      "settings"                 CamelSettings*        : Read

The CamelSettings instance being proxied.