Introduction

Sources provide access to media content. Examples of them are sources providing content from Jamendo or UPnP. Sources can also provide other information that complements already existent media content. Thus, there can be sources providing content and others adding more informationover that content.

Sources are provided by plugins. A plugin usually provides one source, but it can provide more than one. For instance, the UPnP plugin is able to provide several sources, one source per each UPnP server found in the network.

Usually, clients interact with these sources in various ways:

• Search. Users can instruct the source to search for content that matches certain keywords. This is how people typically interact with services like YouTube, for example.
• Browse. Users navigate through a fixed hierarchy of categorized content interactively. This is how people typically interact with UPnP services, for example.
• Query. Some times services provide features that are too specific to be transported to a generic, cross-service API. An example of this could be certain search filtering options. Queries allow users to interact with services using service-specific language that can be used to exploit these features.
• Resolve. Users can request additional information (metadata) for a specific media item served by a source through a previous browse, search or query operation that was configured to retrieve only partial metadata (typically for optimization purposes). Resolve operations are usually used when showing detailed information about specific media items.
• Store. Some sources allow (or even require) users to push content to them. This is how people interact with Podcasts for example, they “store” the feeds they are interested in following first. A source can store either the full media or just a subset of their properties.
• Remove. The opposite to the Store operation, used to remove content from the source. Media from URL. This allows to build a media just knowing the URL. For instance, giving a YouTube URL, the proper source is able to build and return the corresponding Grilo media content.

Registering Plugins

Grilo plugins must use the macro GRL_PLUGIN_DEFINE(), which defines the entry and exit points of the plugin (called when the plugin is loaded and unloaded respectively) as well as its plugin identifier (a string identifying the plugin).

The plugin identifier will be used by clients to identify the plugin when interacting with the plugin registry API. See the GrlRegistry API reference for more details.

The plugin initialization function is mandatory. The plugin deinitialization function is optional.

Usually the plugin initialization function will create at least one GrlSource instance and register it using grl_registry_register_source().

A GrlSource instance represents a particular source of media/attributes. Usually each plugin would spawn just one media source, but some plugins may spawn multiple sources. For example, a UPnP plugin spawning one media source object for each UPnP server discovered.

Users can query the registry for available sources and then use the GrlSource API to interact with them.

The parameter “configs” of the plugin initialization function provides available configuration information provided by the user for this plugin, if any. This parameter is a list of GrlConfig objects. Usually there would be only one GrlConfig object in the list, but there might be more in the cases of plugins spawning multiple media sources that require different configuration options.

gboolean
grl_foo_plugin_init (GrlRegistry *registry,
                     GrlPlugin *plugin,
                     GList *configs)
{
  gchar *api_key;
  GrlConfig *config;

  config = GRL_CONFIG (configs->data);

  api_key = grl_config_get_api_key (config);
  if (!api_key) {
    GRL_INFO ("Missing API Key, cannot load plugin");
    return FALSE;
  }

  GrlFooSource *source = grl_foo_source_new (api_key);
  grl_registry_register_source (registry,
                                plugin,
                                GRL_SOURCE (source),
                                NULL);
  g_free (api_key);
  return TRUE;
}

GRL_PLUGIN_DEFINE (0,
                   3,
                   "grl-foo",
                   "Foo",
                   "A plugin for Foo",
                   "GNOME",
                   "1.0.0",
                   "LGPL",
                   "http://www.gnome.org",
                   grl_foo_plugin_init,
                   NULL,
                   NULL);

The next step is to implement the source code, for that sources must extend the GrlSource class.

In typical GObject fashion, developers should use the G_DEFINE_TYPE macro, and then provide the class initialization function (grl_foo_source_class_init() in the example below) and the instance initialization function (grl_foo_source_init() in the example below). A constructor function, although not mandatory, is usually nice to have (grl_foo_source_new() in the example below).

When creating a new GrlSource iinstance, a few properties should be provided:

