[grilo] doc: Document how to handle multi-valued keys

[Juan A. Suarez Romero <jasuarez src gnome org>]

commit fb3484baf873588df5ea46f2b21066569b11a250
Author: Juan A. Suarez Romero <jasuarez igalia com>
Date:   Tue Apr 19 09:56:24 2011 +0000

    doc: Document how to handle multi-valued keys
    
    Signed-off-by: Juan A. Suarez Romero <jasuarez igalia com>

 doc/grilo/quick-start-using-grilo.xml |  170 +++++++++++++++++++++++++++++++++
 1 files changed, 170 insertions(+), 0 deletions(-)
---
diff --git a/doc/grilo/quick-start-using-grilo.xml b/doc/grilo/quick-start-using-grilo.xml
index cc1bae5..81a36c2 100644
--- a/doc/grilo/quick-start-using-grilo.xml
+++ b/doc/grilo/quick-start-using-grilo.xml
@@ -480,6 +480,176 @@ main (int argc, gchar *argv[])
     </programlisting>    
   </section>
 
+  <section id="programming-with-grilo-multivalued-data">
+    <title>Programming with Grilo: Multi-valued data</title>
+    <para>When working with multimedia content, it can happen that a multimedia
+      element contains several values for one or more keys. Thus, it is quite
+      common having an image with several URLs, each of them providing the image
+      from several places, or moreover, providing the same image with several
+      resolutions.
+    </para>
+    <para>
+      Grilo is able to handle this kind of multimedia content. By default, Grilo
+      handles multi-valued elements in a straight way: developer can add multiple
+      values to a specific key, and retrieve them.
+    </para>
+    <para>
+      An important issue when dealing with multi-valued keys is that there are
+      keys that have values related among them. An example of this is an image
+      providing several URLs, each of them with a different resolution: for each
+      URL, there would be a specific value for WIDTH and HEIGHT. Thus, URL,
+      WIDTH and HEIGHT are multi-valued keys, and those keys are related among
+      them: a specific WIDTH value matches with a specific HEIGHT and URL
+      values. We say those keys are related.
+    </para>
+    <para>
+      The basic idea of related keys is that user sets and gets those keys
+      together. Of course, Grilo still provides API to get one of the values
+      forgetting about the related ones. But the right way is to handling them
+      as a group.
+    </para>
+    <para>
+      In case of pre-defined keys, Grilo already provides high level API to
+      handle several related keys as a group. Thus, in the image example above,
+      there is grl_media_image_add_url_data() and
+      grl_media_image_get_url_data_nth() to add and retrieve the URL values, as
+      well as related values (MIME, WIDTH and HEIGHT).
+    </para>
+    <para>
+      In the case of keys defined by plugins, after registering the keys,
+      plugins must also register which keys are related with.  To deal with
+      related keys and values, developers can use GrlRelatedKeys: a placeholder
+      where related keys and their values are stored. Thus, developer would
+      create a GrlRelatedKeys, adds inside the related keys and its values (in
+      the case of image, the URL, WIDTH and HEIGHT), and then add this
+      GrlRelatedKeys in the GrlData.
+    </para>
+    <para>
+      Here is a small program illustrating how to show all URLs from a video, as
+      well the associated MIME value. We use GrlRelatedKeys instead of
+      high-level API from GrlMediaVideo to illustrate how to use them:
+    </para>
+    <programlisting role="C">
+<![CDATA[
+#include <grilo.h>
+#include <string.h>
+
+#define GRL_LOG_DOMAIN_DEFAULT  example_log_domain
+GRL_LOG_DOMAIN_STATIC(example_log_domain);
+
+static void
+search_cb (GrlMediaSource *source,
+	   guint browse_id,
+	   GrlMedia *media,
+	   guint remaining,
+	   gpointer user_data,
+	   const GError *error)
+{
+  guint i;
+  GrlRelatedKeys *url_related;
+
+  if (error) {
+    g_error ("Search operation failed. Reason: %s", error->message);
+  }
+
+  if (media) {
+    for (i = 0; i < grl_data_length (GRL_DATA (media), GRL_METADATA_KEY_URL); i++) {
+      url_related = grl_data_get_related_keys (GRL_DATA (media), GRL_METADATA_KEY_URL, i);
+      /* Print keys and values */
+      g_debug ("\t [%s] Got url '%s' and mime-type '%s'",
+               grl_media_get_id (media),
+               grl_related_keys_get_string (url_related, GRL_METADATA_KEY_URL),
+               grl_related_keys_get_string (url_related, GRL_METADATA_KEY_MIME));
+    }
+  }
+
+  if (remaining == 0) {
+    g_debug ("Search operation finished!");
+  }
+
+  g_object_unref (media);
+}
+
+static void
+source_added_cb (GrlPluginRegistry *registry, gpointer user_data)
+{
+  const gchar *id;
+  GrlMetadataSource *source = GRL_METADATA_SOURCE (user_data);
+  GList * keys = grl_metadata_key_list_new (GRL_METADATA_KEY_TITLE,
+					    GRL_METADATA_KEY_URL,
+                                            GRL_METADATA_KEY_MIME
+					    NULL);
+
+  /* Not interested if not searchable */
+  if (!(grl_metadata_source_supported_operations (source) & GRL_OP_SEARCH))
+    return;
+
+  g_debug ("Detected new searchable source available: '%s'",
+	   grl_metadata_source_get_name (source));
+
+  /* Only interested in Youtube */
+  id = grl_metadata_source_get_id (source);
+  if (strcmp (id, "grl-youtube"))
+    return;
+
+  g_debug ("Searching \"rock\" in Youtube");
+  grl_media_source_search (GRL_MEDIA_SOURCE (source),
+			   "rock",
+			   keys,
+			   0, 5,
+			   GRL_RESOLVE_IDLE_RELAY,
+			   search_cb,
+			   NULL);
+
+  g_list_free (keys);
+}
+
+static void
+load_plugins (void)
+{
+  GrlPluginRegistry *registry;
+  GError *error = NULL;
+
+  registry = grl_plugin_registry_get_default ();
+  g_signal_connect (registry, "source-added",
+		    G_CALLBACK (source_added_cb), NULL);
+  if (!grl_plugin_registry_load_all (registry, &error)) {
+    g_error ("Failed to load plugins: %s", error->message);
+  }
+}
+
+static void
+configure_plugins (void)
+{
+  GrlConfig *config;
+  GrlPluginRegistry *registry;
+
+  /* Let's configure only the Youtube plugin. This plugin just requires an API
+     key */
+  config = grl_config_new ("grl-youtube", NULL);
+  grl_config_set_api_key (config,
+                          "AI39si4EfscPllSfUy1IwexMf__kntTL_G5dfSr2iUEVN45RHG"
+                          "q92Aq0lX25OlnOkG6KTN-4soVAkAf67fWYXuHfVADZYr7S1A");
+  registry = grl_plugin_registry_get_default ();
+  grl_plugin_registry_add_config (registry, config, NULL);
+}
+
+gint
+main (int argc, gchar *argv[])
+{
+  GMainLoop *loop;
+  grl_init (&argc, &argv);
+  GRL_LOG_DOMAIN_INIT (example_log_domain, "example");
+  configure_plugins ();
+  load_plugins ();
+  loop = g_main_loop_new (NULL, FALSE);
+  g_main_loop_run (loop);
+  return 0;
+}
+]]>
+    </programlisting>
+  </section>
+
   <section id="programming-with-grilo-efficient-metadata-resolution">
     <title>Programming with Grilo: Efficient metadata resolution</title>
     <para>When executing operations that return lists of media items (like