Grl.Source ¶

Browse from media elements through an available list.

This method is asynchronous.

New in version 0.2.0.

browse_sync(container, keys, options)¶

Parameters:

container (Grl.Media or None) – a container of data transfer objects
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options wanted for that operation

Raises:

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:

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:

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:

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:

query (str) – the query to process
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options wanted for that operation
callback (Grl.SourceResultCb) – the user defined callback
user_data (object or None) – the user data to pass in the callback

Returns:

the operation identifier

Return type:

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:

query (str) – the query to process
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options wanted for that operation

Raises:

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:

media (Grl.Media) – a data transfer object
callback (Grl.SourceRemoveCb) – the user defined callback
user_data (object or None) – the user data to pass in the callback

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:

media (Grl.Media or None) – a data transfer object
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options to pass to this operation
callback (Grl.SourceResolveCb) – the user defined callback
user_data (object or None) – the user data to pass in the callback

Returns:

the operation identifie

Return type:

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:

media (Grl.Media or None) – a data transfer object
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options to pass to this operation

Raises:

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:

text (str) – the text to search
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options wanted for that operation
callback (Grl.SourceResultCb) – the user defined callback
user_data (object or None) – the user data to pass in the callback

Returns:

the operation identifier

Return type:

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:

text (str) – the text to search
keys ([int]) – the GLib.List of #GrlKeyID s to request
options (Grl.OperationOptions) – options wanted for that operation

Raises:

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:

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:

parent (Grl.Media or None) – a Grl.Media container to store the data transfer objects
media (Grl.Media) – a Grl.Media data transfer object
flags (Grl.WriteFlags) – flags to configure specific behaviour of the operation

Raises:

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:

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:

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

do_search(ss) virtual¶

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: