GIcon: add g_icon_[de]serialize()

Add support for serialising a GIcon to a GVariant and deserialising the
result back to a GIcon.

This solves a number of problems suffered by the existing to_string()
API, primarily these:

 - not forcing the icon to be a utf8 string means that we can
   efficiently encode a PNG (ie: just give the array of bytes)

 - there is no need to ensure that proper types are loaded before using
   the deserialisation interface.  'Foreign' icon types will probably
   emit a serialised format the deserialises to a GBytesIcon.

We additionally clearly document what is required for being a consumer
or implementation of #GIcon.

Further patches will be required to GdkPixbuf and GVfsIcon to bring
their implementations in line with the new rules (essentially: introduce
implementations of the new serialize() API).

https://bugzilla.gnome.org/show_bug.cgi?id=688820

gio/gbytesicon.c

@@ -197,11 +197,21 @@ g_bytes_icon_equal (GIcon *icon1,
   return g_bytes_equal (bytes1->bytes, bytes2->bytes);
 }
 
+static GVariant *
+g_bytes_icon_serialize (GIcon *icon)
+{
+  GBytesIcon *bytes_icon = G_BYTES_ICON (icon);
+
+  return g_variant_new ("(sv)", "bytes",
+                        g_variant_new_from_bytes (G_VARIANT_TYPE_BYTESTRING, bytes_icon->bytes, TRUE));
+}
+
 static void
 g_bytes_icon_icon_iface_init (GIconIface *iface)
 {
   iface->hash = g_bytes_icon_hash;
   iface->equal = g_bytes_icon_equal;
+  iface->serialize = g_bytes_icon_serialize;
 }
 
 static GInputStream *

gio/gemblem.c

@@ -349,6 +349,26 @@ g_emblem_from_tokens (gchar  **tokens,
   return G_ICON (emblem);
 }
 
+static GVariant *
+g_emblem_serialize (GIcon *icon)
+{
+  GEmblem *emblem = G_EMBLEM (icon);
+  GVariant *icon_data;
+  GEnumValue *origin;
+  GVariant *result;
+
+  icon_data = g_icon_serialize (emblem->icon);
+  if (!icon_data)
+    return NULL;
+
+  origin = g_enum_get_value (g_type_class_peek (G_TYPE_EMBLEM_ORIGIN), emblem->origin);
+  result = g_variant_new_parsed ("('emblem', <(%v, {'origin': <%s>})>)",
+                                 icon_data, origin ? origin->value_nick : "unknown");
+  g_variant_unref (icon_data);
+
+  return result;
+}
+
 static void
 g_emblem_iface_init (GIconIface *iface)
 {
@@ -356,4 +376,5 @@ g_emblem_iface_init (GIconIface *iface)
   iface->equal = g_emblem_equal;
   iface->to_tokens = g_emblem_to_tokens;
   iface->from_tokens = g_emblem_from_tokens;
+  iface->serialize = g_emblem_serialize;
 }

gio/gemblemedicon.c

@@ -413,6 +413,54 @@ g_emblemed_icon_from_tokens (gchar  **tokens,
   return NULL;
 }
 
+static GVariant *
+g_emblemed_icon_serialize (GIcon *icon)
+{
+  GEmblemedIcon *emblemed_icon = G_EMBLEMED_ICON (icon);
+  GVariantBuilder builder;
+  GVariant *icon_data;
+  GList *node;
+
+  icon_data = g_icon_serialize (emblemed_icon->priv->icon);
+  if (!icon_data)
+    return NULL;
+
+  g_variant_builder_init (&builder, G_VARIANT_TYPE ("(va(va{sv}))"));
+
+  g_variant_builder_add (&builder, "v", icon_data);
+  g_variant_unref (icon_data);
+
+  g_variant_builder_open (&builder, G_VARIANT_TYPE ("a(va{sv})"));
+  for (node = emblemed_icon->priv->emblems; node != NULL; node = node->next)
+    {
+      icon_data = g_icon_serialize (node->data);
+      if (icon_data)
+        {
+          /* We know how emblems serialise, so do a tweak here to
+           * reduce some of the variant wrapping and redundant storage
+           * of 'emblem' over and again...
+           */
+          if (g_variant_is_of_type (icon_data, G_VARIANT_TYPE ("(sv)")))
+            {
+              const gchar *name;
+              GVariant *content;
+
+              g_variant_get (icon_data, "(&sv)", &name, &content);
+
+              if (g_str_equal (name, "emblem") && g_variant_is_of_type (content, G_VARIANT_TYPE ("(va{sv})")))
+                g_variant_builder_add (&builder, "@(va{sv})", content);
+
+              g_variant_unref (content);
+            }
+
+          g_variant_unref (icon_data);
+        }
+    }
+  g_variant_builder_close (&builder);
+
+  return g_variant_new ("(sv)", "emblemed", g_variant_builder_end (&builder));
+}
+
 static void
 g_emblemed_icon_icon_iface_init (GIconIface *iface)
 {
@@ -420,4 +468,5 @@ g_emblemed_icon_icon_iface_init (GIconIface *iface)
   iface->equal = g_emblemed_icon_equal;
   iface->to_tokens = g_emblemed_icon_to_tokens;
   iface->from_tokens = g_emblemed_icon_from_tokens;
+  iface->serialize = g_emblemed_icon_serialize;
 }

