GrlSource

GrlSource — Abstract base class for sources

Synopsis

#include <grilo.h>

struct              GrlSource;
struct              GrlSourceClass;
enum                GrlResolutionFlags;
                    GrlSourceBrowseSpec;
enum                GrlSourceChangeType;
                    GrlSourceMediaFromUriSpec;
                    GrlSourceQuerySpec;
void                (*GrlSourceRemoveCb)                (GrlSource *source,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);
                    GrlSourceRemoveSpec;
void                (*GrlSourceResolveCb)               (GrlSource *source,
                                                         guint operation_id,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);
                    GrlSourceResolveSpec;
void                (*GrlSourceResultCb)                (GrlSource *source,
                                                         guint operation_id,
                                                         GrlMedia *media,
                                                         guint remaining,
                                                         gpointer user_data,
                                                         const GError *error);
                    GrlSourceSearchSpec;
void                (*GrlSourceStoreCb)                 (GrlSource *source,
                                                         GrlMedia *media,
                                                         GList *failed_keys,
                                                         gpointer user_data,
                                                         const GError *error);
                    GrlSourceStoreMetadataSpec;
                    GrlSourceStoreSpec;
enum                GrlSupportedOps;
enum                GrlWriteFlags;
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_get_auto_split_threshold (GrlSource *source);
GrlCaps *           grl_source_get_caps                 (GrlSource *source,
                                                         GrlSupportedOps operation);
const gchar *       grl_source_get_description          (GrlSource *source);
const gchar *       grl_source_get_id                   (GrlSource *source);
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);
const gchar *       grl_source_get_name                 (GrlSource *source);
GrlPlugin *         grl_source_get_plugin               (GrlSource *source);
gint                grl_source_get_rank                 (GrlSource *source);
GrlMediaType        grl_source_get_supported_media      (GrlSource *source);
gboolean            grl_source_may_resolve              (GrlSource *source,
                                                         GrlMedia *media,
                                                         GrlKeyID key_id,
                                                         GList **missing_keys);
void                grl_source_notify_change            (GrlSource *source,
                                                         GrlMedia *media,
                                                         GrlSourceChangeType change_type,
                                                         gboolean location_unknown);
void                grl_source_notify_change_list       (GrlSource *source,
                                                         GPtrArray *changed_medias,
                                                         GrlSourceChangeType change_type,
                                                         gboolean location_unknown);
gboolean            grl_source_notify_change_start      (GrlSource *source,
                                                         GError **error);
gboolean            grl_source_notify_change_stop       (GrlSource *source,
                                                         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);
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);
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);
void                grl_source_set_auto_split_threshold (GrlSource *source,
                                                         guint threshold);
const GList *       grl_source_slow_keys                (GrlSource *source);
void                grl_source_store                    (GrlSource *source,
                                                         GrlMediaBox *parent,
                                                         GrlMedia *media,
                                                         GrlWriteFlags flags,
                                                         GrlSourceStoreCb callback,
                                                         gpointer user_data);
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);
void                grl_source_store_sync               (GrlSource *source,
                                                         GrlMediaBox *parent,
                                                         GrlMedia *media,
                                                         GrlWriteFlags flags,
                                                         GError **error);
const GList *       grl_source_supported_keys           (GrlSource *source);
GrlSupportedOps     grl_source_supported_operations     (GrlSource *source);
gboolean            grl_source_test_media_from_uri      (GrlSource *source,
                                                         const gchar *uri);
const GList *       grl_source_writable_keys            (GrlSource *source);

Object Hierarchy

  GObject
   +----GrlSource

Properties

  "auto-split-threshold"     guint                 : Read / Write
  "plugin"                   GrlPlugin*            : Read / Write / Construct
  "rank"                     gint                  : Read / Write / Construct
  "source-desc"              gchar*                : Read / Write / Construct
  "source-id"                gchar*                : Read / Write / Construct
  "source-name"              gchar*                : Read / Write / Construct
  "supported-media"          GrlMediaType          : Read / Write / Construct

Signals

  "content-changed"                                : Action

Description

GrlSource is the abstract base class needed to construct a source providing multimedia information that can be used in a Grilo application.

The sources fetch information from different online or local databases and store them in the GrlMedia.

Details

struct GrlSource

struct GrlSource;

struct GrlSourceClass

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 *ss);

  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);
};

Grilo Source class. Override the vmethods to implement the element functionality.

