gio/gsettingsbackend.c

   1 /*
   2  * Copyright © 2009, 2010 Codethink Limited
   3  * Copyright © 2010 Red Hat, Inc.
   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  * Authors: Ryan Lortie <desrt@desrt.ca>
  21  *          Matthias Clasen <mclasen@redhat.com>
  22  */
  23
  24 #include "config.h"
  25
  26 #include "gsettingsbackendinternal.h"
  27 #include "gnullsettingsbackend.h"
  28 #include "giomodule-priv.h"
  29 #include "gio-marshal.h"
  30
  31 #include <string.h>
  32 #include <stdlib.h>
  33 #include <glib.h>
  34 #include <glibintl.h>
  35
  36 #include "gioalias.h"
  37
  38 G_DEFINE_ABSTRACT_TYPE (GSettingsBackend, g_settings_backend, G_TYPE_OBJECT)
  39
  40 typedef struct _GSettingsBackendWatch GSettingsBackendWatch;
  41
  42 struct _GSettingsBackendPrivate
  43 {
  44   GSettingsBackendWatch *watches;
  45   gchar *context;
  46 };
  47
  48 enum
  49 {
  50   PROP_0,
  51   PROP_CONTEXT
  52 };
  53
  54 /**
  55  * SECTION:gsettingsbackend
  56  * @title: GSettingsBackend
  57  * @short_description: an interface for settings backend implementations
  58  * @include: gio/gsettingsbackend.h
  59  * @see_also: #GSettings, #GIOExtensionPoint
  60  *
  61  * The #GSettingsBackend interface defines a generic interface for
  62  * non-strictly-typed data that is stored in a hierarchy. To implement
  63  * an alternative storage backend for #GSettings, you need to implement
  64  * the #GSettingsBackend interface and then make it implement the
  65  * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
  66  *
  67  * The interface defines methods for reading and writing values, a
  68  * method for determining if writing of certain values will fail
  69  * (lockdown) and a change notification mechanism.
  70  *
  71  * The semantics of the interface are very precisely defined and
  72  * implementations must carefully adhere to the expectations of
  73  * callers that are documented on each of the interface methods.
  74  *
  75  * Some of the GSettingsBackend functions accept or return a #GTree.
  76  * These trees always have strings as keys and #GVariant as values.
  77  * g_settings_backend_create_tree() is a convenience function to create
  78  * suitable trees.
  79  *
  80  * <note><para>
  81  * The #GSettingsBackend API is exported to allow third-party
  82  * implementations, but does not carry the same stability guarantees
  83  * as the public GIO API. For this reason, you have to define the
  84  * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
  85  * <filename>gio/gsettingsbackend.h</filename>
  86  * </para></note>
  87  **/
  88
  89 struct _GSettingsBackendWatch
  90 {
  91   GMainContext                            *context;
  92   GSettingsBackendChangedFunc              changed;
  93   GSettingsBackendPathChangedFunc          path_changed;
  94   GSettingsBackendKeysChangedFunc          keys_changed;
  95   GSettingsBackendWritableChangedFunc      writable_changed;
  96   GSettingsBackendPathWritableChangedFunc  path_writable_changed;
  97   gpointer                                 user_data;
  98
  99   GSettingsBackendWatch                   *next;
 100 };
 101
 102 /*< private >
 103  * g_settings_backend_watch:
 104  * @backend: a #GSettingsBackend
 105  * @context: a #GMainContext, or %NULL
 106  * ...: callbacks...
 107  * @user_data: the user_data for the callbacks
 108  *
 109  * Registers a new watch on a #GSettingsBackend.
 110  *
 111  * note: %NULL @context does not mean "default main context" but rather,
 112  * "it is okay to dispatch in any context".  If the default main context
 113  * is specifically desired then it must be given.
 114  **/
 115 void
 116 g_settings_backend_watch (GSettingsBackend                        *backend,
 117                           GMainContext                            *context,
 118                           GSettingsBackendChangedFunc              changed,
 119                           GSettingsBackendPathChangedFunc          path_changed,
 120                           GSettingsBackendKeysChangedFunc          keys_changed,
 121                           GSettingsBackendWritableChangedFunc      writable_changed,
 122                           GSettingsBackendPathWritableChangedFunc  path_writable_changed,
 123                           gpointer                                 user_data)
 124 {
 125   GSettingsBackendWatch *watch;
 126
 127   watch = g_slice_new (GSettingsBackendWatch);
 128   /* don't need to ref the context here because the watch is
 129    * only valid for the lifecycle of the attaching GSettings
 130    * and it is already holding the context.
 131    */
 132   watch->context = context;
 133   watch->changed = changed;
 134   watch->path_changed = path_changed;
 135   watch->keys_changed = keys_changed;
 136   watch->writable_changed = writable_changed;
 137   watch->path_writable_changed = path_writable_changed;
 138   watch->user_data = user_data;
 139
 140   watch->next = backend->priv->watches;
 141   backend->priv->watches = watch;
 142 }
 143
 144 void
 145 g_settings_backend_unwatch (GSettingsBackend *backend,
 146                             gpointer          user_data)
 147 {
 148   GSettingsBackendWatch **ptr;
 149
 150   for (ptr = &backend->priv->watches; *ptr; ptr = &(*ptr)->next)
 151     if ((*ptr)->user_data == user_data)
 152       {
 153         GSettingsBackendWatch *tmp = *ptr;
 154
 155         *ptr = tmp->next;
 156         g_slice_free (GSettingsBackendWatch, tmp);
 157
 158         return;
 159       }
 160
 161   g_assert_not_reached ();
 162 }
 163
 164 static gboolean
 165 is_key (const gchar *key)
 166 {
 167   gint length;
 168   gint i;
 169
 170   g_return_val_if_fail (key != NULL, FALSE);
 171   g_return_val_if_fail (key[0] == '/', FALSE);
 172
 173   for (i = 1; key[i]; i++)
 174     g_return_val_if_fail (key[i] != '/' || key[i + 1] != '/', FALSE);
 175
 176   length = i;
 177
 178   g_return_val_if_fail (key[length - 1] != '/', FALSE);
 179
 180   return TRUE;
 181 }
 182
 183 static gboolean
 184 is_path (const gchar *path)
 185 {
 186   gint length;
 187   gint i;
 188
 189   g_return_val_if_fail (path != NULL, FALSE);
 190   g_return_val_if_fail (path[0] == '/', FALSE);
 191
 192   for (i = 1; path[i]; i++)
 193     g_return_val_if_fail (path[i] != '/' || path[i + 1] != '/', FALSE);
 194
 195   length = i;
 196
 197   g_return_val_if_fail (path[length - 1] == '/', FALSE);
 198
 199   return TRUE;
 200 }
 201
 202 static GMainContext *
 203 g_settings_backend_get_active_context (void)
 204 {
 205   GMainContext *context;
 206   GSource *source;
 207
 208   if ((source = g_main_current_source ()))
 209     context = g_source_get_context (source);
 210
 211   else
 212     {
 213       context = g_main_context_get_thread_default ();
 214
 215       if (context == NULL)
 216         context = g_main_context_default ();
 217     }
 218
 219   return context;
 220 }
 221
 222 typedef struct
 223 {
 224   void (*function) (GSettingsBackend *backend,
 225                     const gchar      *name,
 226                     gpointer          data1,
 227                     gpointer          data2,
 228                     gpointer          data3);
 229   GSettingsBackend *backend;
 230   gchar *name;
 231
 232   gpointer data1;
 233   gpointer data2;
 234   gpointer data3;
 235
 236   GDestroyNotify destroy_data1;
 237 } GSettingsBackendClosure;
 238
 239 static gboolean
 240 g_settings_backend_invoke_closure (gpointer user_data)
 241 {
 242   GSettingsBackendClosure *closure = user_data;
 243
 244   closure->function (closure->backend, closure->name,
 245                      closure->data1, closure->data2, closure->data3);
 246
 247   g_object_unref (closure->backend);
 248
 249   if (closure->destroy_data1)
 250     closure->destroy_data1 (closure->data1);
 251
 252   g_free (closure->name);
 253
 254   /* make a donation to the magazine in this thread... */
 255   g_slice_free (GSettingsBackendClosure, closure);
 256
 257   return FALSE;
 258 }
 259
 260 static void
 261 g_settings_backend_dispatch_signal (GSettingsBackend *backend,
 262                                     GMainContext     *context,
 263                                     gpointer          function,
 264                                     const gchar      *name,
 265                                     gpointer          data1,
 266                                     GDestroyNotify    destroy_data1,
 267                                     gpointer          data2,
 268                                     gpointer          data3)
 269 {
 270   GSettingsBackendClosure *closure;
 271   GSource *source;
 272
 273   /* XXX we have a rather obnoxious race condition here.
 274    *
 275    * In the meantime of this call being dispatched to the other thread,
 276    * the GSettings instance that is pointed to by the user_data may have
 277    * been freed.
 278    *
 279    * There are two ways of handling this:
 280    *
 281    *   1) Ensure that the watch is still valid by the time it arrives in
 282    *      the destination thread (potentially expensive)
 283    *
 284    *   2) Do proper refcounting (requires changing the interface).
 285    */
 286   closure = g_slice_new (GSettingsBackendClosure);
 287   closure->backend = g_object_ref (backend);
 288   closure->function = function;
 289
 290   /* we could make more effort to share this between all of the
 291    * dispatches but it seems that it might be an overall loss in terms
 292    * of performance/memory use and is definitely not worth the effort.
 293    */
 294   closure->name = g_strdup (name);
 295
 296   /* ditto. */
 297   closure->data1 = data1;
 298   closure->destroy_data1 = destroy_data1;
 299
 300   closure->data2 = data2;
 301   closure->data3 = data3;
 302
 303   source = g_idle_source_new ();
 304   g_source_set_callback (source,
 305                          g_settings_backend_invoke_closure,
 306                          closure, NULL);
 307   g_source_attach (source, context);
 308   g_source_unref (source);
 309 }
 310
 311 /**
 312  * g_settings_backend_changed:
 313  * @backend: a #GSettingsBackend implementation
 314  * @key: the name of the key
 315  * @origin_tag: the origin tag
 316  *
 317  * Signals that a single key has possibly changed.  Backend
 318  * implementations should call this if a key has possibly changed its
 319  * value.
 320  *
 321  * @key must be a valid key (ie: starting with a slash, not containing
 322  * '//', and not ending with a slash).
 323  *
 324  * The implementation must call this function during any call to
 325  * g_settings_backend_write(), before the call returns (except in the
 326  * case that no keys are actually changed and it cares to detect this
 327  * fact).  It may not rely on the existence of a mainloop for
 328  * dispatching the signal later.
 329  *
 330  * The implementation may call this function at any other time it likes
 331  * in response to other events (such as changes occuring outside of the
 332  * program).  These calls may originate from a mainloop or may originate
 333  * in response to any other action (including from calls to
 334  * g_settings_backend_write()).
 335  *
 336  * In the case that this call is in response to a call to
 337  * g_settings_backend_write() then @origin_tag must be set to the same
 338  * value that was passed to that call.
 339  *
 340  * Since: 2.26
 341  **/
 342 void
 343 g_settings_backend_changed (GSettingsBackend *backend,
 344                             const gchar      *key,
 345                             gpointer          origin_tag)
 346 {
 347   GSettingsBackendWatch *watch;
 348   GMainContext *context;
 349
 350   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 351   g_return_if_fail (is_key (key));
 352
 353   context = g_settings_backend_get_active_context ();
 354
 355   for (watch = backend->priv->watches; watch; watch = watch->next)
 356     if (watch->context == context || watch->context == NULL)
 357       watch->changed (backend, key, origin_tag, watch->user_data);
 358     else
 359       g_settings_backend_dispatch_signal (backend, watch->context,
 360                                           watch->changed, key, origin_tag,
 361                                           NULL, watch->user_data, NULL);
 362 }
 363
 364 /**
 365  * g_settings_backend_keys_changed:
 366  * @backend: a #GSettingsBackend implementation
 367  * @path: the path containing the changes
 368  * @items: the %NULL-terminated list of changed keys
 369  * @origin_tag: the origin tag
 370  *
 371  * Signals that a list of keys have possibly changed.  Backend
 372  * implementations should call this if keys have possibly changed their
 373  * values.
 374  *
 375  * @path must be a valid path (ie: starting and ending with a slash and
 376  * not containing '//').  Each string in @items must form a valid key
 377  * name when @path is prefixed to it (ie: each item must not start or
 378  * end with '/' and must not contain '//').
 379  *
 380  * The meaning of this signal is that any of the key names resulting
 381  * from the contatenation of @path with each item in @items may have
 382  * changed.
 383  *
 384  * The same rules for when notifications must occur apply as per
 385  * g_settings_backend_changed().  These two calls can be used
 386  * interchangeably if exactly one item has changed (although in that
 387  * case g_settings_backend_changed() is definitely preferred).
 388  *
 389  * For efficiency reasons, the implementation should strive for @path to
 390  * be as long as possible (ie: the longest common prefix of all of the
 391  * keys that were changed) but this is not strictly required.
 392  *
 393  * Since: 2.26
 394  */
 395 void
 396 g_settings_backend_keys_changed (GSettingsBackend    *backend,
 397                                  const gchar         *path,
 398                                  gchar const * const *items,
 399                                  gpointer             origin_tag)
 400 {
 401   GSettingsBackendWatch *watch;
 402
 403   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 404   g_return_if_fail (path[0] == '\0' || is_path (path));
 405   g_return_if_fail (items != NULL);
 406
 407   for (watch = backend->priv->watches; watch; watch = watch->next)
 408     watch->keys_changed (backend, path, items, origin_tag, watch->user_data);
 409 }
 410
 411 /**
 412  * g_settings_backend_path_changed:
 413  * @backend: a #GSettingsBackend implementation
 414  * @path: the path containing the changes
 415  * @origin_tag: the origin tag
 416  *
 417  * Signals that all keys below a given path may have possibly changed.
 418  * Backend implementations should call this if an entire path of keys
 419  * have possibly changed their values.
 420  *
 421  * @path must be a valid path (ie: starting and ending with a slash and
 422  * not containing '//').
 423  *
 424  * The meaning of this signal is that any of the key which has a name
 425  * starting with @path may have changed.
 426  *
 427  * The same rules for when notifications must occur apply as per
 428  * g_settings_backend_changed().  This call might be an appropriate
 429  * reasponse to a 'reset' call but implementations are also free to
 430  * explicitly list the keys that were affected by that call if they can
 431  * easily do so.
 432  *
 433  * For efficiency reasons, the implementation should strive for @path to
 434  * be as long as possible (ie: the longest common prefix of all of the
 435  * keys that were changed) but this is not strictly required.  As an
 436  * example, if this function is called with the path of "/" then every
 437  * single key in the application will be notified of a possible change.
 438  *
 439  * Since: 2.26
 440  */
 441 void
 442 g_settings_backend_path_changed (GSettingsBackend *backend,
 443                                  const gchar      *path,
 444                                  gpointer          origin_tag)
 445 {
 446   GSettingsBackendWatch *watch;
 447
 448   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 449   g_return_if_fail (is_path (path));
 450
 451   for (watch = backend->priv->watches; watch; watch = watch->next)
 452     watch->path_changed (backend, path, origin_tag, watch->user_data);
 453 }
 454
 455 /**
 456  * g_settings_backend_writable_changed:
 457  * @backend: a #GSettingsBackend implementation
 458  * @key: the name of the key
 459  *
 460  * Signals that the writability of a single key has possibly changed.
 461  *
 462  * Since GSettings performs no locking operations for itself, this call
 463  * will always be made in response to external events.
 464  *
 465  * Since: 2.26
 466  **/
 467 void
 468 g_settings_backend_writable_changed (GSettingsBackend *backend,
 469                                      const gchar      *key)
 470 {
 471   GSettingsBackendWatch *watch;
 472
 473   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 474   g_return_if_fail (is_key (key));
 475
 476   for (watch = backend->priv->watches; watch; watch = watch->next)
 477     watch->writable_changed (backend, key, watch->user_data);
 478 }
 479
 480 /**
 481  * g_settings_backend_path_writable_changed:
 482  * @backend: a #GSettingsBackend implementation
 483  * @path: the name of the path
 484  *
 485  * Signals that the writability of all keys below a given path may have
 486  * changed.
 487  *
 488  * Since GSettings performs no locking operations for itself, this call
 489  * will always be made in response to external events.
 490  *
 491  * Since: 2.26
 492  **/
 493 void
 494 g_settings_backend_path_writable_changed (GSettingsBackend *backend,
 495                                           const gchar      *path)
 496 {
 497   GSettingsBackendWatch *watch;
 498
 499   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 500   g_return_if_fail (is_path (path));
 501
 502   for (watch = backend->priv->watches; watch; watch = watch->next)
 503     watch->path_writable_changed (backend, path, watch->user_data);
 504 }
 505
 506 typedef struct
 507 {
 508   const gchar **keys;
 509   GVariant **values;
 510   gint prefix_len;
 511   gchar *prefix;
 512 } FlattenState;
 513
 514 static gboolean
 515 g_settings_backend_flatten_one (gpointer key,
 516                                 gpointer value,
 517                                 gpointer user_data)
 518 {
 519   FlattenState *state = user_data;
 520   const gchar *skey = key;
 521   gint i;
 522
 523   g_return_val_if_fail (is_key (key), TRUE);
 524
 525   /* calculate longest common prefix */
 526   if (state->prefix == NULL)
 527     {
 528       gchar *last_byte;
 529
 530       /* first key?  just take the prefix up to the last '/' */
 531       state->prefix = g_strdup (skey);
 532       last_byte = strrchr (state->prefix, '/') + 1;
 533       state->prefix_len = last_byte - state->prefix;
 534       *last_byte = '\0';
 535     }
 536   else
 537     {
 538       /* find the first character that does not match.  we will
 539        * definitely find one because the prefix ends in '/' and the key
 540        * does not.  also: no two keys in the tree are the same.
 541        */
 542       for (i = 0; state->prefix[i] == skey[i]; i++);
 543
 544       /* check if we need to shorten the prefix */
 545       if (state->prefix[i] != '\0')
 546         {
 547           /* find the nearest '/', terminate after it */
 548           while (state->prefix[i - 1] != '/')
 549             i--;
 550
 551           state->prefix[i] = '\0';
 552           state->prefix_len = i;
 553         }
 554     }
 555
 556
 557   /* save the entire item into the array.
 558    * the prefixes will be removed later.
 559    */
 560   *state->keys++ = key;
 561
 562   if (state->values)
 563     *state->values++ = value;
 564
 565   return FALSE;
 566 }
 567
 568 /**
 569  * g_settings_backend_flatten_tree:
 570  * @tree: a #GTree containing the changes
 571  * @path: the location to save the path
 572  * @keys: the location to save the relative keys
 573  * @values: the location to save the values, or %NULL
 574  *
 575  * Calculate the longest common prefix of all keys in a tree and write
 576  * out an array of the key names relative to that prefix and,
 577  * optionally, the value to store at each of those keys.
 578  *
 579  * You must free the value returned in @path, @keys and @values using
 580  * g_free().  You should not attempt to free or unref the contents of
 581  * @keys or @values.
 582  *
 583  * Since: 2.26
 584  **/
 585 void
 586 g_settings_backend_flatten_tree (GTree         *tree,
 587                                  gchar        **path,
 588                                  const gchar ***keys,
 589                                  GVariant    ***values)
 590 {
 591   FlattenState state = { 0, };
 592   gsize nnodes;
 593
 594   nnodes = g_tree_nnodes (tree);
 595
 596   *keys = state.keys = g_new (const gchar *, nnodes + 1);
 597   state.keys[nnodes] = NULL;
 598
 599   if (values != NULL)
 600     {
 601       *values = state.values = g_new (GVariant *, nnodes + 1);
 602       state.values[nnodes] = NULL;
 603     }
 604
 605   g_tree_foreach (tree, g_settings_backend_flatten_one, &state);
 606   g_return_if_fail (*keys + nnodes == state.keys);
 607
 608   *path = state.prefix;
 609   while (nnodes--)
 610     *--state.keys += state.prefix_len;
 611 }
 612
 613 /**
 614  * g_settings_backend_changed_tree:
 615  * @backend: a #GSettingsBackend implementation
 616  * @tree: a #GTree containing the changes
 617  * @origin_tag: the origin tag
 618  *
 619  * This call is a convenience wrapper.  It gets the list of changes from
 620  * @tree, computes the longest common prefix and calls
 621  * g_settings_backend_changed().
 622  *
 623  * Since: 2.26
 624  **/
 625 void
 626 g_settings_backend_changed_tree (GSettingsBackend *backend,
 627                                  GTree            *tree,
 628                                  gpointer          origin_tag)
 629 {
 630   GSettingsBackendWatch *watch;
 631   const gchar **keys;
 632   gchar *path;
 633
 634   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
 635
 636   g_settings_backend_flatten_tree (tree, &path, &keys, NULL);
 637
 638   for (watch = backend->priv->watches; watch; watch = watch->next)
 639     watch->keys_changed (backend, path, keys, origin_tag, watch->user_data);
 640
 641   g_free (path);
 642   g_free (keys);
 643 }
 644
 645 /*< private >
 646  * g_settings_backend_read:
 647  * @backend: a #GSettingsBackend implementation
 648  * @key: the key to read
 649  * @expected_type: a #GVariantType hint
 650  * @returns: the value that was read, or %NULL
 651  *
 652  * Reads a key. This call will never block.
 653  *
 654  * If the key exists, the value associated with it will be returned.
 655  * If the key does not exist, %NULL will be returned.
 656  *
 657  * If @expected_type is given, it serves as a type hint to the backend.
 658  * If you expect a key of a certain type then you should give
 659  * @expected_type to increase your chances of getting it.  Some backends
 660  * may ignore this argument and return values of a different type; it is
 661  * mostly used by backends that don't store strong type information.
 662  */
 663 GVariant *
 664 g_settings_backend_read (GSettingsBackend   *backend,
 665                          const gchar        *key,
 666                          const GVariantType *expected_type,
 667                          gboolean            default_value)
 668 {
 669   return G_SETTINGS_BACKEND_GET_CLASS (backend)
 670     ->read (backend, key, expected_type, default_value);
 671 }
 672
 673 /*< private >
 674  * g_settings_backend_write:
 675  * @backend: a #GSettingsBackend implementation
 676  * @key: the name of the key
 677  * @value: a #GVariant value to write to this key
 678  * @origin_tag: the origin tag
 679  * @returns: %TRUE if the write succeeded, %FALSE if the key was not writable
 680  *
 681  * Writes exactly one key.
 682  *
 683  * This call does not fail.  During this call a
 684  * #GSettingsBackend::changed signal will be emitted if the value of the
 685  * key has changed.  The updated key value will be visible to any signal
 686  * callbacks.
 687  *
 688  * One possible method that an implementation might deal with failures is
 689  * to emit a second "changed" signal (either during this call, or later)
 690  * to indicate that the affected keys have suddenly "changed back" to their
 691  * old values.
 692  */
 693 gboolean
 694 g_settings_backend_write (GSettingsBackend *backend,
 695                           const gchar      *key,
 696                           GVariant         *value,
 697                           gpointer          origin_tag)
 698 {
 699   return G_SETTINGS_BACKEND_GET_CLASS (backend)
 700     ->write (backend, key, value, origin_tag);
 701 }
 702
 703 /*< private >
 704  * g_settings_backend_write_keys:
 705  * @backend: a #GSettingsBackend implementation
 706  * @values: a #GTree containing key-value pairs to write
 707  * @origin_tag: the origin tag
 708  *
 709  * Writes one or more keys.  This call will never block.
 710  *
 711  * The key of each item in the tree is the key name to write to and the
 712  * value is a #GVariant to write.  The proper type of #GTree for this
 713  * call can be created with g_settings_backend_create_tree().  This call
 714  * might take a reference to the tree; you must not modified the #GTree
 715  * after passing it to this call.
 716  *
 717  * This call does not fail.  During this call a #GSettingsBackend::changed
 718  * signal will be emitted if any keys have been changed.  The new values of
 719  * all updated keys will be visible to any signal callbacks.
 720  *
 721  * One possible method that an implementation might deal with failures is
 722  * to emit a second "changed" signal (either during this call, or later)
 723  * to indicate that the affected keys have suddenly "changed back" to their
 724  * old values.
 725  */
 726 gboolean
 727 g_settings_backend_write_keys (GSettingsBackend *backend,
 728                                GTree            *tree,
 729                                gpointer          origin_tag)
 730 {
 731   return G_SETTINGS_BACKEND_GET_CLASS (backend)
 732     ->write_keys (backend, tree, origin_tag);
 733 }
 734
 735 /*< private >
 736  * g_settings_backend_reset:
 737  * @backend: a #GSettingsBackend implementation
 738  * @key: the name of a key
 739  * @origin_tag: the origin tag
 740  *
 741  * "Resets" the named key to its "default" value (ie: after system-wide
 742  * defaults, mandatory keys, etc. have been taken into account) or possibly
 743  * unsets it.
 744  */
 745 void
 746 g_settings_backend_reset (GSettingsBackend *backend,
 747                           const gchar      *key,
 748                           gpointer          origin_tag)
 749 {
 750   G_SETTINGS_BACKEND_GET_CLASS (backend)
 751     ->reset (backend, key, origin_tag);
 752 }
 753
 754 /*< private >
 755  * g_settings_backend_reset_path:
 756  * @backend: a #GSettingsBackend implementation
 757  * @name: the name of a key or path
 758  * @origin_tag: the origin tag
 759  *
 760  * "Resets" the named path.  This means that every key under the path is
 761  * reset.
 762  */
 763 void
 764 g_settings_backend_reset_path (GSettingsBackend *backend,
 765                                const gchar      *path,
 766                                gpointer          origin_tag)
 767 {
 768   G_SETTINGS_BACKEND_GET_CLASS (backend)
 769     ->reset_path (backend, path, origin_tag);
 770 }
 771
 772 /*< private >
 773  * g_settings_backend_get_writable:
 774  * @backend: a #GSettingsBackend implementation
 775  * @key: the name of a key
 776  * @returns: %TRUE if the key is writable
 777  *
 778  * Finds out if a key is available for writing to.  This is the
 779  * interface through which 'lockdown' is implemented.  Locked down
 780  * keys will have %FALSE returned by this call.
 781  *
 782  * You should not write to locked-down keys, but if you do, the
 783  * implementation will deal with it.
 784  */
 785 gboolean
 786 g_settings_backend_get_writable (GSettingsBackend *backend,
 787                                  const gchar      *key)
 788 {
 789   return G_SETTINGS_BACKEND_GET_CLASS (backend)
 790     ->get_writable (backend, key);
 791 }
 792
 793 /*< private >
 794  * g_settings_backend_unsubscribe:
 795  * @backend: a #GSettingsBackend
 796  * @name: a key or path to subscribe to
 797  *
 798  * Reverses the effect of a previous call to
 799  * g_settings_backend_subscribe().
 800  */
 801 void
 802 g_settings_backend_unsubscribe (GSettingsBackend *backend,
 803                                 const char       *name)
 804 {
 805   G_SETTINGS_BACKEND_GET_CLASS (backend)
 806     ->unsubscribe (backend, name);
 807 }
 808
 809 /*< private >
 810  * g_settings_backend_subscribe:
 811  * @backend: a #GSettingsBackend
 812  * @name: a key or path to subscribe to
 813  *
 814  * Requests that change signals be emitted for events on @name.
 815  */
 816 void
 817 g_settings_backend_subscribe (GSettingsBackend *backend,
 818                               const gchar      *name)
 819 {
 820   G_SETTINGS_BACKEND_GET_CLASS (backend)
 821     ->subscribe (backend, name);
 822 }
 823
 824 static void
 825 g_settings_backend_set_property (GObject         *object,
 826                                  guint            prop_id,
 827                                  const GValue    *value,
 828                                  GParamSpec      *pspec)
 829 {
 830   GSettingsBackend *backend = G_SETTINGS_BACKEND (object);
 831
 832   switch (prop_id)
 833     {
 834     case PROP_CONTEXT:
 835       backend->priv->context = g_value_dup_string (value);
 836       break;
 837
 838     default:
 839       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 840       break;
 841     }
 842 }
 843
 844 static void
 845 g_settings_backend_get_property (GObject    *object,
 846                                  guint       prop_id,
 847                                  GValue     *value,
 848                                  GParamSpec *pspec)
 849 {
 850   GSettingsBackend *backend = G_SETTINGS_BACKEND (object);
 851
 852   switch (prop_id)
 853     {
 854     case PROP_CONTEXT:
 855       g_value_set_string (value, backend->priv->context);
 856       break;
 857
 858     default:
 859       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 860       break;
 861     }
 862 }
 863
 864 static void
 865 g_settings_backend_finalize (GObject *object)
 866 {
 867   GSettingsBackend *backend = G_SETTINGS_BACKEND (object);
 868
 869   g_free (backend->priv->context);
 870
 871   G_OBJECT_CLASS (g_settings_backend_parent_class)->finalize (object);
 872 }
 873
 874 static void
 875 ignore_subscription (GSettingsBackend *backend,
 876                      const gchar      *key)
 877 {
 878 }
 879
 880 static void
 881 g_settings_backend_init (GSettingsBackend *backend)
 882 {
 883   backend->priv = G_TYPE_INSTANCE_GET_PRIVATE (backend,
 884                                                G_TYPE_SETTINGS_BACKEND,
 885                                                GSettingsBackendPrivate);
 886 }
 887
 888 static void
 889 g_settings_backend_class_init (GSettingsBackendClass *class)
 890 {
 891   GObjectClass *gobject_class = G_OBJECT_CLASS (class);
 892
 893   class->subscribe = ignore_subscription;
 894   class->unsubscribe = ignore_subscription;
 895
 896   gobject_class->get_property = g_settings_backend_get_property;
 897   gobject_class->set_property = g_settings_backend_set_property;
 898   gobject_class->finalize = g_settings_backend_finalize;
 899
 900   g_type_class_add_private (class, sizeof (GSettingsBackendPrivate));
 901
 902   /**
 903    * GSettingsBackend:context:
 904    *
 905    * The "context" property gives a hint to the backend as to
 906    * what storage to use. It is up to the implementation to make
 907    * use of this information.
 908    *
 909    * E.g. DConf supports "user", "system", "defaults" and "login"
 910    * contexts.
 911    *
 912    * If your backend supports different contexts, you should also
 913    * provide an implementation of the supports_context() class
 914    * function in #GSettingsBackendClass.
 915    */
 916   g_object_class_install_property (gobject_class, PROP_CONTEXT,
 917     g_param_spec_string ("context", P_("Context"),
 918                          P_("An identifier to decide which storage to use"),
 919                          "", G_PARAM_READWRITE |
 920                          G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 921
 922 }
 923
 924 /*< private >
 925  * g_settings_backend_create_tree:
 926  * @returns: a new #GTree
 927  *
 928  * This is a convenience function for creating a tree that is compatible
 929  * with g_settings_backend_write().  It merely calls g_tree_new_full()
 930  * with strcmp(), g_free() and g_variant_unref().
 931  */
 932 GTree *
 933 g_settings_backend_create_tree (void)
 934 {
 935   return g_tree_new_full ((GCompareDataFunc) strcmp, NULL,
 936                           g_free, (GDestroyNotify) g_variant_unref);
 937 }
 938
 939
 940 static gpointer
 941 get_default_backend (const gchar *context)
 942 {
 943   GIOExtension *extension = NULL;
 944   GIOExtensionPoint *point;
 945   GList *extensions;
 946   const gchar *env;
 947   GType type;
 948
 949   _g_io_modules_ensure_loaded ();
 950
 951   point = g_io_extension_point_lookup (G_SETTINGS_BACKEND_EXTENSION_POINT_NAME);
 952
 953   if ((env = getenv ("GSETTINGS_BACKEND")))
 954     {
 955       extension = g_io_extension_point_get_extension_by_name (point, env);
 956
 957       if (extension == NULL)
 958         g_warning ("Can't find GSettings backend '%s' given in "
 959                    "GSETTINGS_BACKEND environment variable", env);
 960     }
 961
 962   if (extension == NULL)
 963     {
 964       extensions = g_io_extension_point_get_extensions (point);
 965
 966       if (extensions == NULL)
 967         g_error ("No GSettingsBackend implementations exist.");
 968
 969       extension = extensions->data;
 970     }
 971
 972   if (context[0] != '\0') /* (context != "") */
 973     {
 974       GSettingsBackendClass *backend_class;
 975       GTypeClass *class;
 976
 977       class = g_io_extension_ref_class (extension);
 978       backend_class = G_SETTINGS_BACKEND_CLASS (class);
 979
 980       if (backend_class->supports_context == NULL ||
 981           !backend_class->supports_context (context))
 982         {
 983           g_type_class_unref (class);
 984           return NULL;
 985         }
 986
 987       g_type_class_unref (class);
 988     }
 989
 990   type = g_io_extension_get_type (extension);
 991
 992   return g_object_new (type, "context", context, NULL);
 993 }
 994
 995 static GHashTable *g_settings_backends;
 996
 997 /*< private >
 998  * g_settings_backend_get_with_context:
 999  * @context: a context that might be used by the backend to determine
1000  *     which storage to use, or %NULL to use the default storage
1001  * @returns: the default #GSettingsBackend
1002  *
1003  * Returns the default #GSettingsBackend. It is possible to override
1004  * the default by setting the <envar>GSETTINGS_BACKEND</envar>
1005  * environment variable to the name of a settings backend.
1006  *
1007  * The @context parameter can be used to indicate that a different
1008  * than the default storage is desired. E.g. the DConf backend lets
1009  * you use "user", "system", "defaults" and "login" as contexts.
1010  *
1011  * If @context is not supported by the implementation, this function
1012  * returns an instance of the #GSettingsMemoryBackend.
1013  * See g_settings_backend_supports_context(),
1014  *
1015  * The user does not own the return value and it must not be freed.
1016  */
1017 GSettingsBackend *
1018 g_settings_backend_get_with_context (const gchar *context)
1019 {
1020   GSettingsBackend *backend;
1021
1022   g_return_val_if_fail (context != NULL, NULL);
1023
1024   _g_io_modules_ensure_extension_points_registered ();
1025
1026   if (g_settings_backends == NULL)
1027     g_settings_backends = g_hash_table_new (g_str_hash, g_str_equal);
1028
1029   backend = g_hash_table_lookup (g_settings_backends, context);
1030
1031   if (!backend)
1032     {
1033       backend = get_default_backend (context);
1034
1035       if (!backend)
1036         backend = g_null_settings_backend_new ();
1037
1038       g_hash_table_insert (g_settings_backends, g_strdup (context), backend);
1039     }
1040
1041   return g_object_ref (backend);
1042 }
1043
1044 /*< private >
1045  * g_settings_backend_supports_context:
1046  * @context: a context string that might be passed to
1047  *     g_settings_backend_new_with_context()
1048  * @returns: #TRUE if @context is supported
1049  *
1050  * Determines if the given context is supported by the default
1051  * GSettingsBackend implementation.
1052  */
1053 gboolean
1054 g_settings_backend_supports_context (const gchar *context)
1055 {
1056   GSettingsBackend *backend;
1057
1058   g_return_val_if_fail (context != NULL, FALSE);
1059
1060   backend = get_default_backend (context);
1061
1062   if (backend)
1063     {
1064       g_object_unref (backend);
1065       return TRUE;
1066     }
1067
1068   return FALSE;
1069 }
1070
1071 /**
1072  * g_settings_backend_setup:
1073  * @context: a context string (not %NULL or "")
1074  * @backend: a #GSettingsBackend
1075  *
1076  * Sets up @backend for use with #GSettings.
1077  *
1078  * If you create a #GSettings with its context property set to @context
1079  * then it will use the backend given to this function.  See
1080  * g_settings_new_with_context().
1081  *
1082  * The backend must be set up before any settings objects are created
1083  * for the named context.
1084  *
1085  * It is not possible to specify a backend for the default context.
1086  *
1087  * This function takes a reference on @backend and never releases it.
1088  *
1089  * Since: 2.26
1090  **/
1091 void
1092 g_settings_backend_setup (const gchar      *context,
1093                           GSettingsBackend *backend)
1094 {
1095   g_return_if_fail (context[0] != '\0');
1096   g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
1097
1098   if (g_settings_backends == NULL)
1099     g_settings_backends = g_hash_table_new (g_str_hash, g_str_equal);
1100
1101   if (g_hash_table_lookup (g_settings_backends, context))
1102     g_error ("A GSettingsBackend already exists for context '%s'", context);
1103
1104   g_hash_table_insert (g_settings_backends,
1105                        g_strdup (context),
1106                        g_object_ref (backend));
1107 }
1108
1109 #define __G_SETTINGS_BACKEND_C__
1110 #include "gioaliasdef.c"