gsettingsbackend.c 32.8 KB
Newer Older
1 2 3 4 5 6 7
/*
 * Copyright © 2009, 2010 Codethink Limited
 * Copyright © 2010 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
8
 * version 2.1 of the License, or (at your option) any later version.
9 10 11 12 13 14 15
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
16
 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
17 18 19 20 21 22 23 24
 *
 * Authors: Ryan Lortie <desrt@desrt.ca>
 *          Matthias Clasen <mclasen@redhat.com>
 */

#include "config.h"

#include "gsettingsbackendinternal.h"
25
#include "gsimplepermission.h"
26 27 28 29 30 31 32 33
#include "giomodule-priv.h"

#include <string.h>
#include <stdlib.h>
#include <glib.h>
#include <glibintl.h>


34 35
typedef struct _GSettingsBackendClosure GSettingsBackendClosure;
typedef struct _GSettingsBackendWatch   GSettingsBackendWatch;
36 37 38 39

struct _GSettingsBackendPrivate
{
  GSettingsBackendWatch *watches;
40
  GMutex lock;
41 42
};

43 44
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GSettingsBackend, g_settings_backend, G_TYPE_OBJECT)

45 46 47 48 49 50 51
/* For g_settings_backend_sync_default(), we only want to actually do
 * the sync if the backend already exists.  This avoids us creating an
 * entire GSettingsBackend in order to call a do-nothing sync()
 * operation on it.  This variable lets us avoid that.
 */
static gboolean g_settings_has_backend;

52 53 54
/**
 * SECTION:gsettingsbackend
 * @title: GSettingsBackend
Matthias Clasen's avatar
Matthias Clasen committed
55
 * @short_description: Interface for settings backend implementations
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
 * @include: gio/gsettingsbackend.h
 * @see_also: #GSettings, #GIOExtensionPoint
 *
 * The #GSettingsBackend interface defines a generic interface for
 * non-strictly-typed data that is stored in a hierarchy. To implement
 * an alternative storage backend for #GSettings, you need to implement
 * the #GSettingsBackend interface and then make it implement the
 * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
 *
 * The interface defines methods for reading and writing values, a
 * method for determining if writing of certain values will fail
 * (lockdown) and a change notification mechanism.
 *
 * The semantics of the interface are very precisely defined and
 * implementations must carefully adhere to the expectations of
 * callers that are documented on each of the interface methods.
 *
73
 * Some of the #GSettingsBackend functions accept or return a #GTree.
74 75 76 77
 * These trees always have strings as keys and #GVariant as values.
 * g_settings_backend_create_tree() is a convenience function to create
 * suitable trees.
 *
78
 * The #GSettingsBackend API is exported to allow third-party
79 80
 * implementations, but does not carry the same stability guarantees
 * as the public GIO API. For this reason, you have to define the
81
 * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
82
 * `gio/gsettingsbackend.h`.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
 **/

static gboolean
is_key (const gchar *key)
{
  gint length;
  gint i;

  g_return_val_if_fail (key != NULL, FALSE);
  g_return_val_if_fail (key[0] == '/', FALSE);

  for (i = 1; key[i]; i++)
    g_return_val_if_fail (key[i] != '/' || key[i + 1] != '/', FALSE);

  length = i;

  g_return_val_if_fail (key[length - 1] != '/', FALSE);

  return TRUE;
}

static gboolean
is_path (const gchar *path)
{
  gint length;
  gint i;

  g_return_val_if_fail (path != NULL, FALSE);
  g_return_val_if_fail (path[0] == '/', FALSE);

  for (i = 1; path[i]; i++)
    g_return_val_if_fail (path[i] != '/' || path[i + 1] != '/', FALSE);

  length = i;

  g_return_val_if_fail (path[length - 1] == '/', FALSE);

  return TRUE;
}

123 124
struct _GSettingsBackendWatch
{
125 126 127 128
  GObject                       *target;
  const GSettingsListenerVTable *vtable;
  GMainContext                  *context;
  GSettingsBackendWatch         *next;
129 130 131
};

struct _GSettingsBackendClosure
132
{
133 134 135 136 137 138
  void (*function) (GObject           *target,
                    GSettingsBackend  *backend,
                    const gchar       *name,
                    gpointer           origin_tag,
                    gchar            **names);

139
  GMainContext      *context;
140
  GWeakRef          *target_ref;
141 142 143 144
  GSettingsBackend  *backend;
  gchar             *name;
  gpointer           origin_tag;
  gchar            **names;
145
};
146

147 148
static void
g_settings_backend_watch_weak_notify (gpointer  data,
149
                                      GObject  *where_the_object_was)
150 151 152
{
  GSettingsBackend *backend = data;
  GSettingsBackendWatch **ptr;
153

154
  /* search and remove */
155
  g_mutex_lock (&backend->priv->lock);
156
  for (ptr = &backend->priv->watches; *ptr; ptr = &(*ptr)->next)
157
    if ((*ptr)->target == where_the_object_was)
158 159 160 161 162 163
      {
        GSettingsBackendWatch *tmp = *ptr;

        *ptr = tmp->next;
        g_slice_free (GSettingsBackendWatch, tmp);

164
        g_mutex_unlock (&backend->priv->lock);
165 166 167 168 169 170 171 172 173 174 175
        return;
      }

  /* we didn't find it.  that shouldn't happen. */
  g_assert_not_reached ();
}

/*< private >
 * g_settings_backend_watch:
 * @backend: a #GSettingsBackend
 * @target: the GObject (typically GSettings instance) to call back to
176
 * @context: (nullable): a #GMainContext, or %NULL
177 178 179 180 181 182 183 184 185 186 187 188
 * ...: callbacks...
 *
 * Registers a new watch on a #GSettingsBackend.
 *
 * note: %NULL @context does not mean "default main context" but rather,
 * "it is okay to dispatch in any context".  If the default main context
 * is specifically desired then it must be given.
 *
 * note also: if you want to get meaningful values for the @origin_tag
 * that appears as an argument to some of the callbacks, you *must* have
 * @context as %NULL.  Otherwise, you are subject to cross-thread
 * dispatching and whatever owned @origin_tag at the time that the event
Matthias Clasen's avatar
Matthias Clasen committed
189
 * occurred may no longer own it.  This is a problem if you consider that
190 191 192 193 194 195 196
 * you may now be the new owner of that address and mistakenly think
 * that the event in question originated from yourself.
 *
 * tl;dr: If you give a non-%NULL @context then you must ignore the
 * value of @origin_tag given to any callbacks.
 **/
void
197 198 199 200
g_settings_backend_watch (GSettingsBackend              *backend,
                          const GSettingsListenerVTable *vtable,
                          GObject                       *target,
                          GMainContext                  *context)
201 202 203 204 205 206 207 208 209 210
{
  GSettingsBackendWatch *watch;

  /* For purposes of discussion, we assume that our target is a
   * GSettings instance.
   *
   * Our strategy to defend against the final reference dropping on the
   * GSettings object in a thread other than the one that is doing the
   * dispatching is as follows:
   *
211 212 213
   *  1) hold a thread-safe GWeakRef on the GSettings during an outstanding
   *     dispatch.  This ensures that the delivery is always possible while
   *     the GSettings object is alive.
214 215 216 217 218 219 220 221 222 223 224 225 226 227
   *
   *  2) hold a weak reference on the GSettings at other times.  This
   *     allows us to receive early notification of pending destruction
   *     of the object.  At this point, it is still safe to obtain a
   *     reference on the GObject to keep it alive, so #1 will work up
   *     to that point.  After that point, we'll have been able to drop
   *     the watch from the list.
   *
   * Note, in particular, that it's not possible to simply have an
   * "unwatch" function that gets called from the finalize function of
   * the GSettings instance because, by that point it is no longer
   * possible to keep the object alive using g_object_ref() and we would
   * have no way of knowing this.
   *
228 229
   * Note also that we need to hold a reference on the main context here
   * since the GSettings instance may be finalized before the closure runs.
230 231 232 233
   *
   * All access to the list holds a mutex.  We have some strategies to
   * avoid some of the pain that would be associated with that.
   */
234

235 236
  watch = g_slice_new (GSettingsBackendWatch);
  watch->context = context;
237
  watch->vtable = vtable;
238 239 240 241
  watch->target = target;
  g_object_weak_ref (target, g_settings_backend_watch_weak_notify, backend);

  /* linked list prepend */
242
  g_mutex_lock (&backend->priv->lock);
243 244
  watch->next = backend->priv->watches;
  backend->priv->watches = watch;
245
  g_mutex_unlock (&backend->priv->lock);
246 247 248 249 250 251 252 253 254 255 256 257
}

