GrlSource: Grilo Reference Manual

## GrlSource GrlSource — Abstract base class for sources |

## Functions

void | (*GrlSourceRemoveCb) ()
void | (*GrlSourceResolveCb) ()
void | (*GrlSourceResultCb) ()
void | (*GrlSourceStoreCb) ()
guint | grl_source_browse ()
GList * | grl_source_browse_sync ()
guint | grl_source_get_auto_split_threshold ()
GrlCaps * | grl_source_get_caps ()
const gchar * | grl_source_get_description ()
GIcon * | grl_source_get_icon ()
const gchar * | grl_source_get_id ()
guint | grl_source_get_media_from_uri ()
GrlMedia * | grl_source_get_media_from_uri_sync ()
const gchar * | grl_source_get_name ()
GrlPlugin * | grl_source_get_plugin ()
gint | grl_source_get_rank ()
GrlSupportedMedia | grl_source_get_supported_media ()
const char ** | grl_source_get_tags ()
gboolean | grl_source_may_resolve ()
void | grl_source_notify_change ()
void | grl_source_notify_change_list ()
gboolean | grl_source_notify_change_start ()
gboolean | grl_source_notify_change_stop ()
guint | grl_source_query ()
GList * | grl_source_query_sync ()
void | grl_source_remove ()
void | grl_source_remove_sync ()
guint | grl_source_resolve ()
GrlMedia * | grl_source_resolve_sync ()
guint | grl_source_search ()
GList * | grl_source_search_sync ()
void | grl_source_set_auto_split_threshold ()
const GList * | grl_source_slow_keys ()
void | grl_source_store ()
void | grl_source_store_metadata ()
GList * | grl_source_store_metadata_sync ()
void | grl_source_store_sync ()
const GList * | grl_source_supported_keys ()
GrlSupportedOps | grl_source_supported_operations ()
gboolean | grl_source_test_media_from_uri ()
const GList * | grl_source_writable_keys ()

## Properties

guint | auto-split-threshold | Read / Write
GrlPlugin * | plugin | Read / Write / Construct
int | rank | Read / Write / Construct
char * | source-desc | Read / Write / Construct
GIcon * | source-icon | Read / Write / Construct
char * | source-id | Read / Write / Construct
char * | source-name | Read / Write / Construct
GStrv | source-tags | Read / Write / Construct
GrlSupportedMedia | supported-media | Read / Write / Construct

## Signals

void | content-changed | Action

## Types and Values

struct | GrlSource
struct | GrlSourceClass
enum | GrlResolutionFlags
| GrlSourceBrowseSpec
enum | GrlSourceChangeType
| GrlSourceMediaFromUriSpec
| GrlSourceQuerySpec
| GrlSourceRemoveSpec
| GrlSourceResolveSpec
| GrlSourceSearchSpec
| GrlSourceStoreMetadataSpec
| GrlSourceStoreSpec
enum | GrlSupportedOps
enum | GrlSupportedMedia
enum | GrlWriteFlags

## Object Hierarchy

        GObject
        ╰── GrlSource

## Includes

    #include <grilo.h>

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

## Functions

### GrlSourceRemoveCb ()

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

Prototype for the callback passed to `grl_source_remove()`

#### Parameters

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. | [nullable]

### 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()`. 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()`.

#### Parameters

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. | [nullable]

### 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

#### Parameters

source | a source |
operation_id | operation identifier |
media | a data transfer object. | [nullable][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. | [nullable]

### 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

#### Parameters

source | a source |
media | a GrlMedia transfer object |
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. | [nullable]

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

#### Parameters

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.

#### Parameters

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 GrlMedia][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()`

#### Parameters

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

#### Parameters

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

#### Parameters

source | a source |

#### Returns

the description of the `source`

Since: 0.2.0

### grl_source_get_icon ()

    GIcon *
    grl_source_get_icon (GrlSource *source);

#### Parameters

source | a source |

#### Returns

a GIcon.

[transfer none]

Since: 0.2.8

### grl_source_get_id ()

    const gchar *
    grl_source_get_id (GrlSource *source);

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

source | a source |

#### Returns

the name of the `source`

Since: 0.2.0

### grl_source_get_plugin ()

    GrlPlugin *
    grl_source_get_plugin (GrlSource *source);

#### Parameters

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

#### Parameters

source | a source |

#### Returns

rank value

Since: 0.2.0

### grl_source_get_supported_media ()

    GrlSupportedMedia
    grl_source_get_supported_media (GrlSource *source);

Gets the supported type of medias `source` can deal with.

#### Parameters

source | a source |

#### Returns

a GrlSupportedMedia value

Since: 0.3.0

### grl_source_get_tags ()

    const char **
    grl_source_get_tags (GrlSource *source);

#### Parameters

source | a source |

#### Returns

a `NULL`-terminated list of tags.

[element-type utf8][transfer none]

Since: 0.2.10

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

#### Parameters

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.

This function is intended to be used only by plugins.

#### Parameters

source | a source |
media | the media which has changed, or `NULL` to use the root container. | [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.

This function is intended to be used only by plugins.

#### Parameters

source | a source |
changed_medias | the list of medias that have changed. | [element-type GrlMedia][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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 GrlMedia][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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

source | a source |
media | a data transfer object. | [allow-none][transfer full]
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.

#### Parameters

source | a source |
media | a data transfer object. | [allow-none][transfer full]
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.

#### Parameters

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.

#### Parameters

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 GrlMedia][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.

This function is intended to be used only by plugins.

#### Parameters

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.

#### Parameters

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,
                      GrlMedia *parent,
                      GrlMedia *media,
                      GrlWriteFlags flags,
                      GrlSourceStoreCb callback,
                      gpointer user_data);

Store the `media` into the `parent` container

This method is asynchronous.

#### Parameters

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

### grl_source_store_metadata ()

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

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.

#### Parameters

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 GrlKeyID][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.

#### Parameters

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,
                           GrlMedia *parent,
                           GrlMedia *media,
                           GrlWriteFlags flags,
                           GError **error);

Store the `media` into the `parent` container.

This method is synchronous.

#### Parameters

source | a source |
parent | a GrlMedia container 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.3.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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

source | a source |

#### Returns

a GList with the keys.

[element-type GrlKeyID][transfer none]

Since: 0.2.0

## Types and Values

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

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

#### Members

`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

Resolution flags

#### Members

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.

#### Members

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

Specifies which kind of change has happened in the plugin

#### Members

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 |

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

#### Members

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.

#### Members

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 |

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

#### Members

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 |

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

#### Members

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 |

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

#### Members

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 |

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

#### Members

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;
      GrlMedia *parent;
      GrlMedia *media;
      GrlSourceStoreCb callback;
      gpointer user_data;
    } GrlSourceStoreSpec;

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

#### Members

GrlSource *`source`; | a media source |
GrlMedia *`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

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

#### Members

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

### enum GrlSupportedMedia

#### Members

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 |

### enum GrlWriteFlags

Flags for writing operations.

#### Members

GRL_WRITE_NORMAL | Normal mode. |
GRL_WRITE_FULL | Try other plugins if necessary. |

## Property Details

### The `“auto-split-threshold”` property

      “auto-split-threshold”     guint

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

Owner: GrlSource

Flags: Read / Write

Default value: 0

Since: 0.2.0

### The `“plugin”` property

      “plugin”                   GrlPlugin *

Plugin the source belongs to

Owner: GrlSource

Flags: Read / Write / Construct

Since: 0.2.0

### The `“rank”` property

      “rank”                     int

Source rank

Owner: GrlSource

Flags: Read / Write / Construct

Default value: 0

Since: 0.2.0

### The `“source-desc”` property

      “source-desc”              char *

A description of the source

Owner: GrlSource

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

### The `“source-icon”` property

      “source-icon”              GIcon *

GIcon representing the source

Owner: GrlSource

Flags: Read / Write / Construct

Since: 0.2.8

### The `“source-id”` property

      “source-id”                char *

The identifier of the source.

Owner: GrlSource

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

### The `“source-name”` property

      “source-name”              char *

The name of the source.

Owner: GrlSource

Flags: Read / Write / Construct

Default value: ""

Since: 0.2.0

### The `“source-tags”` property

      “source-tags”              GStrv

A string array of tags relevant this source.

The tags are arbitrary, and applications should just pass over the tags it does not understand. Applications would usually use this to either group sources together, or hide certain sources: a radio application would filter for `GRL_MEDIA_TYPE_AUDIO` in GrlSource::supported-media as well as "radio" being listed in the tags.

To avoid irrelevant content being listed in applications, sources such as generic video sites should not be tagged as "cinema" or "tv" as they contain a lot of content that's not either of those.

This is a list of commonly used values:

- "cinema", or "tv" The content served is from cinema or TV sources. For example, a source for movie trailers would select the former, a source for streaming live TV would select the latter.

- "radio" The content served is from streaming radios.

- "music" The content served is music, for example, music stores such as Jamendo or Magnatune.

- "country:country-code" The content is mostly relevant to users from a particular country, such as a national broadcaster. For example, BBC content would be tagged as "country:uk". Country codes should be an ISO-639-1 or ISO-639-2 code.

- "protocol:protocol-name" The content browsing or searching uses a particular protocol, such as DLNA/UPnP or DMAP/DAAP. This makes it easier to whitelist or blacklist sources rather than matching the implementation specific source ID. Examples are "protocol:dlna" and "protocol:dmap".

- "localhost", or "localuser" The content is served from the machine the application is running on, or by an application the user is running. Applications might choose to avoid showing the user's own data in their interfaces, or integrate it in the user's local collection.

  "net:local", or "net:internet" The source requires a connection to the local network, or a connection to the Internet. Sources with those tags will be automatically hidden from the application's reach when such networks aren't available, or we're not connected to a network.

  "net:plaintext" The source makes requests over plain text, non-encrypted, network channels, such as using HTTP to do searches or lookups. Applications would usually disable those by default, so that privacy is respected by default, and no data is leaked unintentionally.

Owner: GrlSource

Flags: Read / Write / Construct

Since: 0.2.10

### The `“supported-media”` property

      “supported-media”          GrlSupportedMedia

List of supported media types by this source.

Owner: GrlSource

Flags: Read / Write / Construct

Default value: GRL_SUPPORTED_MEDIA_AUDIO | GRL_SUPPORTED_MEDIA_VIDEO | GRL_SUPPORTED_MEDIA_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)

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 GrlMedia container, meaning that the content of that container has changed.

If `location_unknown` is `TRUE` it means the source cannot establish where the change happened: could be either in the container, in any child, or in any other descendant of the container 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 container (`NULL` id) and set location_unknown as `TRUE` .

#### Parameters

source | source that has changed |
changed_medias | a GPtrArray with the medias that changed or a common ancestor of them of type GrlMedia. | [element-type GrlMedia]
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 GrlMedia). `FALSE` otherwise |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 0.2.0

## See Also

GrlPlugin, GrlSource, GrlMedia