• source-id: An identifier for the source object. This is not the same as the plugin identifier (remember that a plugin can spawn multiple media source objects). This identifier can be used by clients when interacting with available media sources through the plugin registry API. See the GrlRegistry API reference for more details.
• source-name: A name for the source object (typically the name that clients would show in the user interface).
• source-desc: A description of the media source.

In the class initialization function the plugin developer should provide implementations for the operations that the plugin will support. Almost all operations are optional, but for typically Search or Browse are expected in sources providing media content, and Resolve for sources providing information for existent content.

/* Foo class initialization code */
static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);

  source_class->supported_keys = grl_foo_source_supported_keys;
  source_class->slow_keys = grl_foo_source_slow_keys;
  source_class->browse = grl_foo_source_browse;
  source_class->search = grl_foo_source_search;
  source_class->query = grl_foo_source_query;
  source_class->store = grl_foo_source_store;
  source_class->remove = grl_foo_source_remove;
  source_class->resolve = grl_foo_source_resolve;
}

/* Foo instance initialization code */
static void
grl_foo_source_init (GrlFooSource *source)
{
  /* Here you would initialize 'source', which is an instance
     of this class type. */
  source->api_key = NULL;
}

/* GrlFooSource constructor */
static GrlFooSource *
grl_foo_source_new (const gchar *api_key)
{
  GrlFooSource *source;

  source = GRL_FOO_SOURCE (g_object_new (GRL_FOO_SOURCE_TYPE,
                                         "source-id", "grl-foo",
                                         "source-name", "Foo",
                                         "source-desc", "Foo media provider",
                                         NULL));
  source->api_key = g_strdup (api_key);
  return source;
}

G_DEFINE_TYPE (GrlFooSource, grl_foo_source, GRL_TYPE_SOURCE);

Implementing Supported Keys

Sources should implement supported_keys method to define what metadata keys the source is able to handle.

This method is declarative, and it only has to return a list of metadata keys that the plugin supports, that is, it is a declaration of the metadata that the plugin can provide for the media content that it exposes.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->supported_keys = grl_foo_source_supported_keys;
}

static const GList *
grl_foo_source_supported_keys (GrlSource *source)
{
  static GList *keys = NULL;
  if (!keys) {
    keys = grl_metadata_key_list_new (GRL_METADATA_KEY_ID,
                                      GRL_METADATA_KEY_TITLE,
                                      GRL_METADATA_KEY_URL,
                                      GRL_METADATA_KEY_THUMBNAIL,
                                      GRL_METADATA_KEY_MIME,
                                      GRL_METADATA_KEY_ARTIST,
                                      GRL_METADATA_KEY_DURATION,
                                      GRL_METADATA_KEY_INVALID);
  }
  return keys;
}

Implementing Slow Keys

This method is similar to supported_keys, and in fact it returns a subset of the keys returned by supported_keys.

This method is intended to provide the framework with information on metadata that is particularly expensive for the framework to retrieve. The framework (or the plugin users) can then use this information to remove this metadata from their requests when performance is important. This is, again, a declarative interface providing a list of keys.

If the plugin does not provide an implementation for slow_keys the framework assumes that all keys are equally expensive to retrieve and will not perform optimizations in any case.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->slow_keys = grl_foo_source_slow_keys;
}

static const GList *
grl_foo_source_slow_keys (GrlSource *source)
{
  static GList *keys = NULL;
  if (!keys) {
    keys = grl_metadata_key_list_new (GRL_METADATA_KEY_URL,
                                      NULL);
  }
  return keys;
}

Implementing Search

This method implements free-text based searches, retrieving media that matches the text provided by the user.

Typically, the way this method operates is like this:

• Plugin receives the text to search, as well as other parameters like the metadata keys to retrieve, how many elements, and so on.
• With all this information the plugin executes the search on the backend, and waits for the results.
• Plugin receives the results from the service provider, and encodes them in different GrlMedia objects.
• Plugin sends each GrlMedia object back to the client, one by one, invoking the user provided callback.

Below you can see some source code that illustrates this process:

/* In this example we assume a media provider that can be
   queried over http, and that provides its results in xml format */

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->search = grl_foo_source_search;
}

static void
foo_execute_search_async_cb (gchar *xml, GrlSourceSearchSpec *ss)
{
  GrlMedia *media;
  gint count;

  count = count_results (xml);

  if (count == 0) {
    /* Signal "no results" */
    ss->callback (ss->source, ss->operation_id,
                  NULL, 0, ss->user_data, NULL);
  } else {
    /* parse_next parses the next media item in the XML
       and creates a GrlMedia instance with the data extracted */
    while (media = parse_next (xml))
      ss->callback (ss->source,       /* Source emitting the data */
                    ss->operation_id, /* Operation identifier */
                    media,            /* Media that matched the query */
                    --count,          /* Remaining count */
                    ss->user_data,    /* User data for the callback */
                    NULL);            /* GError instance (if an error occurred) */
  }
}

static void
grl_foo_source_search (GrlSource *source, GrlSourceSearchSpec *ss)
{
  gchar *foo_http_search:

  foo_http_search =
    g_strdup_printf("http://media.foo.com?text=%s&offset=%d&count=%d",
                    ss->text,
                    grl_operation_options_get_skip (ss->options),
                    grl_operation_options_get_count (ss->options));

  /* This executes an async http query and then invokes
     foo_execute_search_async_cb with the response */
  foo_execute_search_async (foo_http_search, ss);
}

Please, check Common considerations for Search, Browse and Query implementations for more information on how to implement Search operations properly.

Examples of plugins implementing Search functionality are grl-jamendo, grl-youtube or grl-vimeo among others.

Implementing Browse

Browsing is an interactive process, where users navigate by exploring these containers exposed by the media source in hierarchical form. The idea of browsing a media source is the same as browsing a file system.

The signature and way of operation of the Browse operation is the same as in the Search operation with one difference: instead of a text parameter with the search keywords, it receives a GrlMedia object representing the container the user wants to browse.

For the most part, plugin developers that write Browse implementations should consider the same rules and guidelines explained for Search operations.

Below you can see some source code that illustrates this process:

/* In this example we assume a media provider that can be queried over
   http, providing results in XML format. The media provider organizes
   content according to a list of categories. */

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->browse = grl_foo_source_browse;
}

static void
foo_execute_categories_async_cb (gchar *xml, GrlSourceBrowseSpec *bs)
{
  GrlMedia *media;
  gint count;

  count = count_results (xml);

  if (count == 0) {
    /* Signal "no results" */
    bs->callback (bs->source, bs->operation_id,
                  NULL, 0, bs->user_data, NULL);
  } else {
    /* parse_next parses the next category item in the XML
       and creates a GrlMedia instance with the data extracted,
       which should be a container */
    while (media = parse_next_cat (xml))
      bs->callback (bs->source,       /* Source emitting the data */
                    bs->operation_id, /* Operation identifier */
                    media,            /* The category container  */
                    --count,          /* Remaining count */
                    bs->user_data,    /* User data for the callback */
                    NULL);            /* GError instance (if an error occurred) */
  }
}

static void
foo_execute_media_async_cb (gchar *xml, GrlSourceBrowseSpec *os)
{
  GrlMedia *media;
  gint count;

  count = count_results (xml);

  if (count == 0) {
    /* Signal "no results" */
    bs->callback (bs->source, bs->operation_id,
                  NULL, 0, bs->user_data, NULL);
  } else {
    /* parse_next parses the next media item in the XML
       and creates a GrlMedia instance with the data extracted */
    while (media = parse_next_media (xml))
      os->callback (os->source,       /* Source emitting the data */
                    os->operation_id, /* Operation identifier */
                    media,            /* Media that matched the query */
                    --count,          /* Remaining count */
                    os->user_data,    /* User data for the callback */
                    NULL);            /* GError instance (if an error occurred) */
  }
}

