GssConfigFile: libgsystemservice Reference Manual

## GssConfigFile GssConfigFile — Hierarchical configuration files |

## Stability Level

Stable, unless otherwise indicated

## Functions

GssConfigFile * | gss_config_file_new ()
guint | gss_config_file_get_uint ()
gboolean | gss_config_file_get_boolean ()
gchar * | gss_config_file_get_string ()
gchar ** | gss_config_file_get_strv ()
gchar ** | gss_config_file_get_groups ()

## Types and Values

| GssConfigFile

## Includes

    #include <libgsystemservice/config-file.h>

## Description

This represents a configuration file, loaded from one or more layered configuration files following the same schema. For each schema, there must always be one canonical copy of the configuration file compiled into the program as a GResource; ultimately, default values are loaded from this. It is advised that a copy of this default configuration file is also installed in a read-only location on the system, so users can inspect and copy from the default configuration.

When queried for keys, an GssConfigFile instance will return the value from the first configuration file in its hierarchy which contains that key. If an administrator wishes to override a value from a lower configuration file, they must do so explicitly in a higher one.

When listing groups, an GssConfigFile will return the deduplicated union of all the groups in all of its hierarchy of configuration files. When overriding a group of keys, the entire group must be copied from one configuration file to a higher one; otherwise queries for some keys will fall back to the lower configuration file.

## Functions

### gss_config_file_new ()

    GssConfigFile *
    gss_config_file_new (const gchar * const *key_file_paths,
                         GResource *default_resource,
                         const gchar *default_path);

Create a new GssConfigFile representing the configuration loaded from the given collection of `key_file_paths` , which must all follow the same schema. `key_file_paths` must contain at least one element; its final element is treated as the default configuration file containing all default values.

This function does no file I/O.

#### Parameters

key_file_paths | `NULL`-terminated ordered collection of paths of configuration files to load; must be non-empty. | [array zero-terminated=1]
default_resource | GResource containing the default configuration. | [transfer none]
default_path | path to the default configuration file in `default_resource` |

#### Returns

a newly allocated GssConfigFile.

[transfer full]

Since: 0.1.0

### gss_config_file_get_uint ()

    guint
    gss_config_file_get_uint (GssConfigFile *self,
                              const gchar *group_name,
                              const gchar *key_name,
                              guint min_value,
                              guint max_value,
                              GError **error);

Load an unsigned integer value from the configuration, and validate that it lies in [`min_value` , `max_value` ]. The given key must exist in the default configuration file, if not in any others. It will be loaded from the first configuration file which contains it.

If the loaded value does not validate, `G_KEY_FILE_ERROR_INVALID_VALUE` is returned.

#### Parameters

self | an GssConfigFile |
group_name | name of the configuration group |
key_name | name of the configuration key |
min_value | minimum valid value (inclusive) |
max_value | maximum valid value (inclusive) |
error | return location for a GError, or `NULL` |

#### Returns

the loaded unsigned integer

Since: 0.1.0

### gss_config_file_get_boolean ()

    gboolean
    gss_config_file_get_boolean (GssConfigFile *self,
                                 const gchar *group_name,
                                 const gchar *key_name,
                                 GError **error);

Load a boolean value from the configuration. The given key must exist in the default configuration file, if not in any others. It will be loaded from the first configuration file which contains it.

#### Parameters

self | an GssConfigFile |
group_name | name of the configuration group |
key_name | name of the configuration key |
error | return location for a GError, or `NULL` |

#### Returns

the loaded boolean

Since: 0.1.0

### gss_config_file_get_string ()

    gchar *
    gss_config_file_get_string (GssConfigFile *self,
                                const gchar *group_name,
                                const gchar *key_name,
                                GError **error);

Load a string value from the configuration. The given key must exist in the default configuration file, if not in any others. It will be loaded from the first configuration file which contains it.

#### Parameters

self | an GssConfigFile |
group_name | name of the configuration group |
key_name | name of the configuration key |
error | return location for a GError, or `NULL` |

#### Returns

the loaded string, which is guaranteed to be non-`NULL` but may be empty.

[transfer full]

Since: 0.1.0

### gss_config_file_get_strv ()

    gchar **
    gss_config_file_get_strv (GssConfigFile *self,
                              const gchar *group_name,
                              const gchar *key_name,
                              gsize *n_elements_out,
                              GError **error);

Load a string array value from the configuration. The given key must exist in the default configuration file, if not in any others. It will be loaded from the first configuration file which contains it.

#### Parameters

self | an GssConfigFile |
group_name | name of the configuration group |
key_name | name of the configuration key |
n_elements_out | return location for the number of elements in the string array (not including the terminating `NULL`), or `NULL`. | [out caller-allocates][optional]
error | return location for a GError, or `NULL` |

#### Returns

the loaded string array, which is guaranteed to be non-`NULL` but may be empty.

[transfer full][array zero-terminated=1 length=n_elements_out]

Since: 0.1.0

### gss_config_file_get_groups ()

    gchar **
    gss_config_file_get_groups (GssConfigFile *self,
                                gsize *n_groups_out,
                                GError **error);

List the groups from all the configuration files, eliminating duplicates. Empty groups are included in the list. The list is sorted lexicographically.

#### Parameters

self | an GssConfigFile |
n_groups_out | return location for the number of groups returned (not including the terminating `NULL`), or `NULL`. | [out caller-allocates][optional]
error | return location for a GError, or `NULL` |

#### Returns

the groups in the configuration files, which is guaranteed to be non-`NULL` but may be empty.

[transfer full][array zero-terminated=1 length=n_groups_out]

Since: 0.1.0

## Types and Values

### GssConfigFile

    typedef struct _GssConfigFile GssConfigFile;

Implementation of a configuration file hierarchy.

Since: 0.1.0