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

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

Generated by GTK-Doc V1.18.1