GSettingsSchema, GSettingsSchemaSource: GIO Reference Manual

## GSettingsSchema, GSettingsSchemaSource GSettingsSchema, GSettingsSchemaSource — Introspecting and controlling the loading of GSettings schemas |

## Functions

GSettingsSchemaSource * | g_settings_schema_source_get_default ()
GSettingsSchemaSource * | g_settings_schema_source_ref ()
void | g_settings_schema_source_unref ()
GSettingsSchemaSource * | g_settings_schema_source_new_from_directory ()
void | g_settings_schema_source_list_schemas ()
GSettingsSchema * | g_settings_schema_source_lookup ()
GSettingsSchema * | g_settings_schema_ref ()
void | g_settings_schema_unref ()
const gchar * | g_settings_schema_get_id ()
const gchar * | g_settings_schema_get_path ()
gboolean | g_settings_schema_has_key ()
GSettingsSchemaKey * | g_settings_schema_get_key ()
GSettingsSchemaKey * | g_settings_schema_key_ref ()
void | g_settings_schema_key_unref ()
gchar ** | g_settings_schema_list_children ()
gchar ** | g_settings_schema_list_keys ()
const GVariantType * | g_settings_schema_key_get_value_type ()
GVariant * | g_settings_schema_key_get_default_value ()
GVariant * | g_settings_schema_key_get_range ()
gboolean | g_settings_schema_key_range_check ()
const gchar * | g_settings_schema_key_get_name ()
const gchar * | g_settings_schema_key_get_summary ()
const gchar * | g_settings_schema_key_get_description ()

## Types and Values

| GSettingsSchemaSource
| GSettingsSchema
| GSettingsSchemaKey

## Object Hierarchy

        GBoxed
        ├── GSettingsSchema
        ├── GSettingsSchemaKey
        ╰── GSettingsSchemaSource

## Includes

    #include <gio/gio.h>

## Description

The GSettingsSchemaSource and GSettingsSchema APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content.

Plugin loading systems that wish to provide plugins a way to access settings face the problem of how to make the schemas for these settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won't be installed into the standard system directories for schemas.

GSettingsSchemaSource provides a mechanism for dealing with this by allowing the creation of a new 'schema source' from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings.

Consider the following example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    typedef struct
    {
       ...
       GSettingsSchemaSource *schema_source;
       ...
    } Plugin;

    Plugin *
    initialise_plugin (const gchar *dir)
    {
      Plugin *plugin;

      ...

      plugin->schema_source =
        g_settings_schema_source_new_from_directory (dir,
          g_settings_schema_source_get_default (), FALSE, NULL);

      ...

      return plugin;
    }

    ...

    GSettings *
    plugin_get_settings (Plugin      *plugin,
                         const gchar *schema_id)
    {
      GSettingsSchema *schema;

      if (schema_id == NULL)
        schema_id = plugin->identifier;

      schema = g_settings_schema_source_lookup (plugin->schema_source,
                                                schema_id, FALSE);

      if (schema == NULL)
        {
          ... disable the plugin or abort, etc ...
        }

      return g_settings_new_full (schema, NULL, NULL);
    }

The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and how an API can be added to the plugin system to provide a convenient way for the plugin to access its settings, using the schemas that it ships.

From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following:

    1
    2
    3
    4
    5
    6
    7
    8
    {
      GSettings *settings;
      gint some_value;

      settings = plugin_get_settings (self, NULL);
      some_value = g_settings_get_int (settings, "some-value");
      ...
    }

It's also possible that the plugin system expects the schema source files (ie: .gschema.xml files) instead of a gschemas.compiled file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source.

## Functions

### g_settings_schema_source_get_default ()

    GSettingsSchemaSource *
    g_settings_schema_source_get_default (void);

Gets the default system schema source.

This function is not required for normal uses of GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas.

If no schemas are installed, `NULL` will be returned.

The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all lookups performed against the default source should probably be done recursively.

#### Returns

the default schema source.

[transfer none][nullable]

Since: 2.32

### g_settings_schema_source_ref ()

    GSettingsSchemaSource *
    g_settings_schema_source_ref (GSettingsSchemaSource *source);

Increase the reference count of `source` , returning a new reference.

#### Parameters

source | a GSettingsSchemaSource |

#### Returns

a new reference to `source` .

[transfer full][not nullable]

Since: 2.32

### g_settings_schema_source_unref ()

    void
    g_settings_schema_source_unref (GSettingsSchemaSource *source);

Decrease the reference count of `source` , possibly freeing it.

#### Parameters

source | a GSettingsSchemaSource |

Since: 2.32

### g_settings_schema_source_new_from_directory ()

    GSettingsSchemaSource *
    g_settings_schema_source_new_from_directory
                                   (const gchar *directory,
                                    GSettingsSchemaSource *parent,
                                    gboolean trusted,
                                    GError **error);

Attempts to create a new schema source corresponding to the contents of the given directory.

