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_CONFIG_DIR,
	KOLAB_SETTINGS_HANDLER_CHAR_FIELD_CAMEL_ACCOUNT_DIR,
	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