## KolabSettingsHandler KolabSettingsHandler — aggregate Evolution settings data |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    enum                KolabSettingsHandlerBoolFieldID;
    enum                KolabSettingsHandlerCharFieldID;
    struct              KolabSettingsHandlerClass;
    enum                KolabSettingsHandlerIntFieldID;
    enum                KolabSettingsHandlerTblID;
    enum                KolabSettingsHandlerUintFieldID;
    gboolean            kolab_settings_handler_bringup      (KolabSettingsHandler *self,
                                                             GError **err);
    gboolean            kolab_settings_handler_configure    (KolabSettingsHandler *self,
                                                             KolabFolderContextID context,
                                                             GError **err);
    gboolean            kolab_settings_handler_get_bool_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerBoolFieldID field_id,
                                                             GError **err);
    const gchar *       kolab_settings_handler_get_char_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerCharFieldID field_id,
                                                             GError **err);
    gint                kolab_settings_handler_get_int_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerIntFieldID field_id,
                                                             GError **err);
    guint               kolab_settings_handler_get_uint_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerUintFieldID field_id,
                                                             GError **err);
    gconstpointer       kolab_settings_handler_get_value    (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerTblID tbl_id,
                                                             const gchar *key,
                                                             GError **err);
    gboolean            kolab_settings_handler_set_bool_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerBoolFieldID field_id,
                                                             gboolean value,
                                                             GError **err);
    gboolean            kolab_settings_handler_set_char_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerCharFieldID field_id,
                                                             gchar *value,
                                                             GError **err);
    gboolean            kolab_settings_handler_set_int_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerIntFieldID field_id,
                                                             gint value,
                                                             GError **err);
    gboolean            kolab_settings_handler_set_uint_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerUintFieldID field_id,
                                                             guint value,
                                                             GError **err);
    gboolean            kolab_settings_handler_set_value    (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerTblID tbl_id,
                                                             const gchar *key,
                                                             gpointer value,
                                                             GError **err);
    gboolean            kolab_settings_handler_shutdown     (KolabSettingsHandler *self,
                                                             GError **err);

## Description

This class is handles all Kolab (account) settings for the Kolab backends. This means (mostly) reading the settings information created by the Evolution frontend and encapsulating operations concerning EAccount and ESource classes. One instance of this class will live in each backend process and is passed to KolabMailAccess (and by KolabMailAccess, on to all of it's subordinate objects).

Some of the MAPI ExchangeMAPIAccountListener functionality will be replicated, which is

- checking for new Kolab2 account types showing up (EAccount)
- creating an associated ESource object and add it to the backend's ESourceGroup, so it can be advertised to the frontend

In MAPI, ExchangeMAPIAccountListener is part of the MAPI EPlugin. According to mbarnes, the account listener's functionality should be working in backend context as well, so no need to place this into an EPlugin (what's more, again according to mbarnes, EPlugin is going to be replaced entirely by another framework, presumably GTypeModule, so no point in creating an elaborated EPlugin now, anyway).

This account listener could peek (new) EAccount for (new) Kolab2 ones and create ESourceGroup elements accordingly. Since a backend process needs to be started only when at least one Kolab2 EAccount is configured, this functionality might best be placed into the book/cal factory processes.

Account management for future Evo versions is under reconstruction in present dev versions (2010-12-21). GConf is being replaced by GSettings, and a new notification framework is being brought up (see evolution-hackers list, "Rethinking account management" threads by mbarnes et al, 2010-10/2010-11), especially http://mail.gnome.org/archives/evolution-hackers/2010-December/msg00030.html

This class encapsulates as much of the API changes between 2.3x and 3.x as possible so the GConf->GSettings transition changes can be confined to this class.

## Details

### enum KolabSettingsHandlerBoolFieldID

    typedef enum {
    	KOLAB_SETTINGS_HANDLER_BOOL_FIELD_NONE = 0, /* FIXME replace */
    	KOLAB_SETTINGS_HANDLER_BOOL_LAST_FIELD
    } KolabSettingsHandlerBoolFieldID;

