GSettingsSchema, GSettingsSchemaSource

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

## Synopsis

                        GSettingsSchemaSource;
    #define             G_TYPE_SETTINGS_SCHEMA_SOURCE
    GSettingsSchemaSource * g_settings_schema_source_get_default
                                                            (void);
    GSettingsSchemaSource * g_settings_schema_source_ref    (GSettingsSchemaSource *source);
    void                g_settings_schema_source_unref      (GSettingsSchemaSource *source);

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

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

                        GSettingsSchema;
    #define             G_TYPE_SETTINGS_SCHEMA
    GSettingsSchema *   g_settings_schema_ref               (GSettingsSchema *schema);
    void                g_settings_schema_unref             (GSettingsSchema *schema);

    const gchar *       g_settings_schema_get_id            (GSettingsSchema *schema);
    const gchar *       g_settings_schema_get_path          (GSettingsSchema *schema);

## Object Hierarchy

      GBoxed
       +----GSettingsSchema

## 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_new_schema_source_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.

## Details

### GSettingsSchemaSource

    typedef struct _GSettingsSchemaSource GSettingsSchemaSource;

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

Since 2.32

### G_TYPE_SETTINGS_SCHEMA_SOURCE

    #define                 G_TYPE_SETTINGS_SCHEMA_SOURCE                   (g_settings_schema_source_get_type ())

A boxed GType corresponding to GSettingsSchemaSource.

Since 2.32

### 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]

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.

`source` : | a GSettingsSchemaSource
Returns : | a new reference to `source`

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.

`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 glib-compile-schemas.

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.

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 `extents`) 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()`.

`directory` : | the filename of a directory
`parent` : | a GSettingsSchemaSource, or `NULL`. [allow-none]
`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_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.

`source` : | a GSettingsSchemaSource
`schema_id` : | a schema ID
`recursive` : | `TRUE` if the lookup should be recursive
Returns : | a new GSettingsSchema. [transfer full]

Since 2.32

### GSettingsSchema

    typedef struct _GSettingsSchema GSettingsSchema;

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

Since 2.32

### G_TYPE_SETTINGS_SCHEMA

    #define                 G_TYPE_SETTINGS_SCHEMA                          (g_settings_schema_get_type ())

A boxed GType corresponding to GSettingsSchema.

Since 2.32

### g_settings_schema_ref ()

    GSettingsSchema *   g_settings_schema_ref               (GSettingsSchema *schema);

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

`schema` : | a GSettingsSchema
Returns : | a new reference to `schema`

Since 2.32

### g_settings_schema_unref ()

    void                g_settings_schema_unref             (GSettingsSchema *schema);

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

`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`.

`schema` : | a GSettingsSchema
Returns : | the ID. [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 threfore describe multiple sets of keys at different locations. For relocatable schemas, this function will return `NULL`.

`schema` : | a GSettingsSchema
Returns : | the path of the schema, or `NULL`. [transfer none]

Since 2.32