void
g_settings_backend_unwatch (GSettingsBackend *backend,
                            GObject          *target)
{
  /* Our caller surely owns a reference on 'target', so the order of
   * these two calls is unimportant.
   */
  g_object_weak_unref (target, g_settings_backend_watch_weak_notify, backend);
  g_settings_backend_watch_weak_notify (backend, target);
}
258 259 260 261 262

static gboolean
g_settings_backend_invoke_closure (gpointer user_data)
{
  GSettingsBackendClosure *closure = user_data;
263
  GObject *target = g_weak_ref_get (closure->target_ref);
264

265 266 267 268 269 270
  if (target)
    {
      closure->function (target, closure->backend, closure->name,
                         closure->origin_tag, closure->names);
      g_object_unref (target);
    }
271

272 273
  if (closure->context)
    g_main_context_unref (closure->context);
274
  g_object_unref (closure->backend);
275 276
  g_weak_ref_clear (closure->target_ref);
  g_free (closure->target_ref);
277
  g_strfreev (closure->names);
278 279 280 281 282 283 284
  g_free (closure->name);

  g_slice_free (GSettingsBackendClosure, closure);

  return FALSE;
}

285
static void
286 287 288 289 290
g_settings_backend_dispatch_signal (GSettingsBackend    *backend,
                                    gsize                function_offset,
                                    const gchar         *name,
                                    gpointer             origin_tag,
                                    const gchar * const *names)
291
{
292 293
  GSettingsBackendWatch *watch;
  GSList *closures = NULL;
294

295 296 297 298
  /* We're in a little bit of a tricky situation here.  We need to hold
   * a lock while traversing the list, but we don't want to hold the
   * lock while calling back into user code.
   *
299 300 301
   * We work around this by creating a bunch of GSettingsBackendClosure
   * objects while holding the lock and dispatching them after.  We
   * never touch the list without holding the lock.
302
   */
303
  g_mutex_lock (&backend->priv->lock);
304
  for (watch = backend->priv->watches; watch; watch = watch->next)
305 306 307 308
    {
      GSettingsBackendClosure *closure;

      closure = g_slice_new (GSettingsBackendClosure);
309
      closure->context = watch->context;
310 311
      if (closure->context)
        g_main_context_ref (closure->context);
312
      closure->backend = g_object_ref (backend);
313 314
      closure->target_ref = g_new (GWeakRef, 1);
      g_weak_ref_init (closure->target_ref, watch->target);
315 316
      closure->function = G_STRUCT_MEMBER (void *, watch->vtable,
                                           function_offset);
317
      closure->name = g_strdup (name);
318 319
      closure->origin_tag = origin_tag;
      closure->names = g_strdupv ((gchar **) names);
320

321 322 323 324 325 326 327
      closures = g_slist_prepend (closures, closure);
    }
  g_mutex_unlock (&backend->priv->lock);

  while (closures)
    {
      GSettingsBackendClosure *closure = closures->data;
328

329 330
      if (closure->context)
        g_main_context_invoke (closure->context,
331 332
                               g_settings_backend_invoke_closure,
                               closure);
333
      else
334
        g_settings_backend_invoke_closure (closure);
335 336

      closures = g_slist_delete_link (closures, closures);
337
    }
338 339
}

340 341 342 343 344 345 346 347 348 349
/**
 * g_settings_backend_changed:
 * @backend: a #GSettingsBackend implementation
 * @key: the name of the key
 * @origin_tag: the origin tag
 *
 * Signals that a single key has possibly changed.  Backend
 * implementations should call this if a key has possibly changed its
 * value.
 *
350
 * @key must be a valid key (ie starting with a slash, not containing
351 352 353 354 355 356 357 358 359
 * '//', and not ending with a slash).
 *
 * The implementation must call this function during any call to
 * g_settings_backend_write(), before the call returns (except in the
 * case that no keys are actually changed and it cares to detect this
 * fact).  It may not rely on the existence of a mainloop for
 * dispatching the signal later.
 *
 * The implementation may call this function at any other time it likes
Matthias Clasen's avatar
Matthias Clasen committed
360
 * in response to other events (such as changes occurring outside of the
361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378
 * program).  These calls may originate from a mainloop or may originate
 * in response to any other action (including from calls to
 * g_settings_backend_write()).
 *
 * In the case that this call is in response to a call to
 * g_settings_backend_write() then @origin_tag must be set to the same
 * value that was passed to that call.
 *
 * Since: 2.26
 **/
void
g_settings_backend_changed (GSettingsBackend *backend,
                            const gchar      *key,
                            gpointer          origin_tag)
{
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
  g_return_if_fail (is_key (key));

379
  g_settings_backend_dispatch_signal (backend,
380
                                      G_STRUCT_OFFSET (GSettingsListenerVTable,
381
                                                       changed),
382
                                      key, origin_tag, NULL);
383 384 385 386 387 388
}

/**
 * g_settings_backend_keys_changed:
 * @backend: a #GSettingsBackend implementation
 * @path: the path containing the changes
389
 * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
390 391 392 393 394 395
 * @origin_tag: the origin tag
 *
 * Signals that a list of keys have possibly changed.  Backend
 * implementations should call this if keys have possibly changed their
 * values.
 *
396
 * @path must be a valid path (ie starting and ending with a slash and
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
 * not containing '//').  Each string in @items must form a valid key
 * name when @path is prefixed to it (ie: each item must not start or
 * end with '/' and must not contain '//').
 *
 * The meaning of this signal is that any of the key names resulting
 * from the contatenation of @path with each item in @items may have
 * changed.
 *
 * The same rules for when notifications must occur apply as per
 * g_settings_backend_changed().  These two calls can be used
 * interchangeably if exactly one item has changed (although in that
 * case g_settings_backend_changed() is definitely preferred).
 *
 * For efficiency reasons, the implementation should strive for @path to
 * be as long as possible (ie: the longest common prefix of all of the
 * keys that were changed) but this is not strictly required.
 *
 * Since: 2.26
 */
void
g_settings_backend_keys_changed (GSettingsBackend    *backend,
                                 const gchar         *path,
                                 gchar const * const *items,
                                 gpointer             origin_tag)
{
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
423 424 425
  g_return_if_fail (is_path (path));

  /* XXX: should do stricter checking (ie: inspect each item) */
426 427
  g_return_if_fail (items != NULL);

428
  g_settings_backend_dispatch_signal (backend,
429
                                      G_STRUCT_OFFSET (GSettingsListenerVTable,
430
                                                       keys_changed),
431
                                      path, origin_tag, items);
432 433 434
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
435
 * g_settings_backend_path_changed:
436 437 438 439 440 441 442 443
 * @backend: a #GSettingsBackend implementation
 * @path: the path containing the changes
 * @origin_tag: the origin tag
 *
 * Signals that all keys below a given path may have possibly changed.
 * Backend implementations should call this if an entire path of keys
 * have possibly changed their values.
 *
444
 * @path must be a valid path (ie starting and ending with a slash and
445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471
 * not containing '//').
 *
 * The meaning of this signal is that any of the key which has a name
 * starting with @path may have changed.
 *
 * The same rules for when notifications must occur apply as per
 * g_settings_backend_changed().  This call might be an appropriate
 * reasponse to a 'reset' call but implementations are also free to
 * explicitly list the keys that were affected by that call if they can
 * easily do so.
 *
 * For efficiency reasons, the implementation should strive for @path to
 * be as long as possible (ie: the longest common prefix of all of the
 * keys that were changed) but this is not strictly required.  As an
 * example, if this function is called with the path of "/" then every
 * single key in the application will be notified of a possible change.
 *
 * Since: 2.26
 */
void
g_settings_backend_path_changed (GSettingsBackend *backend,
                                 const gchar      *path,
                                 gpointer          origin_tag)
{
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
  g_return_if_fail (is_path (path));

472
  g_settings_backend_dispatch_signal (backend,
473
                                      G_STRUCT_OFFSET (GSettingsListenerVTable,
474
                                                       path_changed),
475
                                      path, origin_tag, NULL);
476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496
}

/**
 * g_settings_backend_writable_changed:
 * @backend: a #GSettingsBackend implementation
 * @key: the name of the key
 *
 * Signals that the writability of a single key has possibly changed.
 *
 * Since GSettings performs no locking operations for itself, this call
 * will always be made in response to external events.
 *
 * Since: 2.26
 **/
void
g_settings_backend_writable_changed (GSettingsBackend *backend,
                                     const gchar      *key)
{
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
  g_return_if_fail (is_key (key));

497
  g_settings_backend_dispatch_signal (backend,
498
                                      G_STRUCT_OFFSET (GSettingsListenerVTable,
499
                                                       writable_changed),
500
                                      key, NULL, NULL);
501 502 503
}

/**
Matthias Clasen's avatar
Matthias Clasen committed
504
 * g_settings_backend_path_writable_changed:
505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522
 * @backend: a #GSettingsBackend implementation
 * @path: the name of the path
 *
 * Signals that the writability of all keys below a given path may have
 * changed.
 *
 * Since GSettings performs no locking operations for itself, this call
 * will always be made in response to external events.
 *
 * Since: 2.26
 **/
void
g_settings_backend_path_writable_changed (GSettingsBackend *backend,
                                          const gchar      *path)
{
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));
  g_return_if_fail (is_path (path));