GObjectClass 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

enum GrlResolutionFlags

typedef enum {
  GRL_RESOLVE_NORMAL     = 0,        /* Normal mode */
  GRL_RESOLVE_FULL       = (1 << 0), /* Try other plugins if necessary */
  GRL_RESOLVE_IDLE_RELAY = (1 << 1), /* Use idle loop to relay results */
  GRL_RESOLVE_FAST_ONLY  = (1 << 2)  /* Only resolve fast metadata keys */
} GrlResolutionFlags;

Resolution flags

GRL_RESOLVE_NORMAL

Normal mode.

GRL_RESOLVE_FULL

Try other plugins if necessary.

GRL_RESOLVE_IDLE_RELAY

Use idle loop to relay results.

GRL_RESOLVE_FAST_ONLY

Only resolve fast metadata keys.

GrlSourceBrowseSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *container;
  GList *keys;
  GrlOperationOptions *options;
    GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceBrowseSpec;

Data transport structure used internally by the plugins which support browse vmethod.

GrlSource *source;

a source

guint operation_id;

operation identifier

GrlMedia *container;

a container of data transfer objects

GList *keys;

the GList of GrlKeyIDs to request

GrlOperationOptions *options;

options wanted for that operation

GrlSourceResultCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

enum GrlSourceChangeType

typedef enum {
  GRL_CONTENT_CHANGED,
  GRL_CONTENT_ADDED,
  GRL_CONTENT_REMOVED
} GrlSourceChangeType;

Specifies which kind of change has happened in the plugin

GRL_CONTENT_CHANGED

content has changed. It is used when any property of GrlMedia has changed, or in case of GrlMediaBox, if several children have been added and removed.

GRL_CONTENT_ADDED

new content has been added.

GRL_CONTENT_REMOVED

content has been removed

GrlSourceMediaFromUriSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *uri;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;
} GrlSourceMediaFromUriSpec;

Data transport structure used internally by the plugins which support media_from_uri vmethod.

GrlSource *source;

a source

guint operation_id;

operation identifier

gchar *uri;

A URI that can be used to identify a media resource

GList *keys;

Metadata keys to resolve

GrlOperationOptions *options;

options wanted for that operation

GrlSourceResolveCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

GrlSourceQuerySpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *query;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceQuerySpec;

Data transport structure used internally by the plugins which support query vmethod.

GrlSource *source;

a source

guint operation_id;

operation identifier

gchar *query;

the query to process

GList *keys;

the GList of GrlKeyIDs to request

GrlOperationOptions *options;

options wanted for that operation

GrlSourceResultCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

GrlSourceRemoveCb ()

void                (*GrlSourceRemoveCb)                (GrlSource *source,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);

Prototype for the callback passed to grl_source_remove()

source :

a source

media :

a data transfer object. [transfer full]

user_data :

user data passed to grl_source_remove()

error :

possible GError generated at processing. [type uint]

GrlSourceRemoveSpec

typedef struct {
  GrlSource *source;
  gchar *media_id;
  GrlMedia *media;
  GrlSourceRemoveCb callback;
  gpointer user_data;
} GrlSourceRemoveSpec;

Data transport structure used internally by the plugins which support store vmethod.

GrlSource *source;

a source

gchar *media_id;

media identifier to remove

GrlMedia *media;

a data transfer object

GrlSourceRemoveCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

GrlSourceResolveCb ()

void                (*GrlSourceResolveCb)               (GrlSource *source,
                                                         guint operation_id,
                                                         GrlMedia *media,
                                                         gpointer user_data,
                                                         const GError *error);

Prototype for the callback passed to grl_source_resolve()

source :

a source

operation_id :

operation identifier

media :

a data transfer object. [transfer full]

user_data :

user data passed to grl_source_resolve()

error :

possible GError generated at processing. [type uint]

GrlSourceResolveSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  GrlMedia *media;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResolveCb callback;
  gpointer user_data;
} GrlSourceResolveSpec;

Data transport structure used internally by the plugins which support resolve vmethod.

GrlSource *source;

a source

guint operation_id;

operation identifier

GrlMedia *media;

a data transfer object

GList *keys;

the GList of GrlKeyIDs to request

GrlOperationOptions *options;

options wanted for that operation

GrlSourceResolveCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

GrlSourceResultCb ()