static void
grl_foo_source_browse (GrlSource *source, GrlSourceBrowseSpec *bs)
{
  gchar *foo_http_browse:

  /* We use the names of the categories as their media identifiers */
  container_id = grl_media_get_id (bs->container);

  if (!container_id) {
    /* Browsing the root container, the result must be the list of
       categories provided by the service */
    foo_http_browse =
      g_strdup_printf("http://media.foo.com/category_list",
                      grl_operation_options_get_skip (bs),
                      grl_operation_options_get_count (bs));
     /* This executes an async http query and then invokes
        foo_execute_categories_async_cb with the response */
     foo_execute_categories_async (foo_http_browse, bs);
  } else {
    /* Browsing a specific category */
    foo_http_browse =
      g_strdup_printf("http://media.foo.com/content/%s?offset=%d&count=%d",
                      container_id,
                      grl_operation_options_get_skip (bs),
                      grl_operation_options_get_count (bs));
     /* This executes an async http query and then invokes
        foo_execute_browse_async_cb with the response */
     foo_execute_media_async (foo_http_browse, bs);
  }
}

Some considerations that plugin developers should take into account:

• In the example we are assuming that the content hierarchy only has two levels, the first level exposes a list of categories (each one exposed as a container GrlMedia object so the user knows they can be browsed again), and then a second level with the contents within these categories, that we assume are all media items, although in real life they could very well be more containers, leading to more complex hierarchies.
• Containers returned by a browse operation can be browsed by clients in future Browse operations.
• The input parameter that informs the plugin about the container that should be browsed (bs->container) is of type GrlMedia. The plugin developer must map that to something the media provider understands. Typically, when GrlMedia objects are returned from a plugin to the client, they are created so their “id” property (grl_media_set_id()) can be used for this purpose, identifying these media resources uniquely in the context of the media provider.
• A GrlMedia object with NULL id always represents the root container/category in the content hierarchy exposed by the plugin.

Please, check Common considerations for Search, Browse and Query implementations for more information on how to implement Browse operations properly.

Examples of plugins implementing browse functionality are grl-jamendo, grl-filesystem or grl-upnp among others.

Implementing Query

This method provides plugin developers with means to expose service-specific functionality that cannot be achieved through regular Browse and Search operations.

This method operates just like the Search method, but the text parameter does not represent a list of keywords to search for, instead, its meaning is plugin specific and defined by the plugin developer. Plugin documentation should explain what is the syntax of this query text, and what it allows.

Normally, Query implementations involve parsing and decoding this input string into something meaningful for the media provider (a specific operation with its parameters).

Usually, Query implementations are intended to provide advanced filtering capabilities and similar features that make use of specific features of the service that cannot be exposed through more service agnostic APIs, like Search or Browse. For example, a plugin that provides media content stored in a database can implement Query to give users the possibility to execute SQL queries directly, by encoding the SQL commands in this input string, giving a lot of flexibility in how they access the content stored in the database in exchange for writing plugin-specific code in the application.

The example below shows the case of a plugin implementing Query to let the user specify filters directly in SQL format for additional flexibility.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->query = grl_foo_source_query;
}

static void
grl_foo_source_query (GrlSource *source, GrlSourceQuerySpec *qs)
{
  const gchar *sql_filter;
  GList *results;
  GrlMedia *media;
  gint count;

  /* In this example, we are assuming qs->query is expected to contain a
  suitable SQL filter */
  sql_query = prepare_sql_with_custom_filter (qs->query,
                                              grl_operation_options_get_skip (qs->options),
                                              grl_operation_options_get_skip (qs->options));
  /* Execute the resulting SQL query, which incorporates
     the filter provided by the user */
  results = execute_sql (sql_query);

  /* For each result obtained, invoke the user callback as usual */
  count = g_list_length (results);

  if (count == 0) {
    /* Signal "no results" */
    qs->callback (qs->source, qs->operation_id,
                  NULL, 0, qs->user_data, NULL);
  } else {
    while (media = next_result (&results))
      qs->callback (qs->source,       /* Source emitting the data */
                    qs->operation_id, /* Operation identifier */
                    media,            /* Media that matched the query */
                    --count,          /* Remaining count */
                    qs->user_data,    /* User data for the callback */
                    NULL);            /* GError instance (if an error occurred) */
  }
}