523
  g_settings_backend_dispatch_signal (backend,
524
                                      G_STRUCT_OFFSET (GSettingsListenerVTable,
525
                                                       path_writable_changed),
526
                                      path, NULL, NULL);
527 528 529 530
}

typedef struct
{
531 532
  const gchar **keys;
  GVariant **values;
533 534
  gint prefix_len;
  gchar *prefix;
535
} FlattenState;
536 537

static gboolean
538 539 540
g_settings_backend_flatten_one (gpointer key,
                                gpointer value,
                                gpointer user_data)
541
{
542
  FlattenState *state = user_data;
543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582
  const gchar *skey = key;
  gint i;

  g_return_val_if_fail (is_key (key), TRUE);

  /* calculate longest common prefix */
  if (state->prefix == NULL)
    {
      gchar *last_byte;

      /* first key?  just take the prefix up to the last '/' */
      state->prefix = g_strdup (skey);
      last_byte = strrchr (state->prefix, '/') + 1;
      state->prefix_len = last_byte - state->prefix;
      *last_byte = '\0';
    }
  else
    {
      /* find the first character that does not match.  we will
       * definitely find one because the prefix ends in '/' and the key
       * does not.  also: no two keys in the tree are the same.
       */
      for (i = 0; state->prefix[i] == skey[i]; i++);

      /* check if we need to shorten the prefix */
      if (state->prefix[i] != '\0')
        {
          /* find the nearest '/', terminate after it */
          while (state->prefix[i - 1] != '/')
            i--;

          state->prefix[i] = '\0';
          state->prefix_len = i;
        }
    }


  /* save the entire item into the array.
   * the prefixes will be removed later.
   */
583 584 585 586
  *state->keys++ = key;

  if (state->values)
    *state->values++ = value;
587 588 589 590

  return FALSE;
}

591 592 593
/**
 * g_settings_backend_flatten_tree:
 * @tree: a #GTree containing the changes
594 595 596
 * @path: (out): the location to save the path
 * @keys: (out) (transfer container) (array zero-terminated=1): the
 *        location to save the relative keys
597
 * @values: (out) (optional) (transfer container) (array zero-terminated=1):
598
 *          the location to save the values, or %NULL
599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633
 *
 * Calculate the longest common prefix of all keys in a tree and write
 * out an array of the key names relative to that prefix and,
 * optionally, the value to store at each of those keys.
 *
 * You must free the value returned in @path, @keys and @values using
 * g_free().  You should not attempt to free or unref the contents of
 * @keys or @values.
 *
 * Since: 2.26
 **/
void
g_settings_backend_flatten_tree (GTree         *tree,
                                 gchar        **path,
                                 const gchar ***keys,
                                 GVariant    ***values)
{
  FlattenState state = { 0, };
  gsize nnodes;

  nnodes = g_tree_nnodes (tree);

  *keys = state.keys = g_new (const gchar *, nnodes + 1);
  state.keys[nnodes] = NULL;

  if (values != NULL)
    {
      *values = state.values = g_new (GVariant *, nnodes + 1);
      state.values[nnodes] = NULL;
    }

  g_tree_foreach (tree, g_settings_backend_flatten_one, &state);
  g_return_if_fail (*keys + nnodes == state.keys);

  *path = state.prefix;
634 635
  while (nnodes--)
    *--state.keys += state.prefix_len;
636 637
}

638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654
/**
 * g_settings_backend_changed_tree:
 * @backend: a #GSettingsBackend implementation
 * @tree: a #GTree containing the changes
 * @origin_tag: the origin tag
 *
 * This call is a convenience wrapper.  It gets the list of changes from
 * @tree, computes the longest common prefix and calls
 * g_settings_backend_changed().
 *
 * Since: 2.26
 **/
