Grl.Source

g GObject.Object GObject.Object Grl.Source Grl.Source GObject.Object->Grl.Source

Subclasses:None

Methods

Inherited:GObject.Object (37)
Structs:GObject.ObjectClass (5)
  browse (container, keys, options, callback, *user_data)
  browse_sync (container, keys, options)
  get_auto_split_threshold ()
  get_caps (operation)
  get_description ()
  get_icon ()
  get_id ()
  get_media_from_uri (uri, keys, options, callback, *user_data)
  get_media_from_uri_sync (uri, keys, options)
  get_name ()
  get_plugin ()
  get_rank ()
  get_supported_media ()
  get_tags ()
  may_resolve (media, key_id, missing_keys)
  notify_change (media, change_type, location_unknown)
  notify_change_list (changed_medias, change_type, location_unknown)
  notify_change_start ()
  notify_change_stop ()
  query (query, keys, options, callback, *user_data)
  query_sync (query, keys, options)
  remove (media, callback, *user_data)
  remove_sync (media)
  resolve (media, keys, options, callback, *user_data)
  resolve_sync (media, keys, options)
  search (text, keys, options, callback, *user_data)
  search_sync (text, keys, options)
  set_auto_split_threshold (threshold)
  slow_keys ()
  store (parent, media, flags, callback, *user_data)
  store_metadata (media, keys, flags, callback, *user_data)
  store_metadata_sync (media, keys, flags)
  store_sync (parent, media, flags)
  supported_keys ()
  supported_operations ()
  test_media_from_uri (uri)
  writable_keys ()

Virtual Methods

Inherited:GObject.Object (7)
  do_browse (bs)
  do_cancel (operation_id)
  do_get_caps (operation)
  do_may_resolve (media, key_id, missing_keys)
  do_media_from_uri (mfus)
  do_notify_change_start ()
  do_notify_change_stop ()
  do_query (qs)
  do_remove (rs)
  do_resolve (ms)
  do_search (ss)
  do_slow_keys ()
  do_store (ss)
  do_store_metadata (sms)
  do_supported_keys ()
  do_supported_operations ()
  do_test_media_from_uri (uri)
  do_writable_keys ()

Properties

Name Type Flags Short Description
auto-split-threshold int r/w Threshold to use auto-split of queries
plugin Grl.Plugin r/w/c Plugin source belongs to
rank int r/w/c Source rank
source-desc str r/w/c A description of the source
source-icon Gio.Icon r/w/c Icon representing the source
source-id str r/w/c The identifier of the source
source-name str r/w/c The name of the source
source-tags [str] r/w/c String array of tags relevant this source
supported-media Grl.SupportedMedia r/w/c List of supported media types

Signals

Inherited:GObject.Object (1)
Name Short Description
content-changed Signals that the content in the source has changed.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent GObject.Object r  

Class Details

class Grl.Source(**kwargs)
Bases:GObject.Object
Abstract:Yes
Structure:Grl.SourceClass
browse(container, keys, options, callback, *user_data)
Parameters:
Returns:

the operation identifier

Return type:

int

Browse from media elements through an available list.

This method is asynchronous.

New in version 0.2.0.

browse_sync(container, keys, options)
Parameters:
Raises:

GLib.Error

Returns:

a GLib.List with Grl.Media elements. After use GObject.Object.unref() every element and g_list_free() the list.

Return type:

[Grl.Media]

Browse media elements through an available list.

This method is synchronous.

New in version 0.2.0.

get_auto_split_threshold()
Returns:the assigned threshold, or 0 if there is no threshold
Return type:int

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

See Grl.Source.set_auto_split_threshold()

New in version 0.2.0.

get_caps(operation)
Parameters:operation (Grl.SupportedOps) – a supported operation. Even though the type allows to specify several operations, only one should be provided here.
Returns:The capabilities
Return type:Grl.Caps

Get the capabilities of self for operation.

New in version 0.2.0.

get_description()
Returns:the description of the self
Return type:str

New in version 0.2.0.

get_icon()
Returns:a Gio.Icon
Return type:Gio.Icon