Please, check Common considerations for Search, Browse and Query implementations for more information on how to implement Query operations properly.

Examples of plugins implementing Query are grl-jamendo, grl-upnp or grl-bookmarks among others.

Common considerations for Search, Browse and Query implementations

• Making operations synchronous would block the client application while the operation is executed, so providing a non-blocking implementation is mostly mandatory for most practical purposes.
• Grilo invokes plugin operations in idle callbacks to ensure that control is returned to the client as soon as possible. Still, plugin developers are encouraged to write efficient code that avoids blocking as much as possible, since this good practice will make applications behave smoother, granting a much better user experience. Use of threads in plugin code is not recommended, instead, splitting the work to do in chunks using the idle loop is encouraged.
• Creating GrlMedia instances is easy, you should instantiate one, and then use the API to set the corresponding data. Check the GrlData hierarchy in the API reference for more details.
• The remaining count parameter present in the callbacks is intended to provide the client with an estimation of how many more results will come after the current one as part of the same operation.
• Finalization of the operation must always be signaled by invoking the user callback with remaining count set to 0, even on error conditions.
• Plugin developers must ensure that all operations end by invoking the user callback with the remaining count parameter set to 0, and that this is done only once per operation. This behavior is expected and must be guaranteed by the plugin developer.
• Once the user callback has been invoked with the remaining count parameter set to 0, the operations is considered finished and the plugin developer must never invoke the user callback again for that operation again.
• In case of error, the plugin developer must invoke the user callback like this:
  • Set the last parameter to a non-NULL GError instance.
  • Set the media parameter to NULL.
  • Set the remaining count parameter to 0.
  • The plugin developer is responsible for releasing the error once the user callback is invoked.
• It is possible to finalize the operation with a NULL media and remaining count set to 0 if that is convenient for the plugin developer.
• Returned GrlMedia objects are owned by the client and should not be freed by the plugin.
• The list of metadata information requested by the client is available in the “keys” field of the Spec structure. Typically plugin developers don’t have to care about the list of keys requested and would just resolve all metadata available. The only situation in which the plugin developer should check the specific list of keys requested is when there are keys that are particularly expensive to resolve, in these cases the plugin should only resolve these keys if the user has indeed requested that information.

Implementing Resolve

Resolve operations are issued in order to grab additional information on a given media (GrlMedia).

Typically, the use case for Resolve operations is applications obtaining a list of GrlMedia objects by executing a Browse, Search or Query operation, requesting limited metadata (for performance reasons), and then requesting additional metadata for specific items selected by the user.

This additional information can be provided by the same source that got the GrlMedia objects (if it implements the Resolve operation), or by other sources able to provide the information requested.

Plugins implementing “resolve” operation should implement “may_resolve” too. The purpose of this method is to analyze if the GrlMedia contains the required metadata for the source to provide the additional metadata requested. If not provided, the default behaviour for sources implementing “resolve” but not “may_resolve” is to resolve only supported keys in media objects coming from the source itself.

/* In this example we assume a plugin that can resolve thumbnail
   information for audio items given that we have artist and album
   information available  */

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->may_resolve = grl_foo_source_may_resolve;
  source_class->resolve = grl_foo_source_resolve;
}