void
g_settings_backend_changed_tree (GSettingsBackend *backend,
                                 GTree            *tree,
                                 gpointer          origin_tag)
{
655 656
  const gchar **keys;
  gchar *path;
657

658 659
  g_return_if_fail (G_IS_SETTINGS_BACKEND (backend));

660
  g_settings_backend_flatten_tree (tree, &path, &keys, NULL);
661

662 663 664 665 666 667 668 669 670 671 672 673
#ifdef DEBUG_CHANGES
  {
    gint i;

    g_print ("----\n");
    g_print ("changed_tree(): prefix %s\n", path);
    for (i = 0; keys[i]; i++)
      g_print ("  %s\n", keys[i]);
    g_print ("----\n");
  }
#endif

674
  g_settings_backend_keys_changed (backend, path, keys, origin_tag);
675 676
  g_free (path);
  g_free (keys);
677 678 679 680 681 682
}

/*< private >
 * g_settings_backend_read:
 * @backend: a #GSettingsBackend implementation
 * @key: the key to read
683 684
 * @expected_type: a #GVariantType
 * @default_value: if the default value should be returned
685 686 687 688 689 690
 *
 * Reads a key. This call will never block.
 *
 * If the key exists, the value associated with it will be returned.
 * If the key does not exist, %NULL will be returned.
 *
691 692 693 694 695 696 697
 * The returned value will be of the type given in @expected_type.  If
 * the backend stored a value of a different type then %NULL will be
 * returned.
 *
 * If @default_value is %TRUE then this gets the default value from the
 * backend (ie: the one that the backend would contain if
 * g_settings_reset() were called).
698 699
 *
 * Returns: the value that was read, or %NULL
700 701 702 703
 */
GVariant *
g_settings_backend_read (GSettingsBackend   *backend,
                         const gchar        *key,
704 705
                         const GVariantType *expected_type,
                         gboolean            default_value)
706
{
707 708 709
  GVariant *value;

  value = G_SETTINGS_BACKEND_GET_CLASS (backend)
710
    ->read (backend, key, expected_type, default_value);
711

712 713 714
  if (value != NULL)
    value = g_variant_take_ref (value);

715 716 717 718 719 720 721
  if G_UNLIKELY (value && !g_variant_is_of_type (value, expected_type))
    {
      g_variant_unref (value);
      value = NULL;
    }

  return value;
722 723
}

724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760
/*< private >
 * g_settings_backend_read_user_value:
 * @backend: a #GSettingsBackend implementation
 * @key: the key to read
 * @expected_type: a #GVariantType
 *
 * Reads the 'user value' of a key.
 *
 * This is the value of the key that the user has control over and has
 * set for themselves.  Put another way: if the user did not set the
 * value for themselves, then this will return %NULL (even if the
 * sysadmin has provided a default value).
 *
 * Returns: the value that was read, or %NULL
 */
GVariant *
g_settings_backend_read_user_value (GSettingsBackend   *backend,
                                    const gchar        *key,
                                    const GVariantType *expected_type)
{
  GVariant *value;

  value = G_SETTINGS_BACKEND_GET_CLASS (backend)
    ->read_user_value (backend, key, expected_type);

  if (value != NULL)
    value = g_variant_take_ref (value);

  if G_UNLIKELY (value && !g_variant_is_of_type (value, expected_type))
    {
      g_variant_unref (value);
      value = NULL;
    }

  return value;
}

761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778
/*< private >
 * g_settings_backend_write:
 * @backend: a #GSettingsBackend implementation
 * @key: the name of the key
 * @value: a #GVariant value to write to this key
 * @origin_tag: the origin tag
 *
 * Writes exactly one key.
 *
 * This call does not fail.  During this call a
 * #GSettingsBackend::changed signal will be emitted if the value of the
 * key has changed.  The updated key value will be visible to any signal
 * callbacks.
 *
 * One possible method that an implementation might deal with failures is
 * to emit a second "changed" signal (either during this call, or later)
 * to indicate that the affected keys have suddenly "changed back" to their
 * old values.
779 780
 *
 * Returns: %TRUE if the write succeeded, %FALSE if the key was not writable
781
 */
782
gboolean
783 784 785 786 787
g_settings_backend_write (GSettingsBackend *backend,
                          const gchar      *key,
                          GVariant         *value,
                          gpointer          origin_tag)
{
788 789 790 791
  gboolean success;

  g_variant_ref_sink (value);
  success = G_SETTINGS_BACKEND_GET_CLASS (backend)
792
    ->write (backend, key, value, origin_tag);
793 794 795
  g_variant_unref (value);

  return success;
796 797 798
}

