path: root/src/grl-source.h

/*
 * Copyright (C) 2012 Igalia S.L.
 *
 * Contact: Iago Toral Quiroga <itoral@igalia.com>
 *
 * 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; version 2.1 of
 * the License, or (at your option) any later version.
 *
 * 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
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

#if !defined (_GRILO_H_INSIDE_) && !defined (GRILO_COMPILATION)
#error "Only <grilo.h> can be included directly."
#endif

#ifndef _GRL_SOURCE_H_
#define _GRL_SOURCE_H_

#include <grl-metadata-key.h>
#include <grl-media.h>
#include <grl-definitions.h>
#include <grl-plugin.h>
#include <grl-operation-options.h>

#include <glib.h>
#include <glib-object.h>
#include <gio/gio.h>

/* Macros */

#define GRL_TYPE_SOURCE                         \
  (grl_source_get_type ())

#define GRL_SOURCE(obj)                         \
  (G_TYPE_CHECK_INSTANCE_CAST ((obj),           \
                               GRL_TYPE_SOURCE, \
                               GrlSource))

#define GRL_IS_SOURCE(obj)                         \
  (G_TYPE_CHECK_INSTANCE_TYPE ((obj),              \
                               GRL_TYPE_SOURCE))

#define GRL_SOURCE_CLASS(klass)                 \
  (G_TYPE_CHECK_CLASS_CAST((klass),             \
                           GRL_TYPE_SOURCE,     \
                           GrlSourceClass))

#define GRL_IS_SOURCE_CLASS(klass)              \
  (G_TYPE_CHECK_CLASS_TYPE((klass),             \
                           GRL_TYPE_SOURCE))

#define GRL_SOURCE_GET_CLASS(obj)               \
  (G_TYPE_INSTANCE_GET_CLASS ((obj),            \
                              GRL_TYPE_SOURCE,  \
                              GrlSourceClass))

typedef struct _GrlSource        GrlSource;
typedef struct _GrlSourcePrivate GrlSourcePrivate;

struct _GrlSource {

  GObject parent;

  /*< private >*/
  GrlSourcePrivate *priv;

  gpointer _grl_reserved[GRL_PADDING];
};

/**
 * GrlSupportedOps:
 * @GRL_OP_NONE: no operation is supported
 * @GRL_OP_RESOLVE: Fetch specific keys of metadata based on other metadata.
 * @GRL_OP_BROWSE: Retrieve complete sets of #GrlMedia
 * @GRL_OP_SEARCH: Look up for #GrlMedia given a search text
 * @GRL_OP_QUERY:  Look up for #GrlMedia give a service specific query
 * @GRL_OP_STORE: Store content in a service
 * @GRL_OP_STORE_PARENT: Store content as child of a certian parent category.
 * @GRL_OP_STORE_METADATA: Update metadata of a #GrlMedia in a service.
 * @GRL_OP_REMOVE: Remove content from a service.
 * @GRL_OP_MEDIA_FROM_URI: Create a #GrlMedia instance from an URI
 * representing a media resource.
 * @GRL_OP_NOTIFY_CHANGE: Notify about changes in the #GrlSource.
 *
 * Bitwise flags which reflect the kind of operations that a
 * #GrlSource supports.
 */
typedef enum {
  GRL_OP_NONE            = 0,
  GRL_OP_RESOLVE         = 1,
  GRL_OP_BROWSE          = 1 << 1,
  GRL_OP_SEARCH          = 1 << 2,
  GRL_OP_QUERY           = 1 << 3,
  GRL_OP_STORE           = 1 << 4,
  GRL_OP_STORE_PARENT    = 1 << 5,
  GRL_OP_STORE_METADATA  = 1 << 6,
  GRL_OP_REMOVE          = 1 << 7,
  GRL_OP_MEDIA_FROM_URI  = 1 << 8,
  GRL_OP_NOTIFY_CHANGE   = 1 << 9
} GrlSupportedOps;

 /**
 * GrlSupportedMedia:
 * @GRL_SUPPORTED_MEDIA_NONE: no media
 * @GRL_SUPPORTED_MEDIA_AUDIO: audio media
 * @GRL_SUPPORTED_MEDIA_VIDEO: video media
 * @GRL_SUPPORTED_MEDIA_IMAGE: image media
 * @GRL_SUPPORTED_MEDIA_ALL: any media
 */