void                (*GrlSourceResultCb)                (GrlSource *source,
                                                         guint operation_id,
                                                         GrlMedia *media,
                                                         guint remaining,
                                                         gpointer user_data,
                                                         const GError *error);

Prototype for the callback passed to the media sources' methods

source :

a source

operation_id :

operation identifier

media :

a data transfer object. [transfer full]

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 :

possible GError generated at processing. [type uint]

GrlSourceSearchSpec

typedef struct {
  GrlSource *source;
  guint operation_id;
  gchar *text;
  GList *keys;
  GrlOperationOptions *options;
  GrlSourceResultCb callback;
  gpointer user_data;
} GrlSourceSearchSpec;

Data transport structure used internally by the plugins which support search vmethod.

GrlSource *source;

a source

guint operation_id;

operation identifier

gchar *text;

the text to search

GList *keys;

the GList of GrlKeyIDs to request

GrlOperationOptions *options;

options wanted for that operation

GrlSourceResultCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

GrlSourceStoreCb ()

void                (*GrlSourceStoreCb)                 (GrlSource *source,
                                                         GrlMedia *media,
                                                         GList *failed_keys,
                                                         gpointer user_data,
                                                         const GError *error);

Prototype for the callback passed to grl_source_store_foo functions

source :

a source

media :

a GrlMedia transfer object. [transfer full]

failed_keys :

GList of keys that could not be updated, if any. [element-type GrlKeyID][transfer none]

user_data :

user data

error :

possible GError generated. [type uint]

GrlSourceStoreMetadataSpec

typedef struct {
  GrlSource *source;
  GrlMedia *media;
  GList *keys;
  GrlWriteFlags flags;
  GrlSourceStoreCb callback;
  gpointer user_data;
  GList *failed_keys;
} GrlSourceStoreMetadataSpec;

Data transport structure used internally by the plugins which support store_metadata vmethod.

GrlSource *source;

a source

GrlMedia *media;

a GrlMedia transfer object

GList *keys;

List of keys to be stored/updated.

GrlWriteFlags flags;

Flags to control specific bahviors of the set metadata operation.

GrlSourceStoreCb callback;

the callback passed to grl_source_store_metadata()

gpointer user_data;

user data passed to grl_source_store_metadata()

GList *failed_keys;

for internal use of the framework only.

GrlSourceStoreSpec

typedef struct {
  GrlSource *source;
  GrlMediaBox *parent;
  GrlMedia *media;
  GrlSourceStoreCb callback;
  gpointer user_data;
} GrlSourceStoreSpec;

Data transport structure used internally by the plugins which support store vmethod.

GrlSource *source;

a media source

GrlMediaBox *parent;

a parent to store the data transfer objects

GrlMedia *media;

a data transfer object

GrlSourceStoreCb callback;

the user defined callback

gpointer user_data;

the user data to pass in the callback

enum GrlSupportedOps

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;

Bitwise flags which reflect the kind of operations that a GrlSource supports.

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 GrlMediaSource.

enum GrlWriteFlags

typedef enum {
  GRL_WRITE_NORMAL     = 0,        /* Normal mode */
  GRL_WRITE_FULL       = (1 << 0)  /* Try other plugins if necessary */
} GrlWriteFlags;

Flags for writing operations.

GRL_WRITE_NORMAL

Normal mode.

GRL_WRITE_FULL

Try other plugins if necessary.

grl_source_browse ()

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

Browse from media elements through an available list.

This method is asynchronous.

source :

a source

container :

a container of data transfer objects. [allow-none]

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Returns :

the operation identifier

Since 0.2.0


grl_source_browse_sync ()

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

Browse media elements through an available list.

This method is synchronous.

source :

a source

container :

a container of data transfer objects. [allow-none]

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

error :

a GError, or NULL

Returns :

a GList with GrlMedia elements. After use g_object_unref() every element and g_list_free() the list. [element-type Grl.Media][transfer full]

Since 0.2.0


grl_source_get_auto_split_threshold ()

guint               grl_source_get_auto_split_threshold (GrlSource *source);

Gets how much elements the source is able to handle in a single request.

See #grl_source_set_auto_split_threshold()

source :

a source

Returns :

the assigned threshold, or 0 if there is no threshold

Since 0.2.0


grl_source_get_caps ()

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

Get the capabilities of source for operation.

source :

a source

operation :

a supported operation. Even though the type allows to specify several operations, only one should be provided here.

Returns :

The capabilities. [transfer none]

Since 0.2.0


grl_source_get_description ()

const gchar *       grl_source_get_description          (GrlSource *source);

source :

a source

Returns :

the description of the source

Since 0.2.0


grl_source_get_id ()

const gchar *       grl_source_get_id                   (GrlSource *source);

source :

a source

Returns :

the ID of the source

Since 0.2.0


grl_source_get_media_from_uri ()

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

Creates an instance of GrlMedia representing the media resource exposed at uri.

It is recommended to call grl_source_test_media_from_uri() before invoking this to check whether the target source can theoretically do the resolution.

This method is asynchronous.

source :

a source

uri :

A URI that can be used to identify a media resource

keys :

A list of keys to resolve. [element-type GrlKeyID]

options :

options wanted for that operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Returns :

the operation identifier

Since 0.2.0


grl_source_get_media_from_uri_sync ()

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

Creates an instance of GrlMedia representing the media resource exposed at uri.

It is recommended to call grl_source_test_media_from_uri() before invoking this to check whether the target source can theoretically do the resolution.

This method is synchronous.

source :

a source

uri :

A URI that can be used to identify a media resource

keys :

a list of keys to resolve. [element-type GrlKeyID]

options :

options wanted for that operation

error :

a GError, or NULL

Returns :

a filled GrlMedia. [transfer full]

Since 0.2.0


grl_source_get_name ()

const gchar *       grl_source_get_name                 (GrlSource *source);

source :

a source

Returns :

the name of the source

Since 0.2.0


grl_source_get_plugin ()

GrlPlugin *         grl_source_get_plugin               (GrlSource *source);

source :

a source

Returns :

the plugin this source belongs to. [transfer none]

Since 0.2.0


grl_source_get_rank ()

gint                grl_source_get_rank                 (GrlSource *source);

Gets the source rank

source :

a source

Returns :

rank value

Since 0.2.0


grl_source_get_supported_media ()

GrlMediaType        grl_source_get_supported_media      (GrlSource *source);

Gets the supported type of medias source can deal with.

source :

a source

Returns :

a GrlMediaType value

Since 0.2.3


grl_source_may_resolve ()

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

Checks whether key_id may be resolved with source for media, so that the caller can avoid calling grl_source_resolve() if it can be known in advance it will fail.

If the resolution is known to be impossible because more keys are needed in media, and missing_keys is not NULL, it is populated with the list of GrlKeyID that would be needed.

This function is synchronous and should not block.

source :

a source

media :

a media on which we want more metadata

key_id :

the key corresponding to a metadata we might want

missing_keys :

an optional originally empty list. [element-type GrlKeyID]

Returns :

TRUE if there's a possibility that source resolves key_id for media, FALSE otherwise.

Since 0.2.0


grl_source_notify_change ()

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

Emits "content-changed" signal to notify subscribers that a change ocurred in source.

See #grl_source_notify_change_list() function.

Note

This function is intended to be used only by plugins.

source :

a source

media :

the media which has changed, or NULL to use the root box. [allow-none]

change_type :

the type of change

location_unknown :

if change has happened in media or any descendant

Since 0.2.0


grl_source_notify_change_list ()

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

Emits "content-changed" signal to notify subscribers that a change ocurred in source.

The function will take ownership of changed medias and it should not be manipulated in any way by the caller after invoking this function. If that is needed, the caller must ref the array in advance.

See GrlSource::content-changed signal.

Note

This function is intended to be used only by plugins.

source :

a source

changed_medias :

: the list of medias that have changed. [element-type Grl.Media][transfer full]

change_type :

the type of change

location_unknown :

if change has happpened in media or any descendant

Since 0.2.0


grl_source_notify_change_start ()

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

Starts emitting ::content-changed signals when source discovers changes in the content. This instructs source to setup the machinery needed to be aware of changes in the content.

source :

a source

error :

a GError, or NULL

Returns :

TRUE if initialization has succeed.

Since 0.2.0


grl_source_notify_change_stop ()

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

This will drop emission of ::content-changed signals from source. When this is done source should stop the machinery required for it to track changes in the content.

source :

a source

error :

a GError, or NULL

Returns :

TRUE if stop has succeed.

Since 0.2.0


grl_source_query ()

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

Execute a specialized query (specific for each provider) on a media repository.

It is different from grl_source_search() semantically, because the query implies a carefully crafted string, rather than a simple string to search.