New in version 0.2.8.

get_id()
Returns:the ID of the self
Return type:str

New in version 0.2.0.

get_media_from_uri(uri, keys, options, callback, *user_data)
Parameters:
  • uri (str) – A URI that can be used to identify a media resource
  • keys ([int]) – A list of keys to resolve
  • options (Grl.OperationOptions) – options wanted for that operation
  • callback (Grl.SourceResolveCb) – the user defined callback
  • user_data (object or None) – the user data to pass in the callback
Returns:

the operation identifier

Return type:

int

Creates an instance of Grl.Media 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.

New in version 0.2.0.

get_media_from_uri_sync(uri, keys, options)
Parameters:
  • uri (str) – A URI that can be used to identify a media resource
  • keys ([int]) – a list of keys to resolve
  • options (Grl.OperationOptions) – options wanted for that operation
Raises:

GLib.Error

Returns:

a filled Grl.Media

Return type:

Grl.Media

Creates an instance of Grl.Media 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.

New in version 0.2.0.

get_name()
Returns:the name of the self
Return type:str

New in version 0.2.0.

get_plugin()
Returns:the plugin this source belongs to
Return type:Grl.Plugin

New in version 0.2.0.

get_rank()
Returns:rank value
Return type:int

Gets the source rank

New in version 0.2.0.

get_supported_media()
Returns:a Grl.SupportedMedia value
Return type:Grl.SupportedMedia

Gets the supported type of medias self can deal with.

New in version 0.3.0.

get_tags()
Returns:a None-terminated list of tags
Return type:[str]

New in version 0.2.10.

may_resolve(media, key_id, missing_keys)
Parameters:
  • media (Grl.Media) – a media on which we want more metadata
  • key_id (int) – the key corresponding to a metadata we might want
  • missing_keys ([int]) – an optional originally empty list
Returns:

True if there’s a possibility that self resolves key_id for media, False otherwise.

Return type:

bool

Checks whether key_id may be resolved with self 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 None, it is populated with the list of GrlKeyID that would be needed.

This function is synchronous and should not block.

New in version 0.2.0.

notify_change(media, change_type, location_unknown)
Parameters:
  • media (Grl.Media or None) – the media which has changed, or None to use the root container.
  • change_type (Grl.SourceChangeType) – the type of change
  • location_unknown (bool) – if change has happened in media or any descendant

Emits “content-changed” signal to notify subscribers that a change ocurred in self.

See Grl.Source.notify_change_list() function.

This function is intended to be used only by plugins.

New in version 0.2.0.

notify_change_list(changed_medias, change_type, location_unknown)
Parameters:
  • changed_medias ([Grl.Media]) – the list of medias that have changed
  • change_type (Grl.SourceChangeType) – the type of change
  • location_unknown (bool) – if change has happpened in media or any descendant

Emits “content-changed” signal to notify subscribers that a change ocurred in self.

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 Grl.Source ::content-changed signal.

This function is intended to be used only by plugins.

New in version 0.2.0.

notify_change_start()
Raises:GLib.Error
Returns:True if initialization has succeed.
Return type:bool

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

New in version 0.2.0.

notify_change_stop()
Raises:GLib.Error
Returns:True if stop has succeed.
Return type:bool

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

New in version 0.2.0.

query(query, keys, options, callback, *user_data)
Parameters:
Returns:

the operation identifier

Return type:

int

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.

New in version 0.2.0.

query_sync(query, keys, options)
Parameters:
Raises:

GLib.Error

Returns:

a GLib.List with Grl.Media elements. After use GObject.Object.unref() every element and g_list_free() the list.

Return type:

[Grl.Media]

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

This method is synchronous.

New in version 0.2.0.

remove(media, callback, *user_data)
Parameters:

Remove a media from the self repository.

This method is asynchronous.

New in version 0.2.0.

remove_sync(media)
Parameters:media (Grl.Media) – a data transfer object
Raises:GLib.Error

Remove a media from the self repository.

This method is synchronous.

New in version 0.2.0.

resolve(media, keys, options, callback, *user_data)
Parameters:
Returns:

the operation identifie

Return type:

int

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

This method is asynchronous.

New in version 0.2.0.

resolve_sync(media, keys, options)
Parameters:
Raises:

GLib.Error

Returns:

a filled Grl.Media

Return type:

Grl.Media

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

This method is synchronous.

New in version 0.2.0.

search(text, keys, options, callback, *user_data)
Parameters:
Returns:

the operation identifier

Return type:

int

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

If text is None then no text filter will be applied, and thus, no media items from self will be filtered. If self does not support None-text search operations it should notiy the client by setting Grl.CoreError.SEARCH_NULL_UNSUPPORTED in callback’s error parameter.

This method is asynchronous.

New in version 0.2.0.

search_sync(text, keys, options)
Parameters:
Raises:

GLib.Error

Returns:

a GLib.List with Grl.Media elements. After use GObject.Object.unref() every element and g_list_free() the list.

Return type:

[Grl.Media]

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

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

This method is synchronous.

New in version 0.2.0.

set_auto_split_threshold(threshold)
Parameters:threshold (int) – the threshold to set

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.

New in version 0.2.0.

slow_keys()
Returns:a GLib.List with the keys
Return type:[int]

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

New in version 0.2.0.

store(parent, media, flags, callback, *user_data)
Parameters:
  • parent (Grl.Media or None) – a parent to store the data transfer objects
  • media (Grl.Media) – a data transfer object
  • flags (Grl.WriteFlags) – flags to configure specific behaviour of the operation
  • callback (Grl.SourceStoreCb) – the user defined callback
  • user_data (object or None) – the user data to pass in the callback

Store the media into the parent container

This method is asynchronous.

New in version 0.3.0.

store_metadata(media, keys, flags, callback, *user_data)
Parameters:
  • media (Grl.Media) – the Grl.Media object that we want to operate on.
  • keys ([int] or None) – a list of #GrlKeyID whose values we want to change.
  • flags (Grl.WriteFlags) – Flags to configure specific behaviors of the operation.
  • callback (Grl.SourceStoreCb) – the callback to execute when the operation is finished.
  • user_data (object or None) – user data set for the callback

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.

New in version 0.2.0.

store_metadata_sync(media, keys, flags)
Parameters:
  • media (Grl.Media) – the Grl.Media object that we want to operate on
  • keys ([int] or None) – a list of #GrlKeyID whose values we want to change
  • flags (Grl.WriteFlags) – Flags to configure specific behaviors of the operation.
Raises:

GLib.Error

Returns:

a GLib.List of keys that could not be updated, or None

Return type:

[int]

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

This function is synchronous.

New in version 0.2.0.

store_sync(parent, media, flags)
Parameters:
Raises:

GLib.Error

Store the media into the parent container.

This method is synchronous.

New in version 0.3.0.

supported_keys()
Returns:a GLib.List with the keys
Return type:[int]

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

New in version 0.2.0.

supported_operations()
Returns:a bitwise mangle with the supported operations by the source
Return type:int

By default the derived objects of Grl.Source can only resolve.

New in version 0.2.0.

test_media_from_uri(uri)
Parameters:uri (str) – A URI that can be used to identify a media resource
Returns:True if it can, False otherwise.

This method is synchronous.

Return type:bool

Tests whether self can instantiate a Grl.Media object representing the media resource exposed at uri.

New in version 0.2.0.

writable_keys()
Returns:a GLib.List with the keys
Return type:[int]

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.

New in version 0.2.0.

do_browse(bs) virtual
Parameters:bs (Grl.SourceBrowseSpec) –
do_cancel(operation_id) virtual
Parameters:operation_id (int) –
do_get_caps(operation) virtual
Parameters:operation (Grl.SupportedOps) – a supported operation. Even though the type allows to specify several operations, only one should be provided here.
Returns:The capabilities
Return type:Grl.Caps

Get the capabilities of source for operation.

New in version 0.2.0.

do_may_resolve(media, key_id, missing_keys) virtual
Parameters:
  • media (Grl.Media) – a media on which we want more metadata
  • key_id (int) – the key corresponding to a metadata we might want
  • missing_keys ([int]) – an optional originally empty list