static gboolean
grl_foo_source_may_resolve (GrlSource *source,
                            GrlMedia *media,
                            GrlKeyID key_id,
                            GList **missing_keys)
{
  gboolean needs_artist = FALSE;
  gboolean needs_album  = FALSE;

  /* We only support thumbnail resolution */
  if (key_id != GRL_METADATA_KEY_THUMBNAIL)
    return FALSE;

  /* We only support audio items */
  if (media) {
    if (!grl_media_is_audio (media))
      return FALSE;

    /* We need artist information available */
    if (grl_media_get_artist (media) == NULL) {
      if (missing_keys)
        *missing_keys = g_list_add (*missing_keys,
                                    GRLKEYID_TO_POINTER (GRL_METADATA_KEY_ARTIST));
      needs_artist = TRUE;
    }

    /* We need album information available */
    if (grl_media_get_album (media) == NULL)) {
      if (missing_keys)
        *missing_keys = g_list_add (*missing_keys,
                                    GRLKEYID_TO_POINTER (GRL_METADATA_KEY_ALBUM));
      needs_album = TRUE;
    }
  }

  if (needs_album || needs_artist)
    return FALSE;

  return TRUE;
}

static void
grl_foo_source_resolve (GrlSource *source,
                        GrlSourceResolveSpec *rs)
{
  const gchar *album;
  const gchar *artist,
  gchar *thumb_uri;
  const GError *error = NULL;

  if (contains_key (rs->keys, GRL_METADATA_KEY_THUMBNAIL) {
    artist = grl_media_get_artist (rs->media);
    album = grl_media_get_album (rs->media);
    if (artist && album) {
      thumb_uri = resolve_thumb_uri (artist, album);
      grl_media_set_thumbnail (rs->media, thumb_uri);
    } else {
      error = g_error_new (GRL_CORE_ERROR,
                           GRL_CORE_ERROR_RESOLVE_FAILED,
                           "Can't resolve thumbnail, artist and album not known");
    }
  } else {
      error = g_error_new (GRL_CORE_ERROR,
                           GRL_CORE_ERROR_RESOLVE_FAILED,
                           "Can't resolve requested keys");
  }

  rs->callback (source, rs->operation_id, rs->media, rs->user_data, error);

  if (error)
    g_error_free (error);
}

Some considerations that plugin developers should take into account:

• The method may_resolve is synchronous, should be fast and never block. If the plugin cannot confirm if it can resolve the metadata requested without doing blocking operations then it should return TRUE. Then, when resolve is invoked further checking can be done.
• Just like in other APIs, implementation of this method is expected to be asynchronous to avoid blocking the user code.

Examples of plugins implementing Resolve are grl-youtube, grl-upnp or grl-lastfm-albumart among others.

Implementing Store

The Store method is used to push new content to the media source.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlMediaSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->store = grl_foo_source_store;
}

static void
grl_foo_source_store (GrlSource *source,
                      GrlSourceStoreSpec *ss)
{
  const gchar *title;
  const gchar *uri;
  const gchar *parent_id;
  guint row_id;

  /* We get the id of the parent container where we want
     to put the new content */
  parent_id = grl_media_get_id (GRL_MEDIA (parent));

  /* We get he metadata of the media we want to push, in this case
     only URI and Title */
  uri = grl_media_get_uri ();
  title = grl_media_get_title ();

  /* Push the data to the media provider (in this case a database) */
  row_id = run_sql_insert (parent_id, uri, title);

  /* Set the media id in the GrlMedia object */
  grl_media_set_id (ss->media, row_id_to_media_id (row_id));

  /* Inform the user that the operation is done (NULL error means everything was
     ok), and all the keys were stored successfully (no list of failed keys) */
  ss->callback (ss->source, ss->media, NULL, ss->user_data, NULL);
}

Some considerations that plugin developers should take into account:

• After successfully storing the media, the method should assign a proper media id to it before invoking the user callback.

Examples of plugins implementing Store are grl-bookmarks or grl-podcasts.

Implementing Store Metadata

Some plugins may provide users with the option of updating the metadata available for specific media items. For example, a plugin may store user metadata like the last time that a certain media resource was played or its play count. These metadata properties do not make sense if applications do not have means to change and update their values.

Plugins that support this feature must implement two methods:

• writable_keys: just like supported_keys or slow_keys, it is a declarative method, intended to provide information on what keys supported by the plugin are writable, that is, their values can be changed by the user.
• store_metadata: which is the method used by clients to update metadata values for specific keys.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->writable_keys = grl_foo_source_writable_keys;
  source_class->store_metadata = grl_foo_source_store_metadata;
}

