![]() |
![]() |
![]() |
Grilo Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#include <grilo.h> struct GrlMediaSource; void (*GrlMediaSourceResultCb) (GrlMediaSource *source
,guint operation_id
,GrlMedia *media
,guint remaining
,gpointer user_data
,const GError *error
); void (*GrlMediaSourceMetadataCb) (GrlMediaSource *source
,GrlMedia *media
,gpointer user_data
,const GError *error
); void (*GrlMediaSourceStoreCb) (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,gpointer user_data
,const GError *error
); void (*GrlMediaSourceRemoveCb) (GrlMediaSource *source
,GrlMedia *media
,gpointer user_data
,const GError *error
); GrlMediaSourceBrowseSpec; GrlMediaSourceSearchSpec; GrlMediaSourceQuerySpec; GrlMediaSourceMetadataSpec; GrlMediaSourceStoreSpec; GrlMediaSourceRemoveSpec; GrlMediaSourceMediaFromUriSpec; struct GrlMediaSourceClass; guint grl_media_source_browse (GrlMediaSource *source
,GrlMedia *container
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
); GList * grl_media_source_browse_sync (GrlMediaSource *source
,GrlMedia *container
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
); guint grl_media_source_search (GrlMediaSource *source
,const gchar *text
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
); GList * grl_media_source_search_sync (GrlMediaSource *source
,const gchar *text
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
); guint grl_media_source_query (GrlMediaSource *source
,const gchar *query
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
); GList * grl_media_source_query_sync (GrlMediaSource *source
,const gchar *query
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
); guint grl_media_source_metadata (GrlMediaSource *source
,GrlMedia *media
,const GList *keys
,GrlMetadataResolutionFlags flags
,GrlMediaSourceMetadataCb callback
,gpointer user_data
); GrlMedia * grl_media_source_metadata_sync (GrlMediaSource *source
,GrlMedia *media
,const GList *keys
,GrlMetadataResolutionFlags flags
,GError **error
); void grl_media_source_store (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,GrlMediaSourceStoreCb callback
,gpointer user_data
); void grl_media_source_store_sync (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,GError **error
); void grl_media_source_remove (GrlMediaSource *source
,GrlMedia *media
,GrlMediaSourceRemoveCb callback
,gpointer user_data
); void grl_media_source_remove_sync (GrlMediaSource *source
,GrlMedia *media
,GError **error
); void grl_media_source_cancel (GrlMediaSource *source
,guint operation_id
); void grl_media_source_set_operation_data (GrlMediaSource *source
,guint operation_id
,gpointer data
); gpointer grl_media_source_get_operation_data (GrlMediaSource *source
,guint operation_id
); void grl_media_source_set_auto_split_threshold (GrlMediaSource *source
,guint threshold
); guint grl_media_source_get_auto_split_threshold (GrlMediaSource *source
); gboolean grl_media_source_test_media_from_uri (GrlMediaSource *source
,const gchar *uri
); void grl_media_source_get_media_from_uri (GrlMediaSource *source
,const gchar *uri
,const GList *keys
,GrlMetadataResolutionFlags flags
,GrlMediaSourceMetadataCb callback
,gpointer user_data
);
GrlMediaSource is the abstract base class needed to construct a source of media data.
The media sources fetch media data descriptors and store them in data transfer objects represented as GrlMedia.
There are several methods to retrieve the media, such as searching a text expression, crafting a specific query, etc. And most of those methods are asynchronous.
Examples of media sources are GrlYoutubeSource, GrlJamendoSource, etc.
void (*GrlMediaSourceResultCb) (GrlMediaSource *source
,guint operation_id
,GrlMedia *media
,guint remaining
,gpointer user_data
,const GError *error
);
Prototype for the callback passed to the media sources' methods
|
a media source |
|
operation identifier |
|
a data transfer object. [transfer full] |
|
the number of remaining GrlMedia to process, or GRL_SOURCE_REMAINING_UNKNOWN if it is unknown |
|
user data passed to the used method |
|
possible GError generated at processing. [type uint] |
void (*GrlMediaSourceMetadataCb) (GrlMediaSource *source
,GrlMedia *media
,gpointer user_data
,const GError *error
);
Prototype for the callback passed to grl_media_source_metadata()
|
a media source |
|
a data transfer object. [transfer full] |
|
user data passed to grl_media_source_metadata()
|
|
possible GError generated at processing. [type uint] |
void (*GrlMediaSourceStoreCb) (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,gpointer user_data
,const GError *error
);
Prototype for the callback passed to grl_media_source_store()
|
a media source |
|
The GrlMediaBox who parents the media
|
|
a data transfer object. [transfer full] |
|
user data passed to grl_media_source_store()
|
|
possible GError generated at processing. [type uint] |
void (*GrlMediaSourceRemoveCb) (GrlMediaSource *source
,GrlMedia *media
,gpointer user_data
,const GError *error
);
Prototype for the callback passed to grl_media_source_remove()
|
a media source |
|
a data transfer object. [transfer full] |
|
user data passed to grl_media_source_remove()
|
|
possible GError generated at processing. [type uint] |
typedef struct { GrlMediaSource *source; guint browse_id; GrlMedia *container; GList *keys; guint skip; guint count; GrlMetadataResolutionFlags flags; GrlMediaSourceResultCb callback; gpointer user_data; } GrlMediaSourceBrowseSpec;
Data transport structure used internally by the plugins which support browse vmethod.
GrlMediaSource * |
a media source |
operation identifier | |
a container of data transfer objects | |
the GList of GrlKeyIDs to request | |
the number if elements to skip in the browse operation | |
the number of elements to retrieve in the browse operation | |
GrlMetadataResolutionFlags |
the resolution mode |
GrlMediaSourceResultCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; guint search_id; gchar *text; GList *keys; guint skip; guint count; GrlMetadataResolutionFlags flags; GrlMediaSourceResultCb callback; gpointer user_data; } GrlMediaSourceSearchSpec;
Data transport structure used internally by the plugins which support search vmethod.
GrlMediaSource * |
a media source |
operation identifier | |
the text to search | |
the GList of GrlKeyIDs to request | |
the number if elements to skip in the browse operation | |
the number of elements to retrieve in the browse operation | |
GrlMetadataResolutionFlags |
the resolution mode |
GrlMediaSourceResultCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; guint query_id; gchar *query; GList *keys; guint skip; guint count; GrlMetadataResolutionFlags flags; GrlMediaSourceResultCb callback; gpointer user_data; } GrlMediaSourceQuerySpec;
Data transport structure used internally by the plugins which support query vmethod.
GrlMediaSource * |
a media source |
operation identifier | |
the query to process | |
the GList of GrlKeyIDs to request | |
the number if elements to skip in the browse operation | |
the number of elements to retrieve in the browse operation | |
GrlMetadataResolutionFlags |
the resolution mode |
GrlMediaSourceResultCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; guint metadata_id; GrlMedia *media; GList *keys; GrlMetadataResolutionFlags flags; GrlMediaSourceMetadataCb callback; gpointer user_data; } GrlMediaSourceMetadataSpec;
Data transport structure used internally by the plugins which support metadata vmethod.
GrlMediaSource * |
a media source |
operation identifier | |
a data transfer object | |
the GList of GrlKeyIDs to request | |
GrlMetadataResolutionFlags |
the resolution mode |
GrlMediaSourceMetadataCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; GrlMediaBox *parent; GrlMedia *media; GrlMediaSourceStoreCb callback; gpointer user_data; } GrlMediaSourceStoreSpec;
Data transport structure used internally by the plugins which support store vmethod.
GrlMediaSource * |
a media source |
a parent to store the data transfer objects | |
a data transfer object | |
GrlMediaSourceStoreCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; gchar *media_id; GrlMedia *media; GrlMediaSourceRemoveCb callback; gpointer user_data; } GrlMediaSourceRemoveSpec;
Data transport structure used internally by the plugins which support store vmethod.
GrlMediaSource * |
a media source |
media identifier to remove | |
a data transfer object | |
GrlMediaSourceRemoveCb |
the user defined callback |
the user data to pass in the callback |
typedef struct { GrlMediaSource *source; gchar *uri; GList *keys; GrlMetadataResolutionFlags flags; GrlMediaSourceMetadataCb callback; gpointer user_data; } GrlMediaSourceMediaFromUriSpec;
Data transport structure used internally by the plugins which support media_from_uri vmethod.
GrlMediaSource * |
a media source |
A URI that can be used to identify a media resource | |
Metadata keys to resolve | |
GrlMetadataResolutionFlags |
Operation flags |
GrlMediaSourceMetadataCb |
the user defined callback |
the user data to pass in the callback |
struct GrlMediaSourceClass { GrlMetadataSourceClass parent_class; guint operation_id; void (*browse) (GrlMediaSource *source, GrlMediaSourceBrowseSpec *bs); void (*search) (GrlMediaSource *source, GrlMediaSourceSearchSpec *ss); void (*query) (GrlMediaSource *source, GrlMediaSourceQuerySpec *qs); void (*cancel) (GrlMediaSource *source, guint operation_id); void (*metadata) (GrlMediaSource *source, GrlMediaSourceMetadataSpec *ms); void (*store) (GrlMediaSource *source, GrlMediaSourceStoreSpec *ss); void (*remove) (GrlMediaSource *source, GrlMediaSourceRemoveSpec *ss); gboolean (*test_media_from_uri) (GrlMediaSource *source, const gchar *uri); void (*media_from_uri) (GrlMediaSource *source, GrlMediaSourceMediaFromUriSpec *mfss); gboolean (*notify_change_start) (GrlMediaSource *source, GError **error); gboolean (*notify_change_stop) (GrlMediaSource *source, GError **error); };
Grilo MediaSource class. Override the vmethods to implement the source functionality.
GrlMetadataSourceClass |
the parent class structure |
operation identifier | |
browse through a list of media | |
search for media | |
query for a specific media | |
cancel the current operation | |
request for specific metadata | |
store a media in a container | |
remove a media from a container | |
tests if this source can create GrlMedia instances from a given URI. | |
Creates a GrlMedia instance representing the media exposed by a certain URI. | |
start emitting signals about changes in content | |
stop emitting signals about changes in content |
guint grl_media_source_browse (GrlMediaSource *source
,GrlMedia *container
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
);
Browse from skip
, a count
number of media elements through an available list.
This method is asynchronous.
|
a media source |
|
a container of data transfer objects. [allow-none] |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the browse operation |
|
the number of elements to retrieve in the browse operation |
|
the resolution mode |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Returns : |
the operation identifier |
Since 0.1.4
GList * grl_media_source_browse_sync (GrlMediaSource *source
,GrlMedia *container
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
);
Browse from skip
, a count
number of media elements through an available
list.
This method is synchronous.
|
a media source |
|
a container of data transfer objects. [allow-none] |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the browse operation |
|
the number of elements to retrieve in the browse operation |
|
the resolution mode |
|
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.1.6
guint grl_media_source_search (GrlMediaSource *source
,const gchar *text
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
);
Search for the text
string in a media 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.
|
a media source |
|
the text to search |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the search operation |
|
the number of elements to retrieve in the search operation |
|
the resolution mode |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Returns : |
the operation identifier |
Since 0.1.1
GList * grl_media_source_search_sync (GrlMediaSource *source
,const gchar *text
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
);
Search for the text
string in a media 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.
|
a media source |
|
the text to search |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the search operation |
|
the number of elements to retrieve in the search operation |
|
the resolution mode |
|
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.1.6
guint grl_media_source_query (GrlMediaSource *source
,const gchar *query
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GrlMediaSourceResultCb callback
,gpointer user_data
);
Execute a specialized query (specific for each provider) on a media repository.
It is different from grl_media_source_search()
semantically, because
the query implies a carefully crafted string, rather than a simple
string to search.
This method is asynchronous.
|
a media source |
|
the query to process |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the query operation |
|
the number of elements to retrieve in the query operation |
|
the resolution mode |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Returns : |
the operation identifier |
Since 0.1.1
GList * grl_media_source_query_sync (GrlMediaSource *source
,const gchar *query
,const GList *keys
,guint skip
,guint count
,GrlMetadataResolutionFlags flags
,GError **error
);
Execute a specialized query (specific for each provider) on a media repository.
This method is synchronous.
|
a media source |
|
the query to process |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the number if elements to skip in the query operation |
|
the number of elements to retrieve in the query operation |
|
the resolution mode |
|
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.1.6
guint grl_media_source_metadata (GrlMediaSource *source
,GrlMedia *media
,const GList *keys
,GrlMetadataResolutionFlags flags
,GrlMediaSourceMetadataCb 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.
|
a media source |
|
a data transfer object. [allow-none] |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the resolution mode |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Returns : |
the operation identifier |
Since 0.1.6
GrlMedia * grl_media_source_metadata_sync (GrlMediaSource *source
,GrlMedia *media
,const GList *keys
,GrlMetadataResolutionFlags flags
,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.
|
a media source |
|
a data transfer object. [allow-none] |
|
the GList of GrlKeyIDs to request. [element-type GObject.ParamSpec] |
|
the resolution mode |
|
a GError, or NULL
|
Returns : |
a filled GrlMedia. [transfer full] |
Since 0.1.6
void grl_media_source_store (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,GrlMediaSourceStoreCb callback
,gpointer user_data
);
Store the media
into the parent
container
This method is asynchronous.
|
a media source |
|
a parent to store the data transfer objects. [allow-none] |
|
a data transfer object |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Since 0.1.4
void grl_media_source_store_sync (GrlMediaSource *source
,GrlMediaBox *parent
,GrlMedia *media
,GError **error
);
Store the media
into the parent
container.
This method is synchronous.
|
a media source |
|
a GrlMediaBox to store the data transfer objects. [allow-none] |
|
a GrlMedia data transfer object |
|
a GError, or NULL
|
Since 0.1.6
void grl_media_source_remove (GrlMediaSource *source
,GrlMedia *media
,GrlMediaSourceRemoveCb callback
,gpointer user_data
);
Remove a media
from the source
repository.
This method is asynchronous.
|
a media source |
|
a data transfer object |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Since 0.1.4
void grl_media_source_remove_sync (GrlMediaSource *source
,GrlMedia *media
,GError **error
);
Remove a media
from the source
repository.
This method is synchronous.
|
a media source |
|
a data transfer object |
|
a GError, or NULL
|
Since 0.1.6
void grl_media_source_cancel (GrlMediaSource *source
,guint operation_id
);
Cancel a running method.
The derived class must implement the cancel vmethod in order to honour the request correctly. Otherwise, the operation will not be interrupted.
In all cases, if this function is called on an ongoing operation, the
corresponding callback will be called with the
GRL_CORE_ERROR_OPERATION_CANCELLED
error set, and no more action will be
taken for that operation after the said callback with error has been called.
|
a media source |
|
the identifier of the running operation, as returned by the function that started it |
Since 0.1.1
void grl_media_source_set_operation_data (GrlMediaSource *source
,guint operation_id
,gpointer data
);
Attach a pointer to the specific operation.
|
a media source |
|
the identifier of a running operation |
|
the data to attach |
Since 0.1.1
gpointer grl_media_source_get_operation_data (GrlMediaSource *source
,guint operation_id
);
Obtains the previously attached data
|
a media source |
|
the identifier of a running operation |
Returns : |
The previously attached data. [transfer none] |
Since 0.1.1
void grl_media_source_set_auto_split_threshold (GrlMediaSource *source
,guint threshold
);
TBD
|
a media source |
|
the threshold to request |
Since 0.1.1
guint grl_media_source_get_auto_split_threshold
(GrlMediaSource *source
);
TBD
|
a media source |
Returns : |
the assigned threshold |
Since 0.1.1
gboolean grl_media_source_test_media_from_uri (GrlMediaSource *source
,const gchar *uri
);
Tests whether source
can instantiate a GrlMedia object representing
the media resource exposed at uri
.
|
a media source |
|
A URI that can be used to identify a media resource |
Returns : |
TRUE if it can, FALSE otherwise.
This method is synchronous. |
Since 0.1.7
void grl_media_source_get_media_from_uri (GrlMediaSource *source
,const gchar *uri
,const GList *keys
,GrlMetadataResolutionFlags flags
,GrlMediaSourceMetadataCb callback
,gpointer user_data
);
Creates an instance of GrlMedia representing the media resource
exposed at uri
.
It is recommended to call grl_media_source_test_media_from_uri()
before
invoking this to check whether the target source can theoretically do the
resolution.
This method is asynchronous.
|
a media source |
|
A URI that can be used to identify a media resource |
|
A list of keys to resolve |
|
the resolution mode |
|
the user defined callback. [scope notified] |
|
the user data to pass in the callback |
Since 0.1.7
"content-changed"
signalvoid user_function (GrlMediaSource *source,
GrlMedia *media,
GrlMediaSourceChangeType change_type,
gboolean location_unknown,
gpointer user_data) : Action
Signals that the content in the source has changed. Usually media
is a
GrlBox, 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.
For the cases where the source can only signal that a change happened, but
not where, it would use the root box (NULL
id) and set location_unknown as
to TRUE
.
|
source that has changed |
|
the media that changed or one of its ancestors |
|
the kind of change that ocurred |
|
TRUE if the change happened in media itself or in one
of its direct children (when media is a GrlMediaBox). FALSE otherwise |
|
user data set when the signal handler was connected. |
Since 0.1.9