## ZifConfig ZifConfig — System wide config options |

## Synopsis

    #define             ZIF_CONFIG_ERROR
    struct              ZifConfig;
    struct              ZifConfigClass;
    guint               (*ZifConfigEnumMappingFunc)         (const gchar *str);
    enum                ZifConfigError;
    GQuark              zif_config_error_quark              (void);
    gchar *             zif_config_expand_substitutions     (ZifConfig *config,
                                                             const gchar *text,
                                                             GError **error);
    gchar **            zif_config_get_basearch_array       (ZifConfig *config);
    gboolean            zif_config_get_boolean              (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);
    guint               zif_config_get_enum                 (ZifConfig *config,
                                                             const gchar *key,
                                                             ZifConfigEnumMappingFunc func,
                                                             GError **error);
    gchar *             zif_config_get_string               (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);
    gchar **            zif_config_get_strv                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);
    guint               zif_config_get_time                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);
    guint               zif_config_get_uint                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);
    gboolean            zif_config_is_instance_valid        (void);
    ZifConfig *         zif_config_new                      (void);
    gboolean            zif_config_reset_default            (ZifConfig *config,
                                                             GError **error);
    gboolean            zif_config_set_boolean              (ZifConfig *config,
                                                             const gchar *key,
                                                             gboolean value,
                                                             GError **error);
    gboolean            zif_config_set_filename             (ZifConfig *config,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            zif_config_set_local                (ZifConfig *config,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);
    gboolean            zif_config_set_string               (ZifConfig *config,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);
    gboolean            zif_config_set_uint                 (ZifConfig *config,
                                                             const gchar *key,
                                                             guint value,
                                                             GError **error);
    gboolean            zif_config_unset                    (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----ZifConfig

## Description

ZifConfig allows settings to be read from a central config file. Some values can be overridden in a running instance.

The values that are overridden can be reset back to the defaults without re-reading the config file.

Different types of data can be read (string, bool, uint, time). Before reading any data, the backing config file has to be set with `zif_config_set_filename()` and any reads prior to that will fail.

## Details

### ZIF_CONFIG_ERROR

    #define ZIF_CONFIG_ERROR (zif_config_error_quark ())

### struct ZifConfig

    struct ZifConfig;

### struct ZifConfigClass

    struct ZifConfigClass {
    	GObjectClass		 parent_class;
    	/* Padding for future expansion */
    	void (*_zif_reserved1) (void);
    	void (*_zif_reserved2) (void);
    	void (*_zif_reserved3) (void);
    	void (*_zif_reserved4) (void);
    };

### ZifConfigEnumMappingFunc ()

    guint               (*ZifConfigEnumMappingFunc)         (const gchar *str);

### enum ZifConfigError

    typedef enum {
    	ZIF_CONFIG_ERROR_FAILED,
    	ZIF_CONFIG_ERROR_LAST
    } ZifConfigError;

`ZIF_CONFIG_ERROR_FAILED` |
`ZIF_CONFIG_ERROR_LAST` |

### zif_config_error_quark ()

    GQuark              zif_config_error_quark              (void);

Returns : | An error quark.

Since 0.1.0

### zif_config_expand_substitutions ()

    gchar *             zif_config_expand_substitutions     (ZifConfig *config,
                                                             const gchar *text,
                                                             GError **error);

Replaces substitutions in text with the actual values of the running system.

`config` : | A ZifConfig
`text` : | The string to scan, e.g. "http://fedora/$releasever/$basearch/moo.rpm"
`error` : | A GError, or `NULL`
Returns : | A new allocated string or `NULL` for error

Since 0.1.0

### zif_config_get_basearch_array ()

    gchar **            zif_config_get_basearch_array       (ZifConfig *config);

Gets the list of architectures that packages are native on for this machine.

`config` : | A ZifConfig
Returns : | An array of strings, e.g. [ "i386", "i486", "noarch" ]. [transfer none]

Since 0.1.0

### zif_config_get_boolean ()

    gboolean            zif_config_get_boolean              (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Gets a boolean value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "keepcache"
`error` : | A GError, or `NULL`
Returns : | `TRUE` or `FALSE`

Since 0.1.0

### zif_config_get_enum ()

    guint               zif_config_get_enum                 (ZifConfig *config,
                                                             const gchar *key,
                                                             ZifConfigEnumMappingFunc func,
                                                             GError **error);

Gets an enumerated value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "pkg_compare_mode"
`func` : | A ZifConfigEnumMappingFunc to convert the string to an enum. [scope call]
`error` : | A GError, or `NULL`
Returns : | Enumerated value, or `G_MAXUINT` for an error

Since 0.2.3

### zif_config_get_string ()

    gchar *             zif_config_get_string               (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Gets a string value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "cachedir"
`error` : | A GError, or `NULL`
Returns : | An allocated value, or `NULL`

Since 0.1.0

### zif_config_get_strv ()

    gchar **            zif_config_get_strv                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Gets a string array value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "keepcache"
`error` : | A GError, or `NULL`
Returns : | `NULL`, or a string array. [element-type utf8][transfer full]

Since 0.1.3

### zif_config_get_time ()

    guint               zif_config_get_time                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Gets a time value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "metadata_expire"
`error` : | A GError, or `NULL`
Returns : | Data value, or 0 for an error

Since 0.1.0

### zif_config_get_uint ()

    guint               zif_config_get_uint                 (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Gets a unsigned integer value from a local setting, falling back to the config file.

`config` : | A ZifConfig
`key` : | A key name to retrieve, e.g. "keepcache"
`error` : | A GError, or `NULL`
Returns : | Data value, or `G_MAXUINT` for error

Since 0.1.0

### zif_config_is_instance_valid ()

    gboolean            zif_config_is_instance_valid        (void);

Returns : | `TRUE` if a singleton instance already exists

Since 0.1.6

### zif_config_new ()

    ZifConfig *         zif_config_new                      (void);

Returns : | A new ZifConfig instance.

Since 0.1.0

### zif_config_reset_default ()

    gboolean            zif_config_reset_default            (ZifConfig *config,
                                                             GError **error);

Removes any local settings previously set.

`config` : | A ZifConfig
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.0

### zif_config_set_boolean ()

    gboolean            zif_config_set_boolean              (ZifConfig *config,
                                                             const gchar *key,
                                                             gboolean value,
                                                             GError **error);

Sets a local value which is used in preference to the config value. `TRUE` is saved as "true" and `FALSE` is saved as "false"

`config` : | A ZifConfig
`key` : | Key name to save, e.g. "keepcache"
`value` : | Key data, e.g. `TRUE`
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.2

### zif_config_set_filename ()

    gboolean            zif_config_set_filename             (ZifConfig *config,
                                                             const gchar *filename,
                                                             GError **error);

Sets the filename to use as the system wide config file.

Using `filename` set to `NULL` to use the default value has been supported since 0.1.3. Earlier versions will assert.

`config` : | A ZifConfig
`filename` : | A system wide config file, e.g. "/etc/zif/zif.conf", or `NULL` to use the default.
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.0

### zif_config_set_local ()

    gboolean            zif_config_set_local                (ZifConfig *config,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);

Sets a local value which is used in preference to the config value. This is deprecated. Use `zif_config_set_string()`, `zif_config_set_uint()` and `zif_config_set_boolean()` instead.

`config` : | A ZifConfig
`key` : | Key name to save, e.g. "keepcache"
`value` : | Key data to save, e.g. "always"
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.0

### zif_config_set_string ()

    gboolean            zif_config_set_string               (ZifConfig *config,
                                                             const gchar *key,
                                                             const gchar *value,
                                                             GError **error);

Sets a local value which is used in preference to the config value.

`config` : | A ZifConfig
`key` : | Key name to save, e.g. "keepcache"
`value` : | Key data to save, e.g. "always"
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.2

### zif_config_set_uint ()

    gboolean            zif_config_set_uint                 (ZifConfig *config,
                                                             const gchar *key,
                                                             guint value,
                                                             GError **error);

Sets a local value which is used in preference to the config value.

`config` : | A ZifConfig
`key` : | Key name to save, e.g. "keepcache"
`value` : | Key data, e.g. `TRUE`
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success, `FALSE` otherwise

Since 0.1.2

### zif_config_unset ()

    gboolean            zif_config_unset                    (ZifConfig *config,
                                                             const gchar *key,
                                                             GError **error);

Unsets an overriden value back to the default. Note: if the value was never set then this method also returns with success. The idea is that we unset any value.

`config` : | A ZifConfig
`key` : | A key name to unset, e.g. "cachedir"
`error` : | A GError, or `NULL`
Returns : | `TRUE` for success

Since 0.1.3