typedef enum {
  GRL_SUPPORTED_MEDIA_NONE  = 0,
  GRL_SUPPORTED_MEDIA_AUDIO = (1 << 0),
  GRL_SUPPORTED_MEDIA_VIDEO = (1 << 1),
  GRL_SUPPORTED_MEDIA_IMAGE = (1 << 2),
  GRL_SUPPORTED_MEDIA_ALL   = (GRL_SUPPORTED_MEDIA_AUDIO | GRL_SUPPORTED_MEDIA_VIDEO | GRL_SUPPORTED_MEDIA_IMAGE)
} GrlSupportedMedia;

/**
 * GrlSourceChangeType:
 * @GRL_CONTENT_CHANGED: content has changed. It is used when any property of
 * #GrlMedia has changed, or in case of containers, if several children have
 * been added and removed.
 * @GRL_CONTENT_ADDED: new content has been added.
 * @GRL_CONTENT_REMOVED: content has been removed
 *
 * Specifies which kind of change has happened in the plugin
 */
typedef enum {
  GRL_CONTENT_CHANGED,
  GRL_CONTENT_ADDED,
  GRL_CONTENT_REMOVED
} GrlSourceChangeType;

/**
 * GrlSourceResolveCb:
 * @source: a source
 * @operation_id: operation identifier
 * @media: (transfer full): a data transfer object
 * @user_data: user data passed to grl_source_resolve()
 * @error: (nullable): possible #GError generated at processing
 *
 * Prototype for the callback passed to grl_source_resolve(). If the URI did
 * not resolve to a valid media record, @media will be %NULL. If there was an
 * error during resolution, @error will be set.
 *
 * If @media is non-%NULL, ownership of it is transferred to the callback, and
 * it must be freed afterwards using g_object_unref().
 */
typedef void (*GrlSourceResolveCb) (GrlSource *source,
                                    guint operation_id,
                                    GrlMedia *media,
                                    gpointer user_data,
                                    const GError *error);

/**
 * GrlSourceResultCb:
 * @source: a source
 * @operation_id: operation identifier
 * @media: (nullable) (transfer full): a data transfer object
 * @remaining: the number of remaining #GrlMedia to process, or
 * GRL_SOURCE_REMAINING_UNKNOWN if it is unknown
 * @user_data: user data passed to the used method
 * @error: (nullable): possible #GError generated at processing
 *
 * Prototype for the callback passed to the media sources' methods
 */
typedef void (*GrlSourceResultCb) (GrlSource *source,
                                   guint operation_id,
                                   GrlMedia *media,
                                   guint remaining,
                                   gpointer user_data,
                                   const GError *error);

/**
 * GrlSourceRemoveCb:
 * @source: a source
 * @media: (transfer full): a data transfer object
 * @user_data: user data passed to grl_source_remove()
 * @error: (nullable): possible #GError generated at processing
 *
 * Prototype for the callback passed to grl_source_remove()
 */
typedef void (*GrlSourceRemoveCb) (GrlSource *source,
                                   GrlMedia *media,
                                   gpointer user_data,
                                   const GError *error);

/**
 * GrlSourceStoreCb:
 * @source: a source
 * @media: a #GrlMedia transfer object
 * @failed_keys: (element-type GrlKeyID) (transfer none): #GList of
 * keys that could not be updated, if any
 * @user_data: user data
 * @error: (nullable): possible #GError generated
 *
 * Prototype for the callback passed to grl_source_store_foo functions
 */
