## MateConfEngine

MateConfEngine — a MateConf "database"

## Synopsis

                        MateConfEngine;
    MateConfEngine *       mateconf_engine_get_default            (void);
    MateConfEngine *       mateconf_engine_get_for_address        (const gchar *address,
                                                             GError **err);
    MateConfEngine *       mateconf_engine_get_for_addresses      (GSList *addresses,
                                                             GError **err);
    void                mateconf_engine_unref                  (MateConfEngine *conf);
    void                mateconf_engine_ref                    (MateConfEngine *conf);
    MateConfEngine *       mateconf_engine_get_local              (const char *address,
                                                             GError **err);
    MateConfEngine *       mateconf_engine_get_local_for_addresses
                                                            (GSList *addresses,
                                                             GError **err);
    void                mateconf_engine_set_user_data          (MateConfEngine *engine,
                                                             gpointer data,
                                                             GDestroyNotify dnotify);
    gpointer            mateconf_engine_get_user_data          (MateConfEngine *engine);

## Description

A MateConfEngine represents a connection to the MateConf database. The default MateConfEngine, returned from `mateconf_engine_get_default()`, represents the user's normal configuration source search path. Configuration-related utilities, such as a configuration editor tool, might wish to access a particular configuration source directly; they can obtain a non-default MateConfEngine with `mateconf_engine_get_for_address()`.

Once you have a MateConfEngine, you can query and manipulate configuration values.

## Details

### MateConfEngine

    typedef struct _MateConfEngine MateConfEngine;

An opaque data type representing one or more configuration sources.

### mateconf_engine_get_default ()

    MateConfEngine *       mateconf_engine_get_default            (void);

Returns the default MateConfEngine. All clients should use this, unless they are special configuration-related tools. The caller of this function assumes one reference count, and must call `mateconf_engine_unref()` at some point. It's fairly important to unref the MateConfEngine, to cleanly close the connection to mateconfd. So if possible close the connection before exiting your application.

Returns : | the default MateConfEngine. [transfer full]

### mateconf_engine_get_for_address ()

    MateConfEngine *       mateconf_engine_get_for_address        (const gchar *address,
                                                             GError **err);

Obtains a special MateConfEngine; mostly useful for specialized MateConf-related tools. Normal clients shouldn't need to use it. As with `mateconf_engine_get_default()`, the returned MateConfEngine should be unreferenced by the caller of this function.

`address` : | a configuration source address.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a MateConfEngine.

### mateconf_engine_get_for_addresses ()

    MateConfEngine *       mateconf_engine_get_for_addresses      (GSList *addresses,
                                                             GError **err);

Similar to `mateconf_engine_get_for_address()` , but takes a list of addresses instead of a single address.

`addresses` : | a list of configuration addresses.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a MateConfEngine.

Since 2.4

### mateconf_engine_unref ()

    void                mateconf_engine_unref                  (MateConfEngine *conf);

Decreases the reference count of a MateConfEngine by one; if the reference count reaches 0, destroys the MateConfEngine.

`conf` : | a MateConfEngine.

### mateconf_engine_ref ()

    void                mateconf_engine_ref                    (MateConfEngine *conf);

Increases the reference count of a MateConfEngine by one.

`conf` : | a MateConfEngine.

### mateconf_engine_get_local ()

    MateConfEngine *       mateconf_engine_get_local              (const char *address,
                                                             GError **err);

Obtain a local (non-process-transparent) MateConfEngine. Local engines do not support notification, and can only access config databases directly (they do not use the multiple sources in a path system supported by nonlocal engines).

`address` : | address of local database.
`err` : | return location of an allocated GError.
Returns : | a MateConfEngine.

### mateconf_engine_get_local_for_addresses ()

    MateConfEngine *       mateconf_engine_get_local_for_addresses
                                                            (GSList *addresses,
                                                             GError **err);

Obtains a local MateConfEngine similar to `mateconf_engine_get_local()`. Instead of taking the address of the local database, this function takes the addresses of the sources and gets the MateConfSources using `mateconf_sources_new_from_addresses()`.

`addresses` : | a list of addresses of MateConfSources.
`err` : | the return location for an allocated GError, or NULL to ignore errors.
Returns : | a MateConfEngine.

Since 2.8

### mateconf_engine_set_user_data ()

    void                mateconf_engine_set_user_data          (MateConfEngine *engine,
                                                             gpointer data,
                                                             GDestroyNotify dnotify);

Sets the user_data and the destroy notification function fields of a MateConfEngine.

`engine` : | a MateConfEngine.
`data` : | a gpointer.
`dnotify` : | a pointer to the function to be called during destroy.

### mateconf_engine_get_user_data ()

    gpointer            mateconf_engine_get_user_data          (MateConfEngine *engine);

Returns the user_data field of a MateConfEngine.

`engine` : | a MateConfEngine.
Returns : | a pointer to the user_data.