client: replace _read_default() with _read_full()

This API has never appeared in a released version of dconf (even
unstable).  Replace it with a more generally-useful form.

Update the test cases, dconf commandline tool and vapi accordingly.

5 files changed, 52 insertions, 24 deletions

diff --git a/bin/dconf.vala b/bin/dconf.vala
index 1c054cd..9704d4a 100644
--- a/bin/dconf.vala
+++ b/bin/dconf.vala
@@ -161,11 +161,11 @@ void dconf_help (string[] args) throws Error {
 
 void dconf_read (string?[] args) throws Error {
 	var client = new DConf.Client ();
-	bool read_default = false;
+	var flags = DConf.ReadFlags.NONE;
 	var index = 2;
 
 	if (args[index] == "-d") {
-		read_default = true;
+		flags = DConf.ReadFlags.DEFAULT_VALUE;
 		index++;
 	}
 
@@ -173,13 +173,7 @@ void dconf_read (string?[] args) throws Error {
 
 	DConf.verify_key (key);
 
-	Variant? result;
-
-	if (read_default) {
-		result = client.read_default (key);
-	} else {
-		result = client.read (key);
-	}
+	var result = client.read_full (key, flags, null);
 
 	if (result != null) {
 		print ("%s\n", result.print (true));
diff --git a/client/dconf-client.c b/client/dconf-client.c
index 0742748..f71a263 100644
--- a/client/dconf-client.c
+++ b/client/dconf-client.c
@@ -246,29 +246,52 @@ dconf_client_read (DConfClient *client,
 }
 
 /**
- * dconf_client_read_default:
+ * dconf_client_read_full:
  * @client: a #DConfClient
  * @key: the key to read the default value of
+ * @flags: #DConfReadFlags
+ * @read_through: a #GQueue of #DConfChangeset
  *
- * Reads the current default value of @key.
+ * Reads the current value of @key.
+ *
+ * If @flags contains %DCONF_READ_USER_VALUE then only the user value
+ * will be read.  Locks are ignored, which means that it is possible to
+ * use this API to read "invisible" user values which are hidden by
+ * system locks.
+ *
+ * If @flags contains %DCONF_READ_DEFAULT_VALUE then only non-user
+ * values will be read.  The result will be exactly equivalent to the
+ * value that would be read if the current value of the key were to be
+ * reset.
  *
- * The default value of the key is the value that the key would have if
- * were to be reset.  This is usually %NULL, but it may be something
- * else in the case that the system administrator has defined a default
- * value for a key.
+ * Flags may not contain both %DCONF_READ_USER_VALUE and
+ * %DCONF_READ_DEFAULT_VALUE.
+ *
+ * If @read_through is non-%NULL, %DCONF_READ_DEFAULT_VALUE is not
+ * given then @read_through is checked for the key in question, subject
+ * to the restriction that the key in question is writable.  This
+ * effectively answers the question of "what would happen if these
+ * changes were committed".
  *
  * If there are outstanding "fast" changes in progress they may affect
  * the result of this call.
  *
+ * If @flags is %DCONF_READ_FLAGS_NONE and @read_through is %NULL then
+ * this call is exactly equivalent to dconf_client_read().
+ *
  * Returns: a #GVariant, or %NULL
+ *
+ * Since: 0.26
  */
 GVariant *
-dconf_client_read_default (DConfClient *client,
-                           const gchar *key)
+dconf_client_read_full (DConfClient    *client,
+                        const gchar    *key,
+                        DConfReadFlags  flags,
+                        const GQueue   *read_through)
 {
   g_return_val_if_fail (DCONF_IS_CLIENT (client), NULL);
 
-  return dconf_engine_read (client->engine, DCONF_READ_DEFAULT_VALUE, NULL, key);
+  return dconf_engine_read (client->engine, flags, read_through, key);
 }
 
 /**
diff --git a/client/dconf-client.h b/client/dconf-client.h
index e37c615..7ef709c 100644
--- a/client/dconf-client.h
+++ b/client/dconf-client.h
@@ -22,6 +22,7 @@
 
 #include <gio/gio.h>
 #include "../common/dconf-changeset.h"
+#include "../common/dconf-enums.h"
 
 G_BEGIN_DECLS
 
@@ -33,8 +34,10 @@ DConfClient *           dconf_client_new                                (void);
 GVariant *              dconf_client_read                               (DConfClient          *client,
                                                                          const gchar          *key);
 
-GVariant *              dconf_client_read_default                       (DConfClient          *client,
-                                                                         const gchar          *key);
+GVariant *              dconf_client_read_full                          (DConfClient          *client,
+                                                                         const gchar          *key,
+                                                                         DConfReadFlags        flags,
+                                                                         const GQueue         *read_through);
 
 gchar **                dconf_client_list                               (DConfClient          *client,
                                                                          const gchar          *dir,
diff --git a/client/dconf.vapi b/client/dconf.vapi
index 6fb34da..62c2e65 100644
--- a/client/dconf.vapi
+++ b/client/dconf.vapi
@@ -1,13 +1,21 @@
 /* dconf.vapi generated by valac 0.17.1.35-814b, do not modify. */
 
 namespace DConf {
+	[CCode (cheader_filename = "dconf.h", cprefix="DCONF_READ_")]
+	public enum ReadFlags {
+		[CCode (cname="DCONF_READ_FLAGS_NONE")]
+		NONE,
+		DEFAULT_VALUE,
+		USER_VALUE
+	}
+
 	[CCode (cheader_filename = "dconf.h")]
 	public class Client : GLib.Object {
 		public signal void changed (string prefix, [CCode (array_length = false, array_null_terminated = true)] string[] changes, string? tag);
 
 		public Client ();
 		public GLib.Variant? read (string key);
-		public GLib.Variant? read_default (string key);
+		public GLib.Variant? read_full (string key, ReadFlags flags, GLib.Queue<Changeset>? read_through);
 		public string[] list (string dir);
 		public string[] list_locks (string dir);
 		public bool is_writable (string key);
diff --git a/tests/client.c b/tests/client.c
index 4a3505c..175fd9e 100644
--- a/tests/client.c
+++ b/tests/client.c
@@ -68,7 +68,7 @@ queue_up_100_writes (DConfClient *client)
 
       /* We should always see the most recently written value. */
       check_and_free (dconf_client_read (client, "/test/value"), g_variant_new_int32 (i));
-      check_and_free (dconf_client_read_default (client, "/test/value"), NULL);
+      check_and_free (dconf_client_read_full (client, "/test/value", DCONF_READ_DEFAULT_VALUE, NULL), NULL);
     }
 
   g_assert_cmpint (g_queue_get_length (&dconf_mock_dbus_outstanding_call_handles), ==, 2);
@@ -141,7 +141,7 @@ test_fast (void)
       g_assert (changed_was_called);
 
       check_and_free (dconf_client_read (client, "/test/value"), g_variant_new_int32 (99));
-      check_and_free (dconf_client_read_default (client, "/test/value"), NULL);
+      check_and_free (dconf_client_read_full (client, "/test/value", DCONF_READ_DEFAULT_VALUE, NULL), NULL);
     }
 
   /* Because of the pending-merging logic, we should only have had to
@@ -156,7 +156,7 @@ test_fast (void)
 
   /* Should read back now as NULL */
   check_and_free (dconf_client_read (client, "/test/value"), NULL);
-  check_and_free (dconf_client_read_default (client, "/test/value"), NULL);
+  check_and_free (dconf_client_read_full (client, "/test/value", DCONF_READ_DEFAULT_VALUE, NULL), NULL);
 
   /* Cleanup */
   g_signal_handlers_disconnect_by_func (client, changed, NULL);