gio/gfileicon.c

@@ -256,6 +256,14 @@ g_file_icon_from_tokens (gchar  **tokens,
   return icon;
 }
 
+static GVariant *
+g_file_icon_serialize (GIcon *icon)
+{
+  GFileIcon *file_icon = G_FILE_ICON (icon);
+
+  return g_variant_new ("(sv)", "file", g_variant_new_take_string (g_file_get_uri (file_icon->file)));
+}
+
 static void
 g_file_icon_icon_iface_init (GIconIface *iface)
 {
@@ -263,6 +271,7 @@ g_file_icon_icon_iface_init (GIconIface *iface)
   iface->equal = g_file_icon_equal;
   iface->to_tokens = g_file_icon_to_tokens;
   iface->from_tokens = g_file_icon_from_tokens;
+  iface->serialize = g_file_icon_serialize;
 }
 
 

gio/gicon.c

@@ -28,8 +28,11 @@
 #include "gthemedicon.h"
 #include "gfileicon.h"
 #include "gemblemedicon.h"
+#include "gbytesicon.h"
 #include "gfile.h"
 #include "gioerror.h"
+#include "gioenumtypes.h"
+#include "gvfs.h"
 
 #include "glibintl.h"
 
@@ -49,17 +52,27 @@
  * #GIcon does not provide the actual pixmap for the icon as this is out 
  * of GIO's scope, however implementations of #GIcon may contain the name 
  * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). 
- * 
+ *
  * To obtain a hash of a #GIcon, see g_icon_hash().
- * 
+ *
  * To check if two #GIcons are equal, see g_icon_equal().
  *
- * For serializing a #GIcon, use g_icon_to_string() and
- * g_icon_new_for_string().
+ * For serializing a #GIcon, use g_icon_serialize() and
+ * g_icon_deserialize().
+ *
+ * If you want to consume #GIcon (for example, in a toolkit) you must
+ * be prepared to handle at least the three following cases:
+ * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon.  It may also make
+ * sense to have fast-paths for other cases (like handling #GdkPixbuf
+ * directly, for example) but all compliant #GIcon implementations
+ * outside of GIO must implement #GLoadableIcon.
  *
  * If your application or library provides one or more #GIcon
- * implementations you need to ensure that each #GType is registered
- * with the type system prior to calling g_icon_new_for_string().
+ * implementations you need to ensure that your new implementation also
+ * implements #GLoadableIcon.  Additionally, you must provide an
+ * implementation of g_icon_serialize() that gives a result that is
+ * understood by g_icon_deserialize(), yielding one of the built-in icon
+ * types.
  **/
 
 typedef GIconIface GIconInterface;
@@ -456,3 +469,195 @@ g_icon_new_for_string (const gchar   *str,
 
   return icon;
 }