This method is asynchronous.

source :

a source

query :

the query to process

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Returns :

the operation identifier

Since 0.2.0


grl_source_query_sync ()

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

Execute a specialized query (specific for each provider) on a media repository.

This method is synchronous.

source :

a source

query :

the query to process

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

error :

a GError, or NULL

Returns :

a GList with GrlMedia elements. After use g_object_unref() every element and g_list_free() the list. [element-type Grl.Media][transfer full]

Since 0.2.0


grl_source_remove ()

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

Remove a media from the source repository.

This method is asynchronous.

source :

a source

media :

a data transfer object

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Since 0.2.0


grl_source_remove_sync ()

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

Remove a media from the source repository.

This method is synchronous.

source :

a source

media :

a data transfer object

error :

a GError, or NULL

Since 0.2.0


grl_source_resolve ()

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

This method is intended to fetch the requested keys of metadata of a given media to the media source.

This method is asynchronous.

source :

a source

media :

a data transfer object. [allow-none]

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options to pass to this operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Returns :

the operation identifie

Since 0.2.0


grl_source_resolve_sync ()

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

This method is intended to fetch the requested keys of metadata of a given media to the media source.

This method is synchronous.

source :

a source

media :

a data transfer object. [allow-none]

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options to pass to this operation

error :

a GError, or NULL

Returns :

a filled GrlMedia. [transfer full]

Since 0.2.0


grl_source_search ()

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

Search for the text string in a source for data identified with that string.

If text is NULL then no text filter will be applied, and thus, no media items from source will be filtered. If source does not support NULL-text search operations it should notiy the client by setting GRL_CORE_ERROR_SEARCH_NULL_UNSUPPORTED in callback's error parameter.

This method is asynchronous.

source :

a source

text :

the text to search

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Returns :

the operation identifier

Since 0.2.0


grl_source_search_sync ()

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

Search for the text string in a source for data identified with that string.

If text is NULL then no text filter will be applied, and thus, no media items from source will be filtered. If source does not support NULL-text search operations it should notiy the client by setting GRL_CORE_ERROR_SEARCH_NULL_UNSUPPORTED in the error parameter.

This method is synchronous.

source :

a source

text :

the text to search

keys :

the GList of GrlKeyIDs to request. [element-type GrlKeyID]

options :

options wanted for that operation

error :

a GError, or NULL

Returns :

a GList with GrlMedia elements. After use g_object_unref() every element and g_list_free() the list. [element-type Grl.Media][transfer full]

Since 0.2.0


grl_source_set_auto_split_threshold ()

void                grl_source_set_auto_split_threshold (GrlSource *source,
                                                         guint threshold);

Sets how much elements the source is able to handle in a single request.

If user, during a search or browsing operation, asks for more elements than the threshold, the request will be automatically splitted in chunks, so up to threshold elements will be asked in each request.

Source will act as if user were asking just a chunk, and user won't notice that the request was chunked.

Note

This function is intended to be used only by plugins.

source :

a source

threshold :

the threshold to set

Since 0.2.0


grl_source_slow_keys ()

const GList *       grl_source_slow_keys                (GrlSource *source);

Similar to grl_source_supported_keys(), but these keys are marked as slow because of the amount of traffic/processing needed to fetch them.

source :

a source

Returns :

a GList with the keys. [element-type GrlKeyID][transfer none]

Since 0.2.0


grl_source_store ()

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

Store the media into the parent container

This method is asynchronous.

source :

a source

parent :

a parent to store the data transfer objects. [allow-none]

media :

a data transfer object

flags :

flags to configure specific behaviour of the operation

callback :

the user defined callback. [scope notified]

user_data :

the user data to pass in the callback

Since 0.2.0


grl_source_store_metadata ()

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

This is the main method of the GrlMetadataSource class. It will get the values for keys from media and store it permanently. After calling this method, future queries that return this media object shall return this new values for the selected keys.

This function is asynchronous and uses the Glib's main loop.

source :

a metadata source

media :

the GrlMedia object that we want to operate on.

keys :

a list of GrlKeyID whose values we want to change. [element-type Grl.KeyID][allow-none]

flags :

Flags to configure specific behaviors of the operation.

callback :

the callback to execute when the operation is finished. [scope notified]

user_data :

user data set for the callback

Since 0.2.0


grl_source_store_metadata_sync ()

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

