GssConfigFile

GssConfigFile — Hierarchical configuration files

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

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