+
+static GEmblem *
+g_icon_deserialize_emblem (GVariant *value)
+{
+  GVariant *emblem_metadata;
+  GVariant *emblem_data;
+  const gchar *origin_nick;
+  GIcon *emblem_icon;
+  GEmblem *emblem;
+
+  g_variant_get (value, "(v@a{sv})", &emblem_data, &emblem_metadata);
+
+  emblem = NULL;
+
+  emblem_icon = g_icon_deserialize (emblem_data);
+  if (emblem_icon != NULL)
+    {
+      /* Check if we should create it with an origin. */
+      if (g_variant_lookup (emblem_metadata, "origin", "&s", &origin_nick))
+        {
+          GEnumClass *origin_class;
+          GEnumValue *origin_value;
+
+          origin_class = g_type_class_ref (G_TYPE_EMBLEM_ORIGIN);
+          origin_value = g_enum_get_value_by_nick (origin_class, origin_nick);
+          if (origin_value)
+            emblem = g_emblem_new_with_origin (emblem_icon, origin_value->value);
+          g_type_class_unref (origin_class);
+        }
+
+      /* We didn't create it with an origin, so do it without. */
+      if (emblem == NULL)
+        emblem = g_emblem_new (emblem_icon);
+
+      g_object_unref (emblem_icon);
+    }
+
+  g_variant_unref (emblem_metadata);
+  g_variant_unref (emblem_data);
+
+  return emblem;
+}
+
+static GIcon *
+g_icon_deserialize_emblemed (GVariant *value)
+{
+  GVariantIter *emblems;
+  GVariant *icon_data;
+  GIcon *main_icon;
+  GIcon *icon;
+
+  g_variant_get (value, "(va(va{sv}))", &icon_data, &emblems);
+  main_icon = g_icon_deserialize (icon_data);
+
+  if (main_icon)
+    {
+      GVariant *emblem_data;
+
+      icon = g_emblemed_icon_new (main_icon, NULL);
+
+      while ((emblem_data = g_variant_iter_next_value (emblems)))
+        {
+          GEmblem *emblem;
+
+          emblem = g_icon_deserialize_emblem (emblem_data);
+
+          if (emblem)
+            {
+              g_emblemed_icon_add_emblem (G_EMBLEMED_ICON (icon), emblem);
+              g_object_unref (emblem);
+            }
+
+          g_variant_unref (emblem_data);
+        }
+
+      g_object_unref (main_icon);
+    }
+
+  g_variant_iter_free (emblems);
+  g_variant_unref (icon_data);
+
+  return icon;
+}
+
+GIcon *
+g_icon_deserialize (GVariant *value)
+{
+  const gchar *tag;
+  GVariant *val;
+  GIcon *icon;
+
+  g_return_val_if_fail (value != NULL, NULL);
+  g_return_val_if_fail (g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) ||
+                        g_variant_is_of_type (value, G_VARIANT_TYPE ("(sv)")), NULL);
+
+  /* Handle some special cases directly so that people can hard-code
+   * stuff into GMenuModel xml files without resorting to using GVariant
+   * text format to describe one of the explicitly-tagged possibilities
+   * below.
+   */
+  if (g_variant_is_of_type (value, G_VARIANT_TYPE_STRING))
+    return g_icon_new_for_string_simple (g_variant_get_string (value, NULL));
+
+  /* Otherwise, use the tagged union format */
+  g_variant_get (value, "(&sv)", &tag, &val);
+
+  icon = NULL;
+
+  if (g_str_equal (tag, "file") && g_variant_is_of_type (val, G_VARIANT_TYPE_STRING))
+    {
+      GFile *file;
+
+      file = g_file_new_for_commandline_arg (g_variant_get_string (val, NULL));
+      icon = g_file_icon_new (file);
+      g_object_unref (file);
+    }
+  else if (g_str_equal (tag, "themed") && g_variant_is_of_type (val, G_VARIANT_TYPE_STRING_ARRAY))
+    {
+      const gchar **names;
+      gsize size;
+
+      names = g_variant_get_strv (val, &size);
+      icon = g_themed_icon_new_from_names ((gchar **) names, size);
+      g_free (names);
+    }
+  else if (g_str_equal (tag, "bytes") && g_variant_is_of_type (val, G_VARIANT_TYPE_BYTESTRING))
+    {
+      GBytes *bytes;
+
+      bytes = g_variant_get_data_as_bytes (val);
+      icon = g_bytes_icon_new (bytes);
+      g_bytes_unref (bytes);
+    }
+  else if (g_str_equal (tag, "emblem") && g_variant_is_of_type (val, G_VARIANT_TYPE ("(va{sv})")))
+    {
+      GEmblem *emblem;
+
+      emblem = g_icon_deserialize_emblem (val);
+      if (emblem)
+        icon = G_ICON (emblem);
+    }
+  else if (g_str_equal (tag, "emblemed") && g_variant_is_of_type (val, G_VARIANT_TYPE ("(va(va{sv}))")))
+    {
+      icon = g_icon_deserialize_emblemed (val);
+    }
+  else if (g_str_equal (tag, "gvfs"))
+    {
+      GVfsClass *class;
+      GVfs *vfs;
+
+      vfs = g_vfs_get_default ();
+      class = G_VFS_GET_CLASS (vfs);
+      if (class->deserialize_icon)
+        icon = (* class->deserialize_icon) (vfs, val);
+    }
+
+  g_variant_unref (val);
+
+  return icon;
+}
+
+GVariant *
+g_icon_serialize (GIcon *icon)
+{
+  GIconInterface *iface;
+  GVariant *result;
+
+  iface = G_ICON_GET_IFACE (icon);
+
+  if (!iface->serialize)
+    {
+      g_critical ("g_icon_serialize() on icon type `%s' is not implemented", G_OBJECT_TYPE_NAME (icon));
+      return NULL;
+    }
+
+  result = (* iface->serialize) (icon);
+
+  if (result)
+    {
+      g_variant_take_ref (result);
+
+      if (!g_variant_is_of_type (result, G_VARIANT_TYPE ("(sv)")))
+        {
+          g_critical ("g_icon_serialize() on icon type `%s' returned GVariant of type `%s' but it must return "
+                      "one with type `(sv)'", G_OBJECT_TYPE_NAME (icon), g_variant_get_type_string (result));
+          g_variant_unref (result);
+          result = NULL;
+        }
+    }
+
+  return result;
+}