Returns:

True if there’s a possibility that source resolves key_id for media, False otherwise.

Return type:

bool

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 None, it is populated with the list of GrlKeyID that would be needed.

This function is synchronous and should not block.

New in version 0.2.0.

do_media_from_uri(mfus) virtual
Parameters:mfus (Grl.SourceMediaFromUriSpec) –
do_notify_change_start() virtual
Returns:True if initialization has succeed.
Return type:bool

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.

New in version 0.2.0.

do_notify_change_stop() virtual
Returns:True if stop has succeed.
Return type:bool

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.

New in version 0.2.0.

do_query(qs) virtual
Parameters:qs (Grl.SourceQuerySpec) –
do_remove(rs) virtual
Parameters:rs (Grl.SourceRemoveSpec) –
do_resolve(ms) virtual
Parameters:ms (Grl.SourceResolveSpec) –
Parameters:ss (Grl.SourceSearchSpec) –
do_slow_keys() virtual
Returns:a GLib.List with the keys
Return type:[int]

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

New in version 0.2.0.

do_store(ss) virtual
Parameters:ss (Grl.SourceStoreSpec) –
do_store_metadata(sms) virtual
Parameters:sms (Grl.SourceStoreMetadataSpec) –
do_supported_keys() virtual
Returns:a GLib.List with the keys
Return type:[int]

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

New in version 0.2.0.

do_supported_operations() virtual
Return type:Grl.SupportedOps
do_test_media_from_uri(uri) virtual
Parameters:uri (str) – A URI that can be used to identify a media resource
Returns:True if it can, False otherwise.

This method is synchronous.

Return type:bool

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

New in version 0.2.0.

do_writable_keys() virtual
Returns:a GLib.List with the keys
Return type:[int]

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.

New in version 0.2.0.

Signal Details

Grl.Source.signals.content_changed(source, changed_medias, change_type, location_unknown)
Signal Name:

content-changed

Flags:

RUN_FIRST, ACTION

Parameters:

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 Grl.Media 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 (None id) and set location_unknown as True.

New in version 0.2.0.

Property Details

Grl.Source.props.auto_split_threshold
Name:auto-split-threshold
Type:int
Default Value:0
Flags:READABLE, WRITABLE

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

New in version 0.2.0.

Grl.Source.props.plugin
Name:plugin
Type:Grl.Plugin
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT

Plugin the source belongs to

New in version 0.2.0.

Grl.Source.props.rank
Name:rank
Type:int
Default Value:0
Flags:READABLE, WRITABLE, CONSTRUCT

Source rank

New in version 0.2.0.

Grl.Source.props.source_desc
Name:source-desc
Type:str
Default Value:''
Flags:READABLE, WRITABLE, CONSTRUCT

A description of the source

New in version 0.2.0.

Grl.Source.props.source_icon
Name:source-icon
Type:Gio.Icon
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT

Gio.Icon representing the source

New in version 0.2.8.

Grl.Source.props.source_id
Name:source-id
Type:str
Default Value:''
Flags:READABLE, WRITABLE, CONSTRUCT

The identifier of the source.

New in version 0.2.0.

Grl.Source.props.source_name
Name:source-name
Type:str
Default Value:''
Flags:READABLE, WRITABLE, CONSTRUCT

The name of the source.

New in version 0.2.0.

Grl.Source.props.source_tags
Name:source-tags
Type:[str]
Default Value:[]
Flags:READABLE, WRITABLE, CONSTRUCT

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.MediaType.AUDIO in Grl.Source ::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.

New in version 0.2.10.

Grl.Source.props.supported_media
Name:supported-media
Type:Grl.SupportedMedia
Default Value:Grl.SupportedMedia.AUDIO | Grl.SupportedMedia.VIDEO | Grl.SupportedMedia.IMAGE | Grl.SupportedMedia.ALL
Flags:READABLE, WRITABLE, CONSTRUCT

List of supported media types by this source.

New in version 0.2.3.