### enum KolabSettingsHandlerCharFieldID

    typedef enum {
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_CAMEL_DATA_DIR = 0,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_CAMEL_CACHE_DIR,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_CAMEL_CONFIG_DIR,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_CAMEL_ACCOUNT_DIR,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_ESOURCE_UID,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_KOLAB_SERVER_NAME,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_KOLAB_USER_NAME,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_KOLAB_USER_PASSWORD,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_KOLAB_URI,
    	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_PKCS11_USER_PIN,
    	KOLAB_SETTINGS_HANDLER_CHAR_LAST_FIELD
    } KolabSettingsHandlerCharFieldID;

### struct KolabSettingsHandlerClass

    struct KolabSettingsHandlerClass {
    	GObjectClass parent_class;
    };

### enum KolabSettingsHandlerIntFieldID

    typedef enum {
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_IMAP_PORT = 0,
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_IMAPS_PORT,
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_HTTP_PORT,
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_HTTPS_PORT,
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_LDAP_PORT,
    	KOLAB_SETTINGS_HANDLER_INT_FIELD_KOLAB_SERVER_LDAPS_PORT,
    	KOLAB_SETTINGS_HANDLER_INT_LAST_FIELD
    } KolabSettingsHandlerIntFieldID;

### enum KolabSettingsHandlerTblID

    typedef enum {
    	KOLAB_SETTINGS_HANDLER_TBL_SYNCSTRATEGY = 0, /* sourcename:KolabSyncStrategyID */
    	KOLAB_SETTINGS_HANDLER_TBL_FOLDERCREATE,     /* sourcename:bool (whether to create folder if not existing) */
    	KOLAB_SETTINGS_HANDLER_LAST_TBL
    } KolabSettingsHandlerTblID;

### enum KolabSettingsHandlerUintFieldID

    typedef enum {
    	KOLAB_SETTINGS_HANDLER_UINT_FIELD_FOLDER_CONTEXT = 0,
    	KOLAB_SETTINGS_HANDLER_UINT_FIELD_TLS_VARIANT,
    	KOLAB_SETTINGS_HANDLER_UINT_LAST_FIELD
    } KolabSettingsHandlerUintFieldID;

### kolab_settings_handler_bringup ()

    gboolean            kolab_settings_handler_bringup      (KolabSettingsHandler *self,
                                                             GError **err);

Gets the KolabSettingsHandler object into operational mode. This may involve file I/O. Must be called once after `kolab_settings_handler_configure()` and before any other operation.

`self` : | a KolabSettingsHandler instance
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_configure ()

    gboolean            kolab_settings_handler_configure    (KolabSettingsHandler *self,
                                                             KolabFolderContextID context,
                                                             GError **err);

Configures the object for operation. Must be called once after object instantiation and before any other operation.

`self` : | a KolabSettingsHandler instance
`context` : | the folder context (i.e. backend type) the settings handler will be used in (for now, either KOLAB_FOLDER_CONTEXT_CALENDAR or KOLAB_FOLDER_CONTEXT_CONTACT)
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_get_bool_field ()

    gboolean            kolab_settings_handler_get_bool_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerBoolFieldID field_id,
                                                             GError **err);

Gets the value of the bool field selected by `field_id`. Check `err` for errors since FALSE may be a valid return value for the bool field.

`self` : | a KolabSettingsHandler instance
`field_id` : | the bool field id to get a value from
`err` : | a GError object (or NULL)
Returns : | the referenced boolean value on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_get_char_field ()

    const gchar *       kolab_settings_handler_get_char_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerCharFieldID field_id,
                                                             GError **err);

Gets the value of the char field selected by `field_id`.

`self` : | a KolabSettingsHandler instance
`field_id` : | the char field id to get a value from
`err` : | a GError object (or NULL)
Returns : | the referenced string on success, NULL otherwise (with `err` set)

### kolab_settings_handler_get_int_field ()

    gint                kolab_settings_handler_get_int_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerIntFieldID field_id,
                                                             GError **err);

Gets the value of the int field selected by `field_id`. Check `err` for errors since 0 may be a valid return value for the int field.

`self` : | a KolabSettingsHandler instance
`field_id` : | the int field id to get a value from
`err` : | a GError object (or NULL)
Returns : | the referenced integer on success, 0 otherwise (with `err` set)

### kolab_settings_handler_get_uint_field ()

    guint               kolab_settings_handler_get_uint_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerUintFieldID field_id,
                                                             GError **err);

Gets the value of the uint field selected by `field_id`. Check `err` for errors since 0 may be a valid return value for the uint field.