This function is not required for normal uses of GSettings but it may be useful to authors of plugin management systems.

The directory should contain a file called `gschemas.compiled` as produced by the glib-compile-schemas tool.

If `trusted` is `TRUE` then `gschemas.compiled` is trusted not to be corrupted. This assumption has a performance advantage, but can result in crashes or inconsistent behaviour in the case of a corrupted file. Generally, you should set `trusted` to `TRUE` for files installed by the system and to `FALSE` for files in the home directory.

In either case, an empty file or some types of corruption in the file will result in `G_FILE_ERROR_INVAL` being returned.

If `parent` is non-`NULL` then there are two effects.

First, if `g_settings_schema_source_lookup()` is called with the `recursive` flag set to `TRUE` and the schema can not be found in the source, the lookup will recurse to the parent.

Second, any references to other schemas specified within this source (ie: `child` or `extends`) references may be resolved from the `parent` .

For this second reason, except in very unusual situations, the `parent` should probably be given as the default schema source, as returned by `g_settings_schema_source_get_default()`.

#### Parameters

directory | the filename of a directory. | [type filename]
parent | a GSettingsSchemaSource, or `NULL`. | [nullable]
trusted | `TRUE`, if the directory is trusted |
error | a pointer to a GError pointer set to `NULL`, or `NULL` |

Since: 2.32

### g_settings_schema_source_list_schemas ()

    void
    g_settings_schema_source_list_schemas (GSettingsSchemaSource *source,
                                           gboolean recursive,
                                           gchar ***non_relocatable,
                                           gchar ***relocatable);

Lists the schemas in a given source.

If `recursive` is `TRUE` then include parent sources. If `FALSE` then only include the schemas from one source (ie: one directory). You probably want `TRUE`.

Non-relocatable schemas are those for which you can call `g_settings_new()`. Relocatable schemas are those for which you must use `g_settings_new_with_path()`.

Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc.

#### Parameters

source | a GSettingsSchemaSource |
recursive | if we should recurse |
non_relocatable | the list of non-relocatable schemas, in no defined order. | [out][transfer full][array zero-terminated=1]
relocatable | the list of relocatable schemas, in no defined order. | [out][transfer full][array zero-terminated=1]

Since: 2.40

### g_settings_schema_source_lookup ()

    GSettingsSchema *
    g_settings_schema_source_lookup (GSettingsSchemaSource *source,
                                     const gchar *schema_id,
                                     gboolean recursive);

Looks up a schema with the identifier `schema_id` in `source` .

This function is not required for normal uses of GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas.

If the schema isn't found directly in `source` and `recursive` is `TRUE` then the parent sources will also be checked.

If the schema isn't found, `NULL` is returned.

#### Parameters

source | a GSettingsSchemaSource |
schema_id | a schema ID |
recursive | `TRUE` if the lookup should be recursive |

#### Returns

a new GSettingsSchema.

[nullable][transfer full]

Since: 2.32

### g_settings_schema_ref ()

    GSettingsSchema *
    g_settings_schema_ref (GSettingsSchema *schema);

Increase the reference count of `schema` , returning a new reference.

#### Parameters

schema | a GSettingsSchema |

#### Returns

a new reference to `schema` .

[transfer full][not nullable]

Since: 2.32

### g_settings_schema_unref ()

    void
    g_settings_schema_unref (GSettingsSchema *schema);

Decrease the reference count of `schema` , possibly freeing it.

#### Parameters

schema | a GSettingsSchema |

Since: 2.32

### g_settings_schema_get_id ()

    const gchar *
    g_settings_schema_get_id (GSettingsSchema *schema);

Get the ID of `schema` .

#### Parameters

schema | a GSettingsSchema |

#### Returns

the ID.

[not nullable][transfer none]

### g_settings_schema_get_path ()

    const gchar *
    g_settings_schema_get_path (GSettingsSchema *schema);

Gets the path associated with `schema` , or `NULL`.

Schemas may be single-instance or relocatable. Single-instance schemas correspond to exactly one set of keys in the backend database: those located at the path returned by this function.

Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return `NULL`.

#### Parameters

schema | a GSettingsSchema |

#### Returns

the path of the schema, or `NULL`.

[nullable][transfer none]

Since: 2.32

### g_settings_schema_has_key ()

    gboolean
    g_settings_schema_has_key (GSettingsSchema *schema,
                               const gchar *name);

Checks if `schema` has a key named `name` .

#### Parameters

schema | a GSettingsSchema |
name | the name of a key |

#### Returns

`TRUE` if such a key exists

Since: 2.40

### g_settings_schema_get_key ()

    GSettingsSchemaKey *
    g_settings_schema_get_key (GSettingsSchema *schema,
                               const gchar *name);

Gets the key named `name` from `schema` .

It is a programmer error to request a key that does not exist. See `g_settings_schema_list_keys()`.

#### Parameters

schema | a GSettingsSchema |
name | the name of a key |

#### Returns