Update keys values from media in the source. After calling this method, future queries that return this media object shall return this new value for the selected key.

This function is synchronous.

source :

a source

media :

the GrlMedia object that we want to operate on

keys :

a list of GrlKeyID whose values we want to change. [element-type GrlKeyID][allow-none]

flags :

Flags to configure specific behaviors of the operation.

error :

a GError, or NULL

Returns :

a GList of keys that could not be updated, or NULL. [element-type GrlKeyID][transfer container]

Since 0.2.0


grl_source_store_sync ()

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

Store the media into the parent container.

This method is synchronous.

source :

a source

parent :

a GrlMediaBox to store the data transfer objects. [allow-none]

media :

a GrlMedia data transfer object

flags :

flags to configure specific behaviour of the operation

error :

a GError, or NULL

Since 0.2.0


grl_source_supported_keys ()

const GList *       grl_source_supported_keys           (GrlSource *source);

Get a list of GrlKeyID, which describe a metadata types that this source can fetch and store.

source :

a source

Returns :

a GList with the keys. [element-type GrlKeyID][transfer none]

Since 0.2.0


grl_source_supported_operations ()

GrlSupportedOps     grl_source_supported_operations     (GrlSource *source);

By default the derived objects of GrlSource can only resolve.

source :

a source

Returns :

a bitwise mangle with the supported operations by the source. [type uint]

Since 0.2.0


grl_source_test_media_from_uri ()

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

Tests whether source can instantiate a GrlMedia object representing the media resource exposed at uri.

source :

a source

uri :

A URI that can be used to identify a media resource

Returns :

TRUE if it can, FALSE otherwise. This method is synchronous.

Since 0.2.0


grl_source_writable_keys ()

const GList *       grl_source_writable_keys            (GrlSource *source);

Similar to grl_source_supported_keys(), but these keys are marked as writable, meaning the source allows the client to provide new values for these keys that will be stored permanently.

source :

a source

Returns :

a GList with the keys. [element-type GrlKeyID][transfer none]

Since 0.2.0

Property Details

The "auto-split-threshold" property

  "auto-split-threshold"     guint                 : Read / Write

Transparently split queries with count requests bigger than a certain threshold into smaller queries.

Default value: 0

Since 0.2.0


The "plugin" property

  "plugin"                   GrlPlugin*            : Read / Write / Construct

Plugin the source belongs to

Since 0.2.0


The "rank" property

  "rank"                     gint                  : Read / Write / Construct

Source rank

Default value: 0

Since 0.2.0


The "source-desc" property

  "source-desc"              gchar*                : Read / Write / Construct

A description of the source

Default value: ""

Since 0.2.0


The "source-id" property

  "source-id"                gchar*                : Read / Write / Construct

The identifier of the source.

Default value: ""

Since 0.2.0


The "source-name" property

  "source-name"              gchar*                : Read / Write / Construct

The name of the source.

Default value: ""

Since 0.2.0


The "supported-media" property

  "supported-media"          GrlMediaType          : Read / Write / Construct

List of supported media types by this source.

Default value: GRL_MEDIA_TYPE_AUDIO|GRL_MEDIA_TYPE_VIDEO|GRL_MEDIA_TYPE_IMAGE

Since 0.2.3

Signal Details

The "content-changed" signal

void                user_function                      (GrlSource          *source,
                                                        GPtrArray          *changed_medias,
                                                        GrlSourceChangeType change_type,
                                                        gboolean            location_unknown,
                                                        gpointer            user_data)             : Action

Signals that the content in the source has changed. changed_medias is the list of elements that have changed. Usually these medias are of type GrlMediaBox, meaning that the content of that box has changed.

If location_unknown is TRUE it means the source cannot establish where the change happened: could be either in the box, in any child, or in any other descendant of the box in the hierarchy.

Both change_type and location_unknown are applied to all elements in the list.

For the cases where the source can only signal that a change happened, but not where, it would use a list with the the root box (NULL id) and set location_unknown as TRUE.

source :

source that has changed

changed_medias :

a GPtrArray with the medias that changed or a common ancestor of them of type GrlMediaBox.

change_type :

the kind of change that ocurred

location_unknown :

TRUE if the change happened in media itself or in one of its direct children (when media is a GrlMediaBox). FALSE otherwise

user_data :

user data set when the signal handler was connected.

Since 0.2.0

See Also

GrlPlugin, GrlSource, GrlMedia