/*< private >
Matthias Clasen's avatar
Matthias Clasen committed
799
 * g_settings_backend_write_tree:
800
 * @backend: a #GSettingsBackend implementation
Matthias Clasen's avatar
Matthias Clasen committed
801
 * @tree: a #GTree containing key-value pairs to write
802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820
 * @origin_tag: the origin tag
 *
 * Writes one or more keys.  This call will never block.
 *
 * The key of each item in the tree is the key name to write to and the
 * value is a #GVariant to write.  The proper type of #GTree for this
 * call can be created with g_settings_backend_create_tree().  This call
 * might take a reference to the tree; you must not modified the #GTree
 * after passing it to this call.
 *
 * This call does not fail.  During this call a #GSettingsBackend::changed
 * signal will be emitted if any keys have been changed.  The new values of
 * all updated keys will be visible to any signal callbacks.
 *
 * One possible method that an implementation might deal with failures is
 * to emit a second "changed" signal (either during this call, or later)
 * to indicate that the affected keys have suddenly "changed back" to their
 * old values.
 */
821
gboolean
822
g_settings_backend_write_tree (GSettingsBackend *backend,
823 824 825
                               GTree            *tree,
                               gpointer          origin_tag)
{
826
  return G_SETTINGS_BACKEND_GET_CLASS (backend)
827
    ->write_tree (backend, tree, origin_tag);
828 829 830 831 832
}

/*< private >
 * g_settings_backend_reset:
 * @backend: a #GSettingsBackend implementation
833
 * @key: the name of a key
834 835
 * @origin_tag: the origin tag
 *
836 837 838
 * "Resets" the named key to its "default" value (ie: after system-wide
 * defaults, mandatory keys, etc. have been taken into account) or possibly
 * unsets it.
839 840 841
 */
void
g_settings_backend_reset (GSettingsBackend *backend,
842
                          const gchar      *key,
843 844 845
                          gpointer          origin_tag)
{
  G_SETTINGS_BACKEND_GET_CLASS (backend)
846 847 848
    ->reset (backend, key, origin_tag);
}

849 850 851
/*< private >
 * g_settings_backend_get_writable:
 * @backend: a #GSettingsBackend implementation
852
 * @key: the name of a key
853 854 855 856 857 858 859
 *
 * Finds out if a key is available for writing to.  This is the
 * interface through which 'lockdown' is implemented.  Locked down
 * keys will have %FALSE returned by this call.
 *
 * You should not write to locked-down keys, but if you do, the
 * implementation will deal with it.
860 861
 *
 * Returns: %TRUE if the key is writable
862 863 864
 */
gboolean
g_settings_backend_get_writable (GSettingsBackend *backend,
865
                                 const gchar      *key)
866 867
{
  return G_SETTINGS_BACKEND_GET_CLASS (backend)
868
    ->get_writable (backend, key);
869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906
}

/*< private >
 * g_settings_backend_unsubscribe:
 * @backend: a #GSettingsBackend
 * @name: a key or path to subscribe to
 *
 * Reverses the effect of a previous call to
 * g_settings_backend_subscribe().
 */
void
g_settings_backend_unsubscribe (GSettingsBackend *backend,
                                const char       *name)
{
  G_SETTINGS_BACKEND_GET_CLASS (backend)
    ->unsubscribe (backend, name);
}

/*< private >
 * g_settings_backend_subscribe:
 * @backend: a #GSettingsBackend
 * @name: a key or path to subscribe to
 *
 * Requests that change signals be emitted for events on @name.
 */
void
g_settings_backend_subscribe (GSettingsBackend *backend,
                              const gchar      *name)
{
  G_SETTINGS_BACKEND_GET_CLASS (backend)
    ->subscribe (backend, name);
}

static void
g_settings_backend_finalize (GObject *object)
{
  GSettingsBackend *backend = G_SETTINGS_BACKEND (object);

907
  g_mutex_clear (&backend->priv->lock);
908

909 910
  G_OBJECT_CLASS (g_settings_backend_parent_class)
    ->finalize (object);
911 912 913 914 915 916 917 918
}

static void
ignore_subscription (GSettingsBackend *backend,
                     const gchar      *key)
{
}