the GSettingsSchemaKey for `name` .

[not nullable][transfer full]

Since: 2.40

### g_settings_schema_key_ref ()

    GSettingsSchemaKey *
    g_settings_schema_key_ref (GSettingsSchemaKey *key);

Increase the reference count of `key` , returning a new reference.

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

a new reference to `key` .

[not nullable][transfer full]

Since: 2.40

### g_settings_schema_key_unref ()

    void
    g_settings_schema_key_unref (GSettingsSchemaKey *key);

Decrease the reference count of `key` , possibly freeing it.

#### Parameters

key | a GSettingsSchemaKey |

Since: 2.40

### g_settings_schema_list_children ()

    gchar **
    g_settings_schema_list_children (GSettingsSchema *schema);

Gets the list of children in `schema` .

You should free the return value with `g_strfreev()` when you are done with it.

#### Parameters

schema | a GSettingsSchema |

#### Returns

a list of the children on `settings` , in no defined order.

[not nullable][transfer full][element-type utf8]

Since: 2.44

### g_settings_schema_list_keys ()

    gchar **
    g_settings_schema_list_keys (GSettingsSchema *schema);

Introspects the list of keys on `schema` .

You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons.

#### Parameters

schema | a GSettingsSchema |

#### Returns

a list of the keys on `schema` , in no defined order.

[not nullable][transfer full][element-type utf8]

Since: 2.46

### g_settings_schema_key_get_value_type ()

    const GVariantType *
    g_settings_schema_key_get_value_type (GSettingsSchemaKey *key);

Gets the GVariantType of `key` .

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

the type of `key` .

[not nullable][transfer none]

Since: 2.40

### g_settings_schema_key_get_default_value ()

    GVariant *
    g_settings_schema_key_get_default_value
                                   (GSettingsSchemaKey *key);

Gets the default value for `key` .

Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API.

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

the default value for the key.

[not nullable][transfer full]

Since: 2.40

### g_settings_schema_key_get_range ()

    GVariant *
    g_settings_schema_key_get_range (GSettingsSchemaKey *key);

Queries the range of a key.

This function will return a GVariant that fully describes the range of values that are valid for `key` .

The type of GVariant returned is `(sv)`. The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string.

If the string is `'type'` then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid.

If the string is `'enum'` then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid.

If the string is `'flags'` then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array `['x', 'y']` then the valid values for the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and `['y', 'x']`.

Finally, if the string is `'range'` then the variant contains a pair of like-typed values -- the minimum and maximum permissible values for this key.

This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future -- but particularly, new forms may be added to the possibilities described above.

You should free the returned value with `g_variant_unref()` when it is no longer needed.

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

a GVariant describing the range.

[not nullable][transfer full]

Since: 2.40

### g_settings_schema_key_range_check ()

    gboolean
    g_settings_schema_key_range_check (GSettingsSchemaKey *key,
                                       GVariant *value);

Checks if the given `value` is within the permitted range for `key` .

It is a programmer error if `value` is not of the correct type — you must check for this first.

#### Parameters

key | a GSettingsSchemaKey |
value | the value to check |

#### Returns

`TRUE` if `value` is valid for `key`

Since: 2.40

### g_settings_schema_key_get_name ()

    const gchar *
    g_settings_schema_key_get_name (GSettingsSchemaKey *key);

Gets the name of `key` .

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

the name of `key` .

[not nullable][transfer none]

Since: 2.44

### g_settings_schema_key_get_summary ()

    const gchar *
    g_settings_schema_key_get_summary (GSettingsSchemaKey *key);

Gets the summary for `key` .

If no summary has been provided in the schema for `key` , returns `NULL`.

The summary is a short description of the purpose of the key; usually one short sentence. Summaries can be translated and the value returned from this function is is the current locale.

This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory.

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

the summary for `key` , or `NULL`.

[nullable][transfer none]

Since: 2.34

### g_settings_schema_key_get_description ()

    const gchar *
    g_settings_schema_key_get_description (GSettingsSchemaKey *key);

Gets the description for `key` .

If no description has been provided in the schema for `key` , returns `NULL`.

The description can be one sentence to several paragraphs in length. Paragraphs are delimited with a double newline. Descriptions can be translated and the value returned from this function is is the current locale.

This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory.

#### Parameters

key | a GSettingsSchemaKey |

#### Returns

the description for `key` , or `NULL`.

[nullable][transfer none]

Since: 2.34

## Types and Values

### GSettingsSchemaSource

    typedef struct _GSettingsSchemaSource GSettingsSchemaSource;

This is an opaque structure type. You may not access it directly.

Since: 2.32

### GSettingsSchema

    typedef struct _GSettingsSchema GSettingsSchema;

This is an opaque structure type. You may not access it directly.

Since: 2.32

### GSettingsSchemaKey

    typedef struct _GSettingsSchemaKey GSettingsSchemaKey;

GSettingsSchemaKey is an opaque data structure and can only be accessed using the following functions.