gio/gsettingsschema.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  * Copyright © 2011 Canonical Limited
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the licence, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #include "config.h"
  22
  23 #include "gsettingsschema-internal.h"
  24 #include "gsettings.h"
  25
  26 #include "gvdb/gvdb-reader.h"
  27 #include "strinfo.c"
  28
  29 #include <glibintl.h>
  30 #include <locale.h>
  31 #include <string.h>
  32
  33 /**
  34  * SECTION:gsettingsschema
  35  * @short_description: Introspecting and controlling the loading of
  36  *                     GSettings schemas
  37  *
  38  * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
  39  * mechanism for advanced control over the loading of schemas and a
  40  * mechanism for introspecting their content.
  41  *
  42  * Plugin loading systems that wish to provide plugins a way to access
  43  * settings face the problem of how to make the schemas for these
  44  * settings visible to GSettings.  Typically, a plugin will want to ship
  45  * the schema along with itself and it won't be installed into the
  46  * standard system directories for schemas.
  47  *
  48  * #GSettingsSchemaSource provides a mechanism for dealing with this by
  49  * allowing the creation of a new 'schema source' from which schemas can
  50  * be acquired.  This schema source can then become part of the metadata
  51  * associated with the plugin and queried whenever the plugin requires
  52  * access to some settings.
  53  *
  54  * Consider the following example:
  55  *
  56  * |[
  57  * typedef struct
  58  * {
  59  *    ...
  60  *    GSettingsSchemaSource *schema_source;
  61  *    ...
  62  * } Plugin;
  63  *
  64  * Plugin *
  65  * initialise_plugin (const gchar *dir)
  66  * {
  67  *   Plugin *plugin;
  68  *
  69  *   ...
  70  *
  71  *   plugin->schema_source =
  72  *     g_settings_new_schema_source_from_directory (dir,
  73  *       g_settings_schema_source_get_default (), FALSE, NULL);
  74  *
  75  *   ...
  76  *
  77  *   return plugin;
  78  * }
  79  *
  80  * ...
  81  *
  82  * GSettings *
  83  * plugin_get_settings (Plugin      *plugin,
  84  *                      const gchar *schema_id)
  85  * {
  86  *   GSettingsSchema *schema;
  87  *
  88  *   if (schema_id == NULL)
  89  *     schema_id = plugin->identifier;
  90  *
  91  *   schema = g_settings_schema_source_lookup (plugin->schema_source,
  92  *                                             schema_id, FALSE);
  93  *
  94  *   if (schema == NULL)
  95  *     {
  96  *       ... disable the plugin or abort, etc ...
  97  *     }
  98  *
  99  *   return g_settings_new_full (schema, NULL, NULL);
 100  * }
 101  * ]|
 102  *
 103  * The code above shows how hooks should be added to the code that
 104  * initialises (or enables) the plugin to create the schema source and
 105  * how an API can be added to the plugin system to provide a convenient
 106  * way for the plugin to access its settings, using the schemas that it
 107  * ships.
 108  *
 109  * From the standpoint of the plugin, it would need to ensure that it
 110  * ships a gschemas.compiled file as part of itself, and then simply do
 111  * the following:
 112  *
 113  * |[
 114  * {
 115  *   GSettings *settings;
 116  *   gint some_value;
 117  *
 118  *   settings = plugin_get_settings (self, NULL);
 119  *   some_value = g_settings_get_int (settings, "some-value");
 120  *   ...
 121  * }
 122  * ]|
 123  *
 124  * It's also possible that the plugin system expects the schema source
 125  * files (ie: .gschema.xml files) instead of a gschemas.compiled file.
 126  * In that case, the plugin loading system must compile the schemas for
 127  * itself before attempting to create the settings source.
 128  *
 129  * Since: 2.32
 130  **/
 131
 132 /**
 133  * GSettingsSchema:
 134  *
 135  * This is an opaque structure type.  You may not access it directly.
 136  *
 137  * Since: 2.32
 138  **/
 139 struct _GSettingsSchema
 140 {
 141   const gchar *gettext_domain;
 142   const gchar *path;
 143   GQuark *items;
 144   gint n_items;
 145   GvdbTable *table;
 146   gchar *id;
 147
 148   gint ref_count;
 149 };
 150
 151 /**
 152  * G_TYPE_SETTINGS_SCHEMA_SOURCE:
 153  *
 154  * A boxed #GType corresponding to #GSettingsSchemaSource.
 155  *
 156  * Since: 2.32
 157  **/
 158 G_DEFINE_BOXED_TYPE (GSettingsSchemaSource, g_settings_schema_source, g_settings_schema_source_ref, g_settings_schema_source_unref)
 159
 160 /**
 161  * G_TYPE_SETTINGS_SCHEMA:
 162  *
 163  * A boxed #GType corresponding to #GSettingsSchema.
 164  *
 165  * Since: 2.32
 166  **/
 167 G_DEFINE_BOXED_TYPE (GSettingsSchema, g_settings_schema, g_settings_schema_ref, g_settings_schema_unref)
 168
 169 /**
 170  * GSettingsSchemaSource:
 171  *
 172  * This is an opaque structure type.  You may not access it directly.
 173  *
 174  * Since: 2.32
 175  **/
 176 struct _GSettingsSchemaSource
 177 {
 178   GSettingsSchemaSource *parent;
 179   gchar *directory;
 180   GvdbTable *table;
 181
 182   gint ref_count;
 183 };
 184
 185 static GSettingsSchemaSource *schema_sources;
 186
 187 /**
 188  * g_settings_schema_source_ref:
 189  * @source: a #GSettingsSchemaSource
 190  *
 191  * Increase the reference count of @source, returning a new reference.
 192  *
 193  * Returns: a new reference to @source
 194  *
 195  * Since: 2.32
 196  **/
 197 GSettingsSchemaSource *
 198 g_settings_schema_source_ref (GSettingsSchemaSource *source)
 199 {
 200   g_atomic_int_inc (&source->ref_count);
 201
 202   return source;
 203 }
 204
 205 /**
 206  * g_settings_schema_source_unref:
 207  * @source: a #GSettingsSchemaSource
 208  *
 209  * Decrease the reference count of @source, possibly freeing it.
 210  *
 211  * Since: 2.32
 212  **/
 213 void
 214 g_settings_schema_source_unref (GSettingsSchemaSource *source)
 215 {
 216   if (g_atomic_int_dec_and_test (&source->ref_count))
 217     {
 218       if (source == schema_sources)
 219         g_error ("g_settings_schema_source_unref() called too many times on the default schema source");
 220
 221       if (source->parent)
 222         g_settings_schema_source_unref (source->parent);
 223       gvdb_table_unref (source->table);
 224       g_free (source->directory);
 225
 226       g_slice_free (GSettingsSchemaSource, source);
 227     }
 228 }
 229
 230 /**
 231  * g_settings_schema_source_new_from_directory:
 232  * @directory: the filename of a directory
 233  * @parent: (allow-none): a #GSettingsSchemaSource, or %NULL
 234  * @trusted: %TRUE, if the directory is trusted
 235  * @error: a pointer to a #GError pointer set to %NULL, or %NULL
 236  *
 237  * Attempts to create a new schema source corresponding to the contents
 238  * of the given directory.
 239  *
 240  * This function is not required for normal uses of #GSettings but it
 241  * may be useful to authors of plugin management systems.
 242  *
 243  * The directory should contain a file called
 244  * <filename>gschemas.compiled</filename> as produced by
 245  * <command>glib-compile-schemas</command>.
 246  *
 247  * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
 248  * trusted not to be corrupted.  This assumption has a performance
 249  * advantage, but can result in crashes or inconsistent behaviour in the
 250  * case of a corrupted file.  Generally, you should set @trusted to
 251  * %TRUE for files installed by the system and to %FALSE for files in
 252  * the home directory.
 253  *
 254  * If @parent is non-%NULL then there are two effects.
 255  *
 256  * First, if g_settings_schema_source_lookup() is called with the
 257  * @recursive flag set to %TRUE and the schema can not be found in the
 258  * source, the lookup will recurse to the parent.
 259  *
 260  * Second, any references to other schemas specified within this
 261  * source (ie: <literal>child</literal> or <literal>extends</literal>)
 262  * references may be resolved from the @parent.
 263  *
 264  * For this second reason, except in very unusual situations, the
 265  * @parent should probably be given as the default schema source, as
 266  * returned by g_settings_schema_source_get_default().
 267  *
 268  * Since: 2.32
 269  **/
 270 GSettingsSchemaSource *
 271 g_settings_schema_source_new_from_directory (const gchar            *directory,
 272                                              GSettingsSchemaSource  *parent,
 273                                              gboolean                trusted,
 274                                              GError                **error)
 275 {
 276   GSettingsSchemaSource *source;
 277   GvdbTable *table;
 278   gchar *filename;
 279
 280   filename = g_build_filename (directory, "gschemas.compiled", NULL);
 281   table = gvdb_table_new (filename, trusted, error);
 282   g_free (filename);
 283
 284   if (table == NULL)
 285     return NULL;
 286
 287   source = g_slice_new (GSettingsSchemaSource);
 288   source->directory = g_strdup (directory);
 289   source->parent = parent ? g_settings_schema_source_ref (parent) : NULL;
 290   source->table = table;
 291   source->ref_count = 1;
 292
 293   return source;
 294 }
 295
 296 static void
 297 try_prepend_dir (const gchar *directory)
 298 {
 299   GSettingsSchemaSource *source;
 300
 301   source = g_settings_schema_source_new_from_directory (directory, schema_sources, TRUE, NULL);
 302
 303   /* If we successfully created it then prepend it to the global list */
 304   if (source != NULL)
 305     schema_sources = source;
 306 }
 307
 308 static void
 309 initialise_schema_sources (void)
 310 {
 311   static gsize initialised;
 312
 313   /* need a separate variable because 'schema_sources' may legitimately
 314    * be null if we have zero valid schema sources
 315    */
 316   if G_UNLIKELY (g_once_init_enter (&initialised))
 317     {
 318       const gchar * const *dirs;
 319       const gchar *path;
 320       gint i;
 321
 322       /* iterate in reverse: count up, then count down */
 323       dirs = g_get_system_data_dirs ();
 324       for (i = 0; dirs[i]; i++);
 325
 326       while (i--)
 327         {
 328           gchar *dirname;
 329
 330           dirname = g_build_filename (dirs[i], "glib-2.0", "schemas", NULL);
 331           try_prepend_dir (dirname);
 332           g_free (dirname);
 333         }
 334
 335       if ((path = g_getenv ("GSETTINGS_SCHEMA_DIR")) != NULL)
 336         try_prepend_dir (path);
 337
 338       g_once_init_leave (&initialised, TRUE);
 339     }
 340 }
 341
 342 /**
 343  * g_settings_schema_source_get_default:
 344  *
 345  * Gets the default system schema source.
 346  *
 347  * This function is not required for normal uses of #GSettings but it
 348  * may be useful to authors of plugin management systems or to those who
 349  * want to introspect the content of schemas.
 350  *
 351  * If no schemas are installed, %NULL will be returned.
 352  *
 353  * The returned source may actually consist of multiple schema sources
 354  * from different directories, depending on which directories were given
 355  * in <envar>XDG_DATA_DIRS</envar> and
 356  * <envar>GSETTINGS_SCHEMA_DIR</envar>.  For this reason, all lookups
 357  * performed against the default source should probably be done
 358  * recursively.
 359  *
 360  * Returns: (transfer none): the default schema source
 361  *
 362  * Since: 2.32
 363  **/
 364  GSettingsSchemaSource *
 365 g_settings_schema_source_get_default (void)
 366 {
 367   initialise_schema_sources ();
 368
 369   return schema_sources;
 370 }
 371
 372 /**
 373  * g_settings_schema_source_lookup:
 374  * @source: a #GSettingsSchemaSource
 375  * @schema_id: a schema ID
 376  * @recursive: %TRUE if the lookup should be recursive
 377  *
 378  * Looks up a schema with the identifier @schema_id in @source.
 379  *
 380  * This function is not required for normal uses of #GSettings but it
 381  * may be useful to authors of plugin management systems or to those who
 382  * want to introspect the content of schemas.
 383  *
 384  * If the schema isn't found directly in @source and @recursive is %TRUE
 385  * then the parent sources will also be checked.
 386  *
 387  * If the schema isn't found, %NULL is returned.
 388  *
 389  * Returns: (transfer full): a new #GSettingsSchema
 390  *
 391  * Since: 2.32
 392  **/
 393 GSettingsSchema *
 394 g_settings_schema_source_lookup (GSettingsSchemaSource *source,
 395                                  const gchar           *schema_id,
 396                                  gboolean               recursive)
 397 {
 398   GSettingsSchema *schema;
 399   GvdbTable *table;
 400
 401   g_return_val_if_fail (source != NULL, NULL);
 402   g_return_val_if_fail (schema_id != NULL, NULL);
 403
 404   table = gvdb_table_get_table (source->table, schema_id);
 405
 406   if (table == NULL && recursive)
 407     for (source = source->parent; source; source = source->parent)
 408       if ((table = gvdb_table_get_table (source->table, schema_id)))
 409         break;
 410
 411   if (table == NULL)
 412     return NULL;
 413
 414   schema = g_slice_new0 (GSettingsSchema);
 415   schema->ref_count = 1;
 416   schema->id = g_strdup (schema_id);
 417   schema->table = table;
 418   schema->path = g_settings_schema_get_string (schema, ".path");
 419   schema->gettext_domain = g_settings_schema_get_string (schema, ".gettext-domain");
 420
 421   if (schema->gettext_domain)
 422     bind_textdomain_codeset (schema->gettext_domain, "UTF-8");
 423
 424   return schema;
 425 }
 426
 427 static gboolean
 428 steal_item (gpointer key,
 429             gpointer value,
 430             gpointer user_data)
 431 {
 432   gchar ***ptr = user_data;
 433
 434   *(*ptr)++ = (gchar *) key;
 435
 436   return TRUE;
 437 }
 438
 439 static const gchar * const *non_relocatable_schema_list;
 440 static const gchar * const *relocatable_schema_list;
 441 static gsize schema_lists_initialised;
 442
 443 static void
 444 ensure_schema_lists (void)
 445 {
 446   if (g_once_init_enter (&schema_lists_initialised))
 447     {
 448       GSettingsSchemaSource *source;
 449       GHashTable *single, *reloc;
 450       const gchar **ptr;
 451       gchar **list;
 452       gint i;
 453
 454       initialise_schema_sources ();
 455
 456       /* We use hash tables to avoid duplicate listings for schemas that
 457        * appear in more than one file.
 458        */
 459       single = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
 460       reloc = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
 461
 462       for (source = schema_sources; source; source = source->parent)
 463         {
 464           list = gvdb_table_list (source->table, "");
 465
 466           /* empty schema cache file? */
 467           if (list == NULL)
 468             continue;
 469
 470           for (i = 0; list[i]; i++)
 471             {
 472               if (!g_hash_table_lookup (single, list[i]) &&
 473                   !g_hash_table_lookup (reloc, list[i]))
 474                 {
 475                   GvdbTable *table;
 476
 477                   table = gvdb_table_get_table (source->table, list[i]);
 478                   g_assert (table != NULL);
 479
 480                   if (gvdb_table_has_value (table, ".path"))
 481                     g_hash_table_insert (single, g_strdup (list[i]), NULL);
 482                   else
 483                     g_hash_table_insert (reloc, g_strdup (list[i]), NULL);
 484
 485                   gvdb_table_unref (table);
 486                 }
 487             }
 488
 489           g_strfreev (list);
 490         }
 491
 492       ptr = g_new (const gchar *, g_hash_table_size (single) + 1);
 493       non_relocatable_schema_list = ptr;
 494       g_hash_table_foreach_steal (single, steal_item, &ptr);
 495       g_hash_table_unref (single);
 496       *ptr = NULL;
 497
 498       ptr = g_new (const gchar *, g_hash_table_size (reloc) + 1);
 499       relocatable_schema_list = ptr;
 500       g_hash_table_foreach_steal (reloc, steal_item, &ptr);
 501       g_hash_table_unref (reloc);
 502       *ptr = NULL;
 503
 504       g_once_init_leave (&schema_lists_initialised, TRUE);
 505     }
 506 }
 507
 508 /**
 509  * g_settings_list_schemas:
 510  *
 511  * Gets a list of the #GSettings schemas installed on the system.  The
 512  * returned list is exactly the list of schemas for which you may call
 513  * g_settings_new() without adverse effects.
 514  *
 515  * This function does not list the schemas that do not provide their own
 516  * paths (ie: schemas for which you must use
 517  * g_settings_new_with_path()).  See
 518  * g_settings_list_relocatable_schemas() for that.
 519  *
 520  * Returns: (element-type utf8) (transfer none):  a list of #GSettings
 521  *   schemas that are available.  The list must not be modified or
 522  *   freed.
 523  *
 524  * Since: 2.26
 525  **/
 526 const gchar * const *
 527 g_settings_list_schemas (void)
 528 {
 529   ensure_schema_lists ();
 530
 531   return non_relocatable_schema_list;
 532 }
 533
 534 /**
 535  * g_settings_list_relocatable_schemas:
 536  *
 537  * Gets a list of the relocatable #GSettings schemas installed on the
 538  * system.  These are schemas that do not provide their own path.  It is
 539  * usual to instantiate these schemas directly, but if you want to you
 540  * can use g_settings_new_with_path() to specify the path.
 541  *
 542  * The output of this function, taken together with the output of
 543  * g_settings_list_schemas() represents the complete list of all
 544  * installed schemas.
 545  *
 546  * Returns: (element-type utf8) (transfer none): a list of relocatable
 547  *   #GSettings schemas that are available.  The list must not be
 548  *   modified or freed.
 549  *
 550  * Since: 2.28
 551  **/
 552 const gchar * const *
 553 g_settings_list_relocatable_schemas (void)
 554 {
 555   ensure_schema_lists ();
 556
 557   return relocatable_schema_list;
 558 }
 559
 560 /**
 561  * g_settings_schema_ref:
 562  * @schema: a #GSettingsSchema
 563  *
 564  * Increase the reference count of @schema, returning a new reference.
 565  *
 566  * Returns: a new reference to @schema
 567  *
 568  * Since: 2.32
 569  **/
 570 GSettingsSchema *
 571 g_settings_schema_ref (GSettingsSchema *schema)
 572 {
 573   g_atomic_int_inc (&schema->ref_count);
 574
 575   return schema;
 576 }
 577
 578 /**
 579  * g_settings_schema_unref:
 580  * @schema: a #GSettingsSchema
 581  *
 582  * Decrease the reference count of @schema, possibly freeing it.
 583  *
 584  * Since: 2.32
 585  **/
 586 void
 587 g_settings_schema_unref (GSettingsSchema *schema)
 588 {
 589   if (g_atomic_int_dec_and_test (&schema->ref_count))
 590     {
 591       gvdb_table_unref (schema->table);
 592       g_free (schema->items);
 593       g_free (schema->id);
 594
 595       g_slice_free (GSettingsSchema, schema);
 596     }
 597 }
 598
 599 const gchar *
 600 g_settings_schema_get_string (GSettingsSchema *schema,
 601                               const gchar     *key)
 602 {
 603   const gchar *result = NULL;
 604   GVariant *value;
 605
 606   if ((value = gvdb_table_get_raw_value (schema->table, key)))
 607     {
 608       result = g_variant_get_string (value, NULL);
 609       g_variant_unref (value);
 610     }
 611
 612   return result;
 613 }
 614
 615 GVariantIter *
 616 g_settings_schema_get_value (GSettingsSchema *schema,
 617                              const gchar     *key)
 618 {
 619   GVariantIter *iter;
 620   GVariant *value;
 621
 622   value = gvdb_table_get_raw_value (schema->table, key);
 623
 624   if G_UNLIKELY (value == NULL || !g_variant_is_of_type (value, G_VARIANT_TYPE_TUPLE))
 625     g_error ("Settings schema '%s' does not contain a key named '%s'", schema->id, key);
 626
 627   iter = g_variant_iter_new (value);
 628   g_variant_unref (value);
 629
 630   return iter;
 631 }
 632
 633 /**
 634  * g_settings_schema_get_path:
 635  * @schema: a #GSettingsSchema
 636  *
 637  * Gets the path associated with @schema, or %NULL.
 638  *
 639  * Schemas may be single-instance or relocatable.  Single-instance
 640  * schemas correspond to exactly one set of keys in the backend
 641  * database: those located at the path returned by this function.
 642  *
 643  * Relocatable schemas can be referenced by other schemas and can
 644  * threfore describe multiple sets of keys at different locations.  For
 645  * relocatable schemas, this function will return %NULL.
 646  *
 647  * Returns: (transfer none): the path of the schema, or %NULL
 648  *
 649  * Since: 2.32
 650  **/
 651 const gchar *
 652 g_settings_schema_get_path (GSettingsSchema *schema)
 653 {
 654   return schema->path;
 655 }
 656
 657 const gchar *
 658 g_settings_schema_get_gettext_domain (GSettingsSchema *schema)
 659 {
 660   return schema->gettext_domain;
 661 }
 662
 663 gboolean
 664 g_settings_schema_has_key (GSettingsSchema *schema,
 665                            const gchar     *key)
 666 {
 667   return gvdb_table_has_value (schema->table, key);
 668 }
 669
 670 const GQuark *
 671 g_settings_schema_list (GSettingsSchema *schema,
 672                         gint            *n_items)
 673 {
 674   gint i, j;
 675
 676   if (schema->items == NULL)
 677     {
 678       gchar **list;
 679       gint len;
 680
 681       list = gvdb_table_list (schema->table, "");
 682       len = list ? g_strv_length (list) : 0;
 683
 684       schema->items = g_new (GQuark, len);
 685       j = 0;
 686
 687       for (i = 0; i < len; i++)
 688         if (list[i][0] != '.')
 689           {
 690             if (g_str_has_suffix (list[i], "/"))
 691               {
 692                 /* This is a child.  Check to make sure that
 693                  * instantiating the child would actually work before we
 694                  * return it from list() and cause a crash.
 695                  */
 696                 GSettingsSchemaSource *source;
 697                 GVariant *child_schema;
 698                 GvdbTable *child_table;
 699
 700                 child_schema = gvdb_table_get_raw_value (schema->table, list[i]);
 701                 if (!child_schema)
 702                   continue;
 703
 704                 child_table = NULL;
 705
 706                 for (source = schema_sources; source; source = source->parent)
 707                   if ((child_table = gvdb_table_get_table (source->table, g_variant_get_string (child_schema, NULL))))
 708                     break;
 709
 710                 g_variant_unref (child_schema);
 711
 712                 /* Schema is not found -> don't add it to the list */
 713                 if (child_table == NULL)
 714                   continue;
 715
 716                 /* Make sure the schema is relocatable or at the
 717                  * expected path
 718                  */
 719                 if (gvdb_table_has_value (child_table, ".path"))
 720                   {
 721                     GVariant *path;
 722                     gchar *expected;
 723                     gboolean same;
 724
 725                     path = gvdb_table_get_raw_value (child_table, ".path");
 726                     expected = g_strconcat (schema->path, list[i], NULL);
 727                     same = g_str_equal (expected, g_variant_get_string (path, NULL));
 728                     g_variant_unref (path);
 729                     g_free (expected);
 730
 731                     if (!same)
 732                       {
 733                         gvdb_table_unref (child_table);
 734                         continue;
 735                       }
 736                   }
 737
 738                 gvdb_table_unref (child_table);
 739                 /* Else, it's good... */
 740               }
 741
 742             schema->items[j++] = g_quark_from_string (list[i]);
 743           }
 744       schema->n_items = j;
 745
 746       g_strfreev (list);
 747     }
 748
 749   *n_items = schema->n_items;
 750   return schema->items;
 751 }
 752
 753 /**
 754  * g_settings_schema_get_id:
 755  * @schema: a #GSettingsSchema
 756  *
 757  * Get the ID of @schema.
 758  *
 759  * Returns: (transfer none): the ID
 760  **/
 761 const gchar *
 762 g_settings_schema_get_id (GSettingsSchema *schema)
 763 {
 764   return schema->id;
 765 }
 766
 767 static inline void
 768 endian_fixup (GVariant **value)
 769 {
 770 #if G_BYTE_ORDER == G_BIG_ENDIAN
 771   GVariant *tmp;
 772
 773   tmp = g_variant_byteswap (*value);
 774   g_variant_unref (*value);
 775   *value = tmp;
 776 #endif
 777 }
 778
 779 void
 780 g_settings_schema_key_init (GSettingsSchemaKey *key,
 781                             GSettingsSchema    *schema,
 782                             const gchar        *name)
 783 {
 784   GVariantIter *iter;
 785   GVariant *data;
 786   guchar code;
 787
 788   memset (key, 0, sizeof *key);
 789
 790   iter = g_settings_schema_get_value (schema, name);
 791
 792   key->schema = g_settings_schema_ref (schema);
 793   key->default_value = g_variant_iter_next_value (iter);
 794   endian_fixup (&key->default_value);
 795   key->type = g_variant_get_type (key->default_value);
 796   key->name = g_intern_string (name);
 797
 798   while (g_variant_iter_next (iter, "(y*)", &code, &data))
 799     {
 800       switch (code)
 801         {
 802         case 'l':
 803           /* translation requested */
 804           g_variant_get (data, "(y&s)", &key->lc_char, &key->unparsed);
 805           break;
 806
 807         case 'e':
 808           /* enumerated types... */
 809           key->is_enum = TRUE;
 810           goto choice;
 811
 812         case 'f':
 813           /* flags... */
 814           key->is_flags = TRUE;
 815           goto choice;
 816
 817         choice: case 'c':
 818           /* ..., choices, aliases */
 819           key->strinfo = g_variant_get_fixed_array (data, &key->strinfo_length, sizeof (guint32));
 820           break;
 821
 822         case 'r':
 823           g_variant_get (data, "(**)", &key->minimum, &key->maximum);
 824           endian_fixup (&key->minimum);
 825           endian_fixup (&key->maximum);
 826           break;
 827
 828         default:
 829           g_warning ("unknown schema extension '%c'", code);
 830           break;
 831         }
 832
 833       g_variant_unref (data);
 834     }
 835
 836   g_variant_iter_free (iter);
 837 }
 838
 839 void
 840 g_settings_schema_key_clear (GSettingsSchemaKey *key)
 841 {
 842   if (key->minimum)
 843     g_variant_unref (key->minimum);
 844
 845   if (key->maximum)
 846     g_variant_unref (key->maximum);
 847
 848   g_variant_unref (key->default_value);
 849
 850   g_settings_schema_unref (key->schema);
 851 }
 852
 853 gboolean
 854 g_settings_schema_key_type_check (GSettingsSchemaKey *key,
 855                                   GVariant           *value)
 856 {
 857   g_return_val_if_fail (value != NULL, FALSE);
 858
 859   return g_variant_is_of_type (value, key->type);
 860 }
 861
 862 gboolean
 863 g_settings_schema_key_range_check (GSettingsSchemaKey *key,
 864                                    GVariant           *value)
 865 {
 866   if (key->minimum == NULL && key->strinfo == NULL)
 867     return TRUE;
 868
 869   if (g_variant_is_container (value))
 870     {
 871       gboolean ok = TRUE;
 872       GVariantIter iter;
 873       GVariant *child;
 874
 875       g_variant_iter_init (&iter, value);
 876       while (ok && (child = g_variant_iter_next_value (&iter)))
 877         {
 878           ok = g_settings_schema_key_range_check (key, child);
 879           g_variant_unref (child);
 880         }
 881
 882       return ok;
 883     }
 884
 885   if (key->minimum)
 886     {
 887       return g_variant_compare (key->minimum, value) <= 0 &&
 888              g_variant_compare (value, key->maximum) <= 0;
 889     }
 890
 891   return strinfo_is_string_valid (key->strinfo, key->strinfo_length,
 892                                   g_variant_get_string (value, NULL));
 893 }
 894
 895 GVariant *
 896 g_settings_schema_key_range_fixup (GSettingsSchemaKey *key,
 897                                    GVariant           *value)
 898 {
 899   const gchar *target;
 900
 901   if (g_settings_schema_key_range_check (key, value))
 902     return g_variant_ref (value);
 903
 904   if (key->strinfo == NULL)
 905     return NULL;
 906
 907   if (g_variant_is_container (value))
 908     {
 909       GVariantBuilder builder;
 910       GVariantIter iter;
 911       GVariant *child;
 912
 913       g_variant_iter_init (&iter, value);
 914       g_variant_builder_init (&builder, g_variant_get_type (value));
 915
 916       while ((child = g_variant_iter_next_value (&iter)))
 917         {
 918           GVariant *fixed;
 919
 920           fixed = g_settings_schema_key_range_fixup (key, child);
 921           g_variant_unref (child);
 922
 923           if (fixed == NULL)
 924             {
 925               g_variant_builder_clear (&builder);
 926               return NULL;
 927             }
 928
 929           g_variant_builder_add_value (&builder, fixed);
 930           g_variant_unref (fixed);
 931         }
 932
 933       return g_variant_ref_sink (g_variant_builder_end (&builder));
 934     }
 935
 936   target = strinfo_string_from_alias (key->strinfo, key->strinfo_length,
 937                                       g_variant_get_string (value, NULL));
 938   return target ? g_variant_ref_sink (g_variant_new_string (target)) : NULL;
 939 }
 940
 941
 942 GVariant *
 943 g_settings_schema_key_get_translated_default (GSettingsSchemaKey *key)
 944 {
 945   const gchar *translated;
 946   GError *error = NULL;
 947   const gchar *domain;
 948   GVariant *value;
 949
 950   domain = g_settings_schema_get_gettext_domain (key->schema);
 951
 952   if (key->lc_char == '\0')
 953     /* translation not requested for this key */
 954     return NULL;
 955
 956   if (key->lc_char == 't')
 957     translated = g_dcgettext (domain, key->unparsed, LC_TIME);
 958   else
 959     translated = g_dgettext (domain, key->unparsed);
 960
 961   if (translated == key->unparsed)
 962     /* the default value was not translated */
 963     return NULL;
 964
 965   /* try to parse the translation of the unparsed default */
 966   value = g_variant_parse (key->type, translated, NULL, NULL, &error);
 967
 968   if (value == NULL)
 969     {
 970       g_warning ("Failed to parse translated string '%s' for "
 971                  "key '%s' in schema '%s': %s", key->unparsed, key->name,
 972                  g_settings_schema_get_id (key->schema), error->message);
 973       g_warning ("Using untranslated default instead.");
 974       g_error_free (error);
 975     }
 976
 977   else if (!g_settings_schema_key_range_check (key, value))
 978     {
 979       g_warning ("Translated default '%s' for key '%s' in schema '%s' "
 980                  "is outside of valid range", key->unparsed, key->name,
 981                  g_settings_schema_get_id (key->schema));
 982       g_variant_unref (value);
 983       value = NULL;
 984     }
 985
 986   return value;
 987 }
 988
 989 gint
 990 g_settings_schema_key_to_enum (GSettingsSchemaKey *key,
 991                                GVariant           *value)
 992 {
 993   gboolean it_worked;
 994   guint result;
 995
 996   it_worked = strinfo_enum_from_string (key->strinfo, key->strinfo_length,
 997                                         g_variant_get_string (value, NULL),
 998                                         &result);
 999
1000   /* 'value' can only come from the backend after being filtered for validity,
1001    * from the translation after being filtered for validity, or from the schema
1002    * itself (which the schema compiler checks for validity).  If this assertion
1003    * fails then it's really a bug in GSettings or the schema compiler...
1004    */
1005   g_assert (it_worked);
1006
1007   return result;
1008 }
1009
1010 GVariant *
1011 g_settings_schema_key_from_enum (GSettingsSchemaKey *key,
1012                                  gint                value)
1013 {
1014   const gchar *string;
1015
1016   string = strinfo_string_from_enum (key->strinfo, key->strinfo_length, value);
1017
1018   if (string == NULL)
1019     return NULL;
1020
1021   return g_variant_new_string (string);
1022 }
1023
1024 guint
1025 g_settings_schema_key_to_flags (GSettingsSchemaKey *key,
1026                                 GVariant           *value)
1027 {
1028   GVariantIter iter;
1029   const gchar *flag;
1030   guint result;
1031
1032   result = 0;
1033   g_variant_iter_init (&iter, value);
1034   while (g_variant_iter_next (&iter, "&s", &flag))
1035     {
1036       gboolean it_worked;
1037       guint flag_value;
1038
1039       it_worked = strinfo_enum_from_string (key->strinfo, key->strinfo_length, flag, &flag_value);
1040       /* as in g_settings_to_enum() */
1041       g_assert (it_worked);
1042
1043       result |= flag_value;
1044     }
1045
1046   return result;
1047 }
1048
1049 GVariant *
1050 g_settings_schema_key_from_flags (GSettingsSchemaKey *key,
1051                                   guint               value)
1052 {
1053   GVariantBuilder builder;
1054   gint i;
1055
1056   g_variant_builder_init (&builder, G_VARIANT_TYPE ("as"));
1057
1058   for (i = 0; i < 32; i++)
1059     if (value & (1u << i))
1060       {
1061         const gchar *string;
1062
1063         string = strinfo_string_from_enum (key->strinfo, key->strinfo_length, 1u << i);
1064
1065         if (string == NULL)
1066           {
1067             g_variant_builder_clear (&builder);
1068             return NULL;
1069           }
1070
1071         g_variant_builder_add (&builder, "s", string);
1072       }
1073
1074   return g_variant_builder_end (&builder);
1075 }