gio/gicon.h

@@ -75,6 +75,8 @@ struct _GIconIface
                                gint     num_tokens,
                                gint     version,
                                GError **error);
+
+  GVariant *  (* serialize)   (GIcon   *icon);
 };
 
 GLIB_AVAILABLE_IN_ALL
@@ -91,6 +93,11 @@ GLIB_AVAILABLE_IN_ALL
 GIcon   *g_icon_new_for_string  (const gchar   *str,
                                  GError       **error);
 
+GLIB_AVAILABLE_IN_2_38
+GVariant * g_icon_serialize     (GIcon         *icon);
+GLIB_AVAILABLE_IN_2_38
+GIcon *    g_icon_deserialize   (GVariant      *value);
+
 G_END_DECLS
 
 #endif /* __G_ICON_H__ */

gio/gthemedicon.c

@@ -512,6 +512,14 @@ g_themed_icon_from_tokens (gchar  **tokens,
   return icon;
 }
 
+static GVariant *
+g_themed_icon_serialize (GIcon *icon)
+{
+  GThemedIcon *themed_icon = G_THEMED_ICON (icon);
+
+  return g_variant_new ("(sv)", "themed", g_variant_new ("^as", themed_icon->names));
+}
+
 static void
 g_themed_icon_icon_iface_init (GIconIface *iface)
 {
@@ -519,4 +527,5 @@ g_themed_icon_icon_iface_init (GIconIface *iface)
   iface->equal = g_themed_icon_equal;
   iface->to_tokens = g_themed_icon_to_tokens;
   iface->from_tokens = g_themed_icon_from_tokens;
+  iface->serialize = g_themed_icon_serialize;
 }

gio/gvfs.h

@@ -95,6 +95,8 @@ struct _GVfsClass
   void                  (* local_file_moved)          (GVfs       *vfs,
 						       const char *source,
 						       const char *dest);
+  GIcon *               (* deserialize_icon)          (GVfs       *vfs,
+                                                       GVariant   *value);
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
@@ -102,7 +104,6 @@ struct _GVfsClass
   void (*_g_reserved4) (void);
   void (*_g_reserved5) (void);
   void (*_g_reserved6) (void);
-  void (*_g_reserved7) (void);
 };
 
 GLIB_AVAILABLE_IN_ALL

gio/tests/g-icon.c

@@ -28,7 +28,7 @@
 #include <string.h>
 
 static void
-test_g_icon_serialize (void)
+test_g_icon_to_string (void)
 {
   GIcon *icon;
   GIcon *icon2;
@@ -247,6 +247,125 @@ test_g_icon_serialize (void)
   g_free (data);
 }
 