`self` : | a KolabSettingsHandler instance
`field_id` : | the uint field id to get a value from
`err` : | a GError object (or NULL)
Returns : | the referenced unsigned integer on success, 0 otherwise (with `err` set)

### kolab_settings_handler_get_value ()

    gconstpointer       kolab_settings_handler_get_value    (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerTblID tbl_id,
                                                             const gchar *key,
                                                             GError **err);

Retrieve a `value` under the given `key` from an internal table identified by `tbl_id`.

The data type `value` points to is determined by the `tbl_id`. Each table has a certain value data type associated with it (see KolabSettingsHandlerTblID).

It is an error to try to retrieve a value if nothing has ever been stored in any table or if a `tbl_id` is given for a table into which nothing has been stored before, or if there is no value stored for `key` in `tbl_id` (`err` has an error value set to KOLAB_BACKEND_ERROR_NOTFOUND in these cases).

`self` : | a KolabSettingsHandler instance
`tbl_id` : | ID for the internal table to store the `value` in
`key` : | the key string to reference the value with
`err` : | a GError object (or NULL)
Returns : | a pointer to the data referenced by `tbl_id`:`key` on success, NULL with `err` set on failure or if not found

### kolab_settings_handler_set_bool_field ()

    gboolean            kolab_settings_handler_set_bool_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerBoolFieldID field_id,
                                                             gboolean value,
                                                             GError **err);

Sets `value` as the value for the bool field selected by `field_id`. If an error occurs, the internal value of the bool field selected by `field_id` is not changed.

`self` : | a KolabSettingsHandler instance
`field_id` : | the bool field id to set a value for
`value` : | value to set for the given field
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_set_char_field ()

    gboolean            kolab_settings_handler_set_char_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerCharFieldID field_id,
                                                             gchar *value,
                                                             GError **err);

Sets `value` as the value for the char field selected by `field_id`. If an error occurs and the internal value of the char field selected by `field_id` is not changed, no ownership is taken of `value`. If the function returns successfully, the KolabSettingsHandler instance will have taken ownership of `value`, so make sure it is not free'd later on.

`self` : | a KolabSettingsHandler instance
`field_id` : | the char field id to set a value for
`value` : | the string to set as a value for the given field
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_set_int_field ()

    gboolean            kolab_settings_handler_set_int_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerIntFieldID field_id,
                                                             gint value,
                                                             GError **err);

Sets `value` as the value for the int field selected by `field_id`. If an error occurs, the internal value of the int field selected by `field_id` is not changed.

`self` : | a KolabSettingsHandler instance
`field_id` : | the int field id to set a value for
`value` : | value to set for the given field
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_set_uint_field ()

    gboolean            kolab_settings_handler_set_uint_field
                                                            (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerUintFieldID field_id,
                                                             guint value,
                                                             GError **err);

Sets `value` as the value for the uint field selected by `field_id`. If an error occurs, the internal value of the uint field selected by `field_id` is not changed.

`self` : | a KolabSettingsHandler instance
`field_id` : | the uint field id to set a value for
`value` : | value to set for the given field
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_set_value ()

    gboolean            kolab_settings_handler_set_value    (KolabSettingsHandler *self,
                                                             KolabSettingsHandlerTblID tbl_id,
                                                             const gchar *key,
                                                             gpointer value,
                                                             GError **err);

Store a `value` under the given `key` in an internal table identified by `tbl_id`. Be sure that the data pointed to does not get erased as long as it is accessible via `tbl_id`:`key`.

The data type `value` points to is determined by the `tbl_id`. Each table has a certain value data type associated with it (see KolabSettingsHandlerTblID), so be sure to supply only pointers to the data type this table is meant for (orelse, table destruction or replacing of existing values will fail miserably).

`self` : | a KolabSettingsHandler instance
`tbl_id` : | ID for the internal table to store the `value` in
`key` : | the key string to reference the value with
`value` : | a pointer to the data object to store
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

### kolab_settings_handler_shutdown ()

    gboolean            kolab_settings_handler_shutdown     (KolabSettingsHandler *self,
                                                             GError **err);

Shuts down the KolabSettingsHandler object. Must be called before object destruction. No further operation on the object is valid unless `kolab_settings_handler_bringup()` is called again.

`self` : | a KolabSettingsHandler instance
`err` : | a GError object (or NULL)
Returns : | TRUE on success, FALSE otherwise (with `err` set)

## See Also

KolabMailAccess