static const GList *
grl_foo_source_writable_keys (GrlSource *source)
{
  static GList *keys = NULL;
  if (!keys) {
    keys = grl_metadata_key_list_new (GRL_METADATA_KEY_RATING,
                                      GRL_METADATA_KEY_PLAY_COUNT,
                                      GRL_METADATA_KEY_LAST_PLAYED,
                                      NULL);
  }
  return keys;
}

static void
grl_foo_source_store_metadata (GrlSource *source,
                               GrlSourceSetMetadataSpec *sms)
{
  GList *iter;
  const gchar *media_id;
  GList *failed_keys = NULL;

  /* 'sms->media' contains the media with updated values */
  media_id = grl_media_get_id (sms->media);

  /* Go through all the keys that need update ('sms->keys'), take
     the new values (from 'sms->media') and update them in the
     media provider  */
  iter = sms->keys;
  while (iter) {
    GrlKeyID key = GRLPOINTER_TO_KEYID (iter->data);
    if (!foo_update_value_for_key (sms->media, key)) {
      /* Save a list with keys that we failed to update */
      failed_keys = g_list_prepend (failed_keys, iter->data);
    }
    iter = g_list_next (iter);
  }

  /* We are done, invoke user callback to signal client */
  sms->callback (sms->source, sms->media, failed_keys, sms->user_data, NULL);
  g_list_free (failed_keys);
}

Some considerations that plugin developers should take into account:

• Typically, updating metadata keys in the media provider would involve one or more blocking operations, so asynchronous implementations of store_metadata should be considered.
• Some media providers may allow for the possibility of updating multiple keys in just one operation. The user callback for store_metadata receives a list with all the keys that failed to be updated, which the plugin should free after calling the user callback.

Examples of plugins implementing store_metadata are grl-metadata-store or grl-tracker.

Implementing Remove

The Remove method is used to remove content from the media source.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->remove = grl_foo_source_remove;
}

static void
grl_foo_source_remove (GrlSource *source,
                       GrlSourceRemoveSpec *rs)
{
  /* Remove the data from the media provider (in this case a database) */
  run_sql_delete (ss->media_id);

  /* Inform the user that the operation is done (NULL error means everything
     was ok */
  rs->callback (rs->source, rs->media, rs->user_data, NULL);
}

Examples of plugins implementing Remove are grl-bookmarks or grl-podcasts.

Implementing Media from URI

Some times clients have access to the URI of the media, and they want to retrieve metadata for it. A couple of examples where this may come in handy: A file system browser that needs to obtain additional metadata for a particular media item located in the filesystem. A browser plugin that can obtain additional metadata for a media item given its URL. In these cases we know the URI of the media, but we need to create a GrlMedia object representing it.

Plugins that want to support URI to GrlMedia conversions must implement the test_media_from_uri and media_from_uri methods.

The method test_media_from_uri should return TRUE if, upon inspection of the media URI, the plugin decides that it can convert it to a GrlMedia object. For example, a YouTube plugin would check that the URI of the media is a valid YouTube URL. This method is asynchronous and should not block. If the plugin cannot decide if it can or cannot convert the URI to a GrlMedia object by inspecting the URI without doing blocking operations, it should return TRUE. This method is used to discard efficiently plugins that cannot resolve the media.

The method media_from_uri is used to do the actual conversion from the URI to the GrlMedia object.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->test_media_from_uri = grl_foo_source_test_media_from_uri;
  source_class->media_from_uri = grl_foo_source_media_from_uri;
}

static gboolean
grl_filesystem_test_media_from_uri (GrlSource *source,
                                    const gchar *uri)
{
  if (strstr (uri, "http://media.foo.com/media-info/") == uri) {
    return TRUE;
  }
  return FALSE;
}