+static void
+test_g_icon_serialize (void)
+{
+  GIcon *icon;
+  GIcon *icon2;
+  GIcon *icon3;
+  GIcon *icon4;
+  GIcon *icon5;
+  GEmblem *emblem1;
+  GEmblem *emblem2;
+  GFile *location;
+  GVariant *data;
+  gint origin;
+  GIcon *i;
+
+  /* Check that we can deserialize from well-known specified formats */
+  data = g_variant_new_string ("network-server%");
+  icon = g_icon_deserialize (g_variant_ref_sink (data));
+  g_variant_unref (data);
+  icon2 = g_themed_icon_new ("network-server%");
+  g_assert (g_icon_equal (icon, icon2));
+  g_object_unref (icon);
+  g_object_unref (icon2);
+
+  data = g_variant_new_string ("/path/to/somewhere.png");
+  icon = g_icon_deserialize (g_variant_ref_sink (data));
+  g_variant_unref (data);
+  location = g_file_new_for_commandline_arg ("/path/to/somewhere.png");
+  icon2 = g_file_icon_new (location);
+  g_assert (g_icon_equal (icon, icon2));
+  g_object_unref (icon);
+  g_object_unref (icon2);
+  g_object_unref (location);
+
+  data = g_variant_new_string ("/path/to/somewhere with whitespace.png");
+  icon = g_icon_deserialize (g_variant_ref_sink (data));
+  g_variant_unref (data);
+  location = g_file_new_for_commandline_arg ("/path/to/somewhere with whitespace.png");
+  icon2 = g_file_icon_new (location);
+  g_assert (g_icon_equal (icon, icon2));
+  g_object_unref (location);
+  g_object_unref (icon2);
+  location = g_file_new_for_commandline_arg ("/path/to/somewhere%20with%20whitespace.png");
+  icon2 = g_file_icon_new (location);
+  g_assert (!g_icon_equal (icon, icon2));
+  g_object_unref (location);
+  g_object_unref (icon2);
+  g_object_unref (icon);
+
+  data = g_variant_new_string ("sftp:///path/to/somewhere.png");
+  icon = g_icon_deserialize (g_variant_ref_sink (data));
+  g_variant_unref (data);
+  location = g_file_new_for_commandline_arg ("sftp:///path/to/somewhere.png");
+  icon2 = g_file_icon_new (location);
+  g_assert (g_icon_equal (icon, icon2));
+  g_object_unref (icon);
+  g_object_unref (icon2);
+  g_object_unref (location);
+
+  /* Check that GThemedIcon serialization works */
+
+  icon = g_themed_icon_new ("network-server");
+  g_themed_icon_append_name (G_THEMED_ICON (icon), "computer");
+  data = g_icon_serialize (icon);
+  icon2 = g_icon_deserialize (data);
+  g_assert (g_icon_equal (icon, icon2));
+  g_variant_unref (data);
+  g_object_unref (icon);
+  g_object_unref (icon2);
+
+  icon = g_themed_icon_new ("icon name with whitespace");
+  g_themed_icon_append_name (G_THEMED_ICON (icon), "computer");
+  data = g_icon_serialize (icon);
+  icon2 = g_icon_deserialize (data);
+  g_assert (g_icon_equal (icon, icon2));
+  g_variant_unref (data);
+  g_object_unref (icon);
+  g_object_unref (icon2);
+
+  icon = g_themed_icon_new_with_default_fallbacks ("network-server-xyz");
+  g_themed_icon_append_name (G_THEMED_ICON (icon), "computer");
+  data = g_icon_serialize (icon);
+  icon2 = g_icon_deserialize (data);
+  g_assert (g_icon_equal (icon, icon2));
+  g_variant_unref (data);
+  g_object_unref (icon);
+  g_object_unref (icon2);
+
+  /* Check that GEmblemedIcon serialization works */
+
+  icon = g_themed_icon_new ("face-smirk");
+  icon2 = g_themed_icon_new ("emblem-important");
+  g_themed_icon_append_name (G_THEMED_ICON (icon2), "emblem-shared");
+  location = g_file_new_for_uri ("file:///some/path/somewhere.png");
+  icon3 = g_file_icon_new (location);
+  g_object_unref (location);
+  emblem1 = g_emblem_new_with_origin (icon2, G_EMBLEM_ORIGIN_DEVICE);
+  emblem2 = g_emblem_new_with_origin (icon3, G_EMBLEM_ORIGIN_LIVEMETADATA);
+  icon4 = g_emblemed_icon_new (icon, emblem1);
+  g_emblemed_icon_add_emblem (G_EMBLEMED_ICON (icon4), emblem2);
+  data = g_icon_serialize (icon4);
+  icon5 = g_icon_deserialize (data);
+  g_assert (g_icon_equal (icon4, icon5));
+
+  g_object_get (emblem1, "origin", &origin, "icon", &i, NULL);
+  g_assert (origin == G_EMBLEM_ORIGIN_DEVICE);
+  g_assert (i == icon2);
+  g_object_unref (i);
+
+  g_object_unref (emblem1);
+  g_object_unref (emblem2);
+  g_object_unref (icon);
+  g_object_unref (icon2);
+  g_object_unref (icon3);
+  g_object_unref (icon4);
+  g_object_unref (icon5);
+  g_variant_unref (data);
+}
+
 static void
 test_themed_icon (void)
 {
@@ -373,6 +492,7 @@ main (int   argc,
 {
   g_test_init (&argc, &argv, NULL);
 
+  g_test_add_func ("/icons/to-string", test_g_icon_to_string);
   g_test_add_func ("/icons/serialize", test_g_icon_serialize);
   g_test_add_func ("/icons/themed", test_themed_icon);
   g_test_add_func ("/icons/emblemed", test_emblemed_icon);