typedef void (*GrlSourceStoreCb) (GrlSource *source,
                                  GrlMedia *media,
                                  GList *failed_keys,
                                  gpointer user_data,
                                  const GError *error);

/**
 * GrlSourceResolveSpec:
 * @source: a source
 * @operation_id: operation identifier
 * @media: a data transfer object
 * @keys: the #GList of #GrlKeyID<!-- -->s to request
 * @options: options wanted for that operation
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * resolve vmethod.
 */
typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *media;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceResolveSpec;

/**
 * GrlSourceMediaFromUriSpec:
 * @source: a source
 * @operation_id: operation identifier
 * @uri: A URI that can be used to identify a media resource
 * @keys: Metadata keys to resolve
 * @options: options wanted for that operation
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * media_from_uri vmethod.
 */
typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *uri;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceMediaFromUriSpec;

/**
 * GrlSourceBrowseSpec:
 * @source: a source
 * @operation_id: operation identifier
 * @container: a container of data transfer objects
 * @keys: the #GList of #GrlKeyID<!-- -->s to request
 * @options: options wanted for that operation
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * browse vmethod.
 */
typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *container;
  GList *keys;
  GrlOperationOptions *options;
    GrlSourceResultCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceBrowseSpec;

/**
 * GrlSourceSearchSpec:
 * @source: a source
 * @operation_id: operation identifier
 * @text: the text to search
 * @keys: the #GList of #GrlKeyID<!-- -->s to request
 * @options: options wanted for that operation
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * search vmethod.
 */
typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *text;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceSearchSpec;

/**
 * GrlSourceQuerySpec:
 * @source: a source
 * @operation_id: operation identifier
 * @query: the query to process
 * @keys: the #GList of #GrlKeyID<!-- -->s to request
 * @options: options wanted for that operation
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * query vmethod.
 */
typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *query;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceQuerySpec;

/**
 * GrlSourceRemoveSpec:
 * @source: a source
 * @media_id: media identifier to remove
 * @media: a data transfer object
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * store vmethod.
 */
typedef struct {
  GrlSource *source;
  gchar *media_id;
  GrlMedia *media;
  GrlSourceRemoveCb callback;
  gpointer user_data;
  GrlOperationOptions *options;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING - 1];
} GrlSourceRemoveSpec;

/**
 * GrlSourceStoreSpec:
 * @source: a media source
 * @parent: a parent to store the data transfer objects
 * @media: a data transfer object
 * @callback: the user defined callback
 * @user_data: the user data to pass in the callback
 *
 * Data transport structure used internally by the plugins which support
 * store vmethod.
 */