919 920 921 922 923 924 925 926
static GVariant *
g_settings_backend_real_read_user_value (GSettingsBackend   *backend,
                                         const gchar        *key,
                                         const GVariantType *expected_type)
{
  return g_settings_backend_read (backend, key, expected_type, FALSE);
}

927 928 929
static void
g_settings_backend_init (GSettingsBackend *backend)
{
930
  backend->priv = g_settings_backend_get_instance_private (backend);
931
  g_mutex_init (&backend->priv->lock);
932 933 934 935 936 937 938 939 940 941
}

static void
g_settings_backend_class_init (GSettingsBackendClass *class)
{
  GObjectClass *gobject_class = G_OBJECT_CLASS (class);

  class->subscribe = ignore_subscription;
  class->unsubscribe = ignore_subscription;

942 943
  class->read_user_value = g_settings_backend_real_read_user_value;

944 945 946
  gobject_class->finalize = g_settings_backend_finalize;
}

947 948 949 950 951 952 953
static void
g_settings_backend_variant_unref0 (gpointer data)
{
  if (data != NULL)
    g_variant_unref (data);
}

954 955 956 957 958 959
/*< private >
 * g_settings_backend_create_tree:
 *
 * This is a convenience function for creating a tree that is compatible
 * with g_settings_backend_write().  It merely calls g_tree_new_full()
 * with strcmp(), g_free() and g_variant_unref().
960 961
 *
 * Returns: a new #GTree
962 963 964 965 966
 */
GTree *
g_settings_backend_create_tree (void)
{
  return g_tree_new_full ((GCompareDataFunc) strcmp, NULL,
967
                          g_free, g_settings_backend_variant_unref0);
968 969
}

970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985
static gboolean
g_settings_backend_verify (gpointer impl)
{
  GSettingsBackend *backend = impl;

  if (strcmp (G_OBJECT_TYPE_NAME (backend), "GMemorySettingsBackend") == 0 &&
      g_strcmp0 (g_getenv ("GSETTINGS_BACKEND"), "memory") != 0)
    {
      g_message ("Using the 'memory' GSettings backend.  Your settings "
		 "will not be saved or shared with other applications.");
    }

  g_settings_has_backend = TRUE;
  return TRUE;
}

986
/**
987
 * g_settings_backend_get_default:
988 989
 *
 * Returns the default #GSettingsBackend. It is possible to override
990 991
 * the default by setting the `GSETTINGS_BACKEND` environment variable
 * to the name of a settings backend.
992
 *
993
 * The user gets a reference to the backend.
994
 *
995 996
 * Returns: (transfer full): the default #GSettingsBackend
 *
997
 * Since: 2.28
998 999
 */
GSettingsBackend *
1000
g_settings_backend_get_default (void)
1001
{
1002
  GSettingsBackend *backend;
1003

1004 1005 1006 1007
  backend = _g_io_module_get_default (G_SETTINGS_BACKEND_EXTENSION_POINT_NAME,
				      "GSETTINGS_BACKEND",
				      g_settings_backend_verify);
  return g_object_ref (backend);
1008 1009
}

1010 1011 1012 1013 1014 1015 1016 1017 1018 1019
/*< private >
 * g_settings_backend_get_permission:
 * @backend: a #GSettingsBackend
 * @path: a path
 *
 * Gets the permission object associated with writing to keys below
 * @path on @backend.
 *
 * If this is not implemented in the backend, then a %TRUE
 * #GSimplePermission is returned.
1020 1021
 *
 * Returns: a non-%NULL #GPermission. Free with g_object_unref()
1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034
 */
GPermission *
g_settings_backend_get_permission (GSettingsBackend *backend,
                                   const gchar      *path)
{
  GSettingsBackendClass *class = G_SETTINGS_BACKEND_GET_CLASS (backend);

  if (class->get_permission)
    return class->get_permission (backend, path);

  return g_simple_permission_new (TRUE);
}

1035
/*< private >
1036
 * g_settings_backend_sync_default:
1037
 *
1038
 * Syncs the default backend.
1039 1040
 */
void
1041
g_settings_backend_sync_default (void)
1042
{
1043 1044 1045 1046
  if (g_settings_has_backend)
    {
      GSettingsBackendClass *class;
      GSettingsBackend *backend;
1047

1048 1049
      backend = g_settings_backend_get_default ();
      class = G_SETTINGS_BACKEND_GET_CLASS (backend);
1050

1051 1052 1053
      if (class->sync)
        class->sync (backend);
    }
1054
}