static void
grl_filesystem_media_from_uri (GrlSource *source,
                               GrlSourceMediaFromUriSpec *mfus)
{
  gchar *media_id;
  GrlMedia *media;

  media_id = get_media_id_from_uri (mfus->uri);
  media = create_media_from_id (media_id);
  mfus->callback (source, mfus->media_from_uri_id, media, mfus->user_data, NULL);
  g_free (media_id);
}

Some considerations that plugin developers should take into account:

• Typically media_from_uri involves a blocking operation, and hence its implementation should be asynchronous.

Examples of plugins implementing media_from_uri are grl-filesystem or grl-youtube.

Notifying changes

Source can signal clients when available media content has been changed. This is an optional feature.

Plugins supporting content change notification must implement notify_change_start and notify_change_stop, which let the user start or stop content change notification at will.

Once users have activated notifications by invoking notify_change_start, media sources should communicate any changes detected by calling grl_source_notify_change_list() with a list of the media items changed.

Upon calling notify_changes_stop the plugin must stop communicating changes until notify_changes_start is called again.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);
  source_class->notify_change_start = grl_foo_source_notify_change_start;
  source_class->notify_change_stop = grl_foo_source_notify_change_stop;
}

static void
content_changed_cb (GList *changes)
{
  GPtrArray *changed_medias;

  changed_medias = g_ptr_array_sized_new (g_list_length (changes));
  while (media = next_media_from_changes (&changes)) {
    g_ptr_array_add (changed_medias, media);
  }

  grl_source_notify_change_list (source,
                                 changed_medias,
                                 GRL_CONTENT_CHANGED,
                                 FALSE);
}

static gboolean
grl_foo_source_notify_change_start (GrlSource *source,
                                    GError **error)
{
  GrlFooSource *foo_source;

  /* Listen to changes in the media content provider */
  foo_source = GRL_FOO_SOURCE (source);
  foo_source->listener_id = foo_subscribe_listener_new (content_changed_cb);

  return TRUE;
}

static gboolean
grl_foo_source_notify_change_stop (GrlSource *source,
                                   GError **error)
{
  GrlFooSource *foo_source;

  /* Stop listening to changes in the media content provider */
  foo_source = GRL_FOO_SOURCE (source);
  foo_listener_destroy (foo_source->listener_id);

  return TRUE;
}

Please check the GrlSource API reference for more details on how grl_source_notify_change_list() should be used.

Examples of plugins implementing change notification are grl-upnp and grl-tracker among others

Cancelling ongoing operations

Implementing the cancel method is optional, as others. This method provided means for application developers to cancel ongoing operations on metadata sources (and hence, also in media sources).

The cancel method receives the identifier of the operation to be cancelled.

Typically, plugin developers would implement cancellation support by storing relevant information for the cancellation process along with the operation data when this is started, and then retrieving this information when a cancellation request is received.

Grilo provides plugin developers with API to attach arbitrary data to a certain operation given its identifier. These APIs are:

• grl_operation_set_data()
• grl_operation_get_data()

See the API reference documentation for GrlOperation for more details.

static void
grl_foo_source_class_init (GrlFooSourceClass * klass)
{
  GrlSourceClass *source_class = GRL_SOURCE_CLASS (klass);

  source_class->search = grl_foo_source_search;
  source_class->cancel = grl_foo_source_cancel;
}

static void
grl_foo_source_search (GrlSource *source,
                       GrlSourceSearchSpec *ss)
{
  ...
  gint op_handler = foo_service_search_start (ss->text, ...);
  grl_operation_set_data (ss->operation_id,
                          GINT_TO_POINTER (op_handler));
  ...
}

static void
grl_foo_source_cancel (GrlSource *source,
                       guint operation_id)
{
  gint op_handler;

  op_handler =
    GPOINTER_TO_INT (grl_operation_get_data (operation_id));
  if (op_handler > 0) {
    foo_service_search_cancel (op_handler);
  }
}

Some examples of plugins implementing cancellation support are grl-youtube, grl-jamendo or grl-filesystem, among others.

Developers must free any data stored before the operation finishes.