typedef struct {
  GrlSource *source;
  GrlMedia *parent;
  GrlMedia *media;
  GrlSourceStoreCb callback;
  gpointer user_data;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceStoreSpec;

/**
 * GrlSourceStoreMetadataSpec:
 * @source: a source
 * @media: a #GrlMedia transfer object
 * @keys: List of keys to be stored/updated.
 * @flags: Flags to control specific bahviors of the set metadata operation.
 * @callback: the callback passed to grl_source_store_metadata()
 * @user_data: user data passed to grl_source_store_metadata()
 * @failed_keys: for internal use of the framework only.
 *
 * Data transport structure used internally by the plugins which support
 * store_metadata vmethod.
 */
typedef struct {
  GrlSource *source;
  GrlMedia *media;
  GList *keys;
  GrlWriteFlags flags;
  GrlSourceStoreCb callback;
  gpointer user_data;
  GList *failed_keys;

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
} GrlSourceStoreMetadataSpec;

/* GrlSource class */

typedef struct _GrlSourceClass GrlSourceClass;

/**
 * GrlSourceClass:
 * @parent_class: the parent class structure
 * @supported_operations: the operations that can be called
 * @supported_keys: the list of keys that can be handled
 * @slow_keys: the list of slow keys that can be fetched
 * @writable_keys: the list of keys which value can be written
 * @get_caps: the capabilities that @source supports for @operation
 * @resolve: resolve the metadata of a given transfer object
 * @may_resolve: return FALSE if it can be known without blocking that @key_id
 * @test_media_from_uri: tests if this source can create #GrlMedia
 * instances from a given URI.
 * @media_from_uri: Creates a #GrlMedia instance representing the media
 * exposed by a certain URI.
 * @browse: browse through a list of media
 * @search: search for media
 * @query: query for a specific media
 * @remove: remove a media from a container
 * @store: store a media in a container
 * @store_metadata: update metadata values for a given object in a
 * permanent fashion
 * @cancel: cancel the current operation
 * @notify_change_start: start emitting signals about changes in content
 * @notify_change_stop: stop emitting signals about changes in content
 *
 * Grilo Source class. Override the vmethods to implement the
 * element functionality.
 */
struct _GrlSourceClass {

  GObjectClass parent_class;

  GrlSupportedOps (*supported_operations) (GrlSource *source);

  const GList * (*supported_keys) (GrlSource *source);

  const GList * (*slow_keys) (GrlSource *source);

  const GList * (*writable_keys) (GrlSource *source);

  GrlCaps * (*get_caps) (GrlSource *source, GrlSupportedOps operation);

  void (*resolve) (GrlSource *source, GrlSourceResolveSpec *ms);

  gboolean (*may_resolve) (GrlSource *source, GrlMedia *media,
                           GrlKeyID key_id, GList **missing_keys);

  gboolean (*test_media_from_uri) (GrlSource *source,
                                   const gchar *uri);

  void (*media_from_uri) (GrlSource *source,
                          GrlSourceMediaFromUriSpec *mfus);

  void (*browse) (GrlSource *source, GrlSourceBrowseSpec *bs);

  void (*search) (GrlSource *source, GrlSourceSearchSpec *ss);

  void (*query) (GrlSource *source, GrlSourceQuerySpec *qs);

  void (*remove) (GrlSource *source, GrlSourceRemoveSpec *rs);

  void (*store) (GrlSource *source, GrlSourceStoreSpec *ss);

  void (*store_metadata) (GrlSource *source, GrlSourceStoreMetadataSpec *sms);

  void (*cancel) (GrlSource *source, guint operation_id);

  gboolean (*notify_change_start) (GrlSource *source,
                                    GError **error);

  gboolean (*notify_change_stop) (GrlSource *source,
                                  GError **error);

  /*< private >*/
  gpointer _grl_reserved[GRL_PADDING];
};

G_BEGIN_DECLS

GType grl_source_get_type (void);

GrlSupportedOps grl_source_supported_operations (GrlSource *source);

const GList *grl_source_supported_keys (GrlSource *source);

const GList *grl_source_slow_keys (GrlSource *source);

const GList *grl_source_writable_keys (GrlSource *source);

GrlCaps *grl_source_get_caps (GrlSource *source,
                              GrlSupportedOps operation);

void grl_source_set_auto_split_threshold (GrlSource *source,
                                          guint threshold);

guint grl_source_get_auto_split_threshold (GrlSource *source);


guint grl_source_resolve (GrlSource *source,
                          GrlMedia *media,
                          const GList *keys,
                          GrlOperationOptions *options,
                          GrlSourceResolveCb callback,
                          gpointer user_data);

GrlMedia *grl_source_resolve_sync (GrlSource *source,
                                   GrlMedia *media,
                                   const GList *keys,
                                   GrlOperationOptions *options,
                                   GError **error);

gboolean grl_source_may_resolve (GrlSource *source,
                                 GrlMedia *media,
                                 GrlKeyID key_id,
                                 GList **missing_keys);

gboolean grl_source_test_media_from_uri (GrlSource *source,
                                         const gchar *uri);

guint grl_source_get_media_from_uri (GrlSource *source,
                                     const gchar *uri,
                                     const GList *keys,
                                     GrlOperationOptions *options,
                                     GrlSourceResolveCb callback,
                                     gpointer user_data);

GrlMedia *grl_source_get_media_from_uri_sync (GrlSource *source,
                                              const gchar *uri,
                                              const GList *keys,
                                              GrlOperationOptions *options,
                                              GError **error);

guint grl_source_browse (GrlSource *source,
                         GrlMedia *container,
                         const GList *keys,
                         GrlOperationOptions *options,
                         GrlSourceResultCb callback,
                         gpointer user_data);

GList *grl_source_browse_sync (GrlSource *source,
                               GrlMedia *container,
                               const GList *keys,
                               GrlOperationOptions *options,
                               GError **error);

guint grl_source_search (GrlSource *source,
                         const gchar *text,
                         const GList *keys,
                         GrlOperationOptions *options,
                         GrlSourceResultCb callback,
                         gpointer user_data);

GList *grl_source_search_sync (GrlSource *source,
                               const gchar *text,
                               const GList *keys,
                               GrlOperationOptions *options,
                               GError **error);

guint grl_source_query (GrlSource *source,
                        const gchar *query,
                        const GList *keys,
                        GrlOperationOptions *options,
                        GrlSourceResultCb callback,
                        gpointer user_data);

GList *grl_source_query_sync (GrlSource *source,
                              const gchar *query,
                              const GList *keys,
                              GrlOperationOptions *options,
                              GError **error);

void grl_source_remove (GrlSource *source,
                        GrlMedia *media,
                        GrlSourceRemoveCb callback,
                        gpointer user_data);

void grl_source_remove_sync (GrlSource *source,
                             GrlMedia *media,
                             GError **error);

void grl_source_remove_with_options (GrlSource *source,
                                     GrlMedia *media,
                                     GrlOperationOptions *options,
                                     GrlSourceRemoveCb callback,
                                     gpointer user_data);

void grl_source_remove_with_options_sync (GrlSource *source,
                                          GrlMedia *media,
                                          GrlOperationOptions *options,
                                          GError **error);

void grl_source_store (GrlSource *source,
                       GrlMedia *parent,
                       GrlMedia *media,
                       GrlWriteFlags flags,
                       GrlSourceStoreCb callback,
                       gpointer user_data);

void grl_source_store_sync (GrlSource *source,
                            GrlMedia *parent,
                            GrlMedia *media,
                            GrlWriteFlags flags,
                            GError **error);

void grl_source_store_metadata (GrlSource *source,
                                GrlMedia *media,
                                GList *keys,
                                GrlWriteFlags flags,
                                GrlSourceStoreCb callback,
                                gpointer user_data);

GList *grl_source_store_metadata_sync (GrlSource *source,
                                       GrlMedia *media,
                                       GList *keys,
                                       GrlWriteFlags flags,
                                       GError **error);

gboolean grl_source_notify_change_start (GrlSource *source,
                                         GError **error);

gboolean grl_source_notify_change_stop (GrlSource *source,
                                        GError **error);

void grl_source_notify_change_list (GrlSource *source,
                                    GPtrArray *changed_medias,
                                    GrlSourceChangeType change_type,
                                    gboolean location_unknown);

void grl_source_notify_change (GrlSource *source,
                               GrlMedia *media,
                               GrlSourceChangeType change_type,
                               gboolean location_unknown);

const gchar *grl_source_get_id (GrlSource *source);

const gchar *grl_source_get_name (GrlSource *source);

GIcon *grl_source_get_icon (GrlSource *source);

const gchar *grl_source_get_description (GrlSource *source);

GrlPlugin *grl_source_get_plugin (GrlSource *source);

gint grl_source_get_rank (GrlSource *source);

GrlSupportedMedia grl_source_get_supported_media (GrlSource *source);

const char ** grl_source_get_tags (GrlSource *source);

G_END_DECLS

#endif /* _GRL_SOURCE_H_ */