![]() |
![]() |
![]() |
MAFW Reference Manual | ![]() |
---|---|---|---|---|
MafwSource; #define MAFW_SOURCE_ERROR #define MAFW_SOURCE_BROWSE_ALL #define MAFW_SOURCE_INVALID_BROWSE_ID #define MAFW_SOURCE_KEY_WILDCARD #define MAFW_SOURCE_NO_KEYS #define MAFW_SOURCE_ALL_KEYS #define MAFW_SOURCE_LIST (...) #define MAFW_SOURCE_MKPTRLIST (...) #define MAFW_SOURCE_PTRLIST (...) enum MafwSourceError; void (*MafwSourceBrowseResultCb) (MafwSource *self, guint browse_id, gint remaining_count, guint index, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error); void (*MafwSourceMetadataResultCb) (MafwSource *self, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error); void (*MafwSourceMetadataResultsCb) (MafwSource *self, GHashTable *metadatas, gpointer user_data, const GError *error); void (*MafwSourceObjectCreatedCb) (MafwSource *self, const gchar *object_id, gpointer user_data, const GError *error); void (*MafwSourceObjectDestroyedCb) (MafwSource *self, const gchar *object_id, gpointer user_data, const GError *error); void (*MafwSourceMetadataSetCb) (MafwSource *self, const gchar *object_id, const gchar **failed_keys, gpointer user_data, const GError *error); guint mafw_source_browse (MafwSource *self, const gchar *object_id, gboolean recursive, const MafwFilter *filter, const gchar *sort_criteria, const gchar *const *metadata_keys, guint skip_count, guint item_count, MafwSourceBrowseResultCb browse_cb, gpointer user_data); gboolean mafw_source_cancel_browse (MafwSource *self, guint browse_id, GError **error); void mafw_source_get_metadata (MafwSource *self, const gchar *object_id, const gchar *const *metadata_keys, MafwSourceMetadataResultCb metadata_cb, gpointer user_data); void mafw_source_get_metadatas (MafwSource *self, const gchar **object_ids, const gchar *const *metadata_keys, MafwSourceMetadataResultsCb metadatas_cb, gpointer user_data); void mafw_source_create_object (MafwSource *self, const gchar *parent, GHashTable *metadata, MafwSourceObjectCreatedCb cb, gpointer user_data); void mafw_source_destroy_object (MafwSource *self, const gchar *object_id, MafwSourceObjectDestroyedCb cb, gpointer user_data); void mafw_source_set_metadata (MafwSource *self, const gchar *object_id, GHashTable *metadata, MafwSourceMetadataSetCb cb, gpointer user_data); gboolean mafw_source_all_keys (const gchar *const *keys); gboolean mafw_source_split_objectid (gchar const *objectid, gchar **extensionid, gchar **itemid); gchar* mafw_source_create_objectid (const gchar *uri);
"container-changed" : Run First / Action "metadata-changed" : Run First / Action "updating" : Run First / Action
MafwSource is an abstract base class which individual sources should inherit from. Sources represent repositories of multimedia contents, which can either reside in the local file system, on a remote server or being generated on-the-fly for example by aggregating other sources. Sources are comparable to GnomeVFS handlers but they offer extended functionality.
Object IDs:
Individual content items are identified by their `Object ID'. Sources produce and renderers consume Object IDs, which are only meaningful for the providing sources themselves. An object ID is a string:
`<Source ID>::<Item ID>'
consisting of the Source ID of the originating source and a unique (within the individual source's scope) Item ID, separated by two colons. See the MafwRegistry description for `Source ID's. Each object ID should be unique, persistent and portable, if possible. Applications may assume that an object ID corresponds to a single content item, and this should be maintained across shutdowns, reboots and reinstalls.
MafwSource's can be acquired from a MafwRegistry. The two main
operations of a source are browsing for content items with
mafw_source_browse()
and acquiring metadata information related to
individual items with mafw_source_get_metadata()
. These functions
are the minimum that each source should provide.
In addition to getting content information, one can also modify the contents
with optional methods that include mafw_source_create_object()
for object
creation, mafw_source_destroy_object()
for object destruction and
mafw_source_set_metadata()
for modifying the metadata of individual items.
#define MAFW_SOURCE_ERROR g_quark_from_static_string("com.nokia.mafw.error.source")
Gets a quark for source errors
#define MAFW_SOURCE_BROWSE_ALL (0)
If passed as item_count
to mafw_source_browse()
, it means that
the caller is interested in all resulting elements.
#define MAFW_SOURCE_KEY_WILDCARD "*"
Wildcard to get all available metadata.
#define MAFW_SOURCE_NO_KEYS _mafw_source_no_keys
Value usable as metadata_keys
of browse()
, denoting that the
caller is not interested in any metadata. Its value is an
zero-length, NULL
-terminated array.
#define MAFW_SOURCE_ALL_KEYS _mafw_source_all_keys
Value usable as metadata_keys
of mafw_source_browse()
and
mafw_source_get_metadata()
, denoting that the caller is interested
in all possible metadata the source can retrieve. Its value is a
NULL
-terminated array with one single "*" element.
#define MAFW_SOURCE_LIST(...)
Constructs and returns a NULL
-terminated string array from the varadic
arguments, suitable to be passed to mafw_source_browse()
as object IDs or
metadata tags of interest. The arguments are evaluated only once and the
list can be empty.
g_strdupv()
.
... : |
list of elements |
#define MAFW_SOURCE_MKPTRLIST(...)
Like MAFW_SOURCE_PTRLIST()
but returns a newly allocated array of pointers
of its arguments.
The arguments are evaluated only once.
... : |
list of elements |
#define MAFW_SOURCE_PTRLIST(...)
Like MAFW_SOURCE_LIST()
but returns an unterminated void-pointer array.
... : |
list of elements |
typedef enum { /* Source errors */ MAFW_SOURCE_ERROR_INVALID_OBJECT_ID, MAFW_SOURCE_ERROR_OBJECT_ID_NOT_AVAILABLE, MAFW_SOURCE_ERROR_INVALID_SEARCH_STRING, MAFW_SOURCE_ERROR_INVALID_SORT_STRING, MAFW_SOURCE_ERROR_INVALID_BROWSE_ID, /* Or bundle to invalid_params? */ MAFW_SOURCE_ERROR_PEER, MAFW_SOURCE_ERROR_BROWSE_RESULT_FAILED, MAFW_SOURCE_ERROR_GET_METADATA_RESULT_FAILED, MAFW_SOURCE_ERROR_UNSUPPORTED_METADATA_KEY, MAFW_SOURCE_ERROR_DESTROY_OBJECT_FAILED, MAFW_SOURCE_ERROR_PLAYLIST_PARSING_FAILED } MafwSourceError;
MAFW source specific error code definitions
void (*MafwSourceBrowseResultCb) (MafwSource *self, guint browse_id, gint remaining_count, guint index, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error);
Callback prototype for browse results. For a successful mafw_source_browse()
call, the number of callbacks depends on the number of items requested and
number of items available. The callback should be called at least once,
unless mafw_source_browse()
returned with an error.
object_id
tells the unique object ID that metadata
is related to. It
should not be NULL
unless there are no results available. If an error has
occurred, error
is set non-NULL
, the contents of metadata
can be NULL
and remaining_count
and index
might be invalid. No more results are to
be expected after a non-NULL
error.
remaining_count
tells the number of results that are to be expected for
the browse session identified by browse_id
. If 10 items were requested
and the currently browsed container has at least 10 items, remaining_count
should go from 9 to 0. The same goes for index
, which tells the index of
the current item within the current browse session; in the aforementioned
example result set index
should go from 0 to 9. When remaining_count
reaches zero, the session has ended and no more results are to be expected.
browse_id
is also invalidated after receiving zero remaining_count
.
when there are no more results available (which is not considered an error
situation) the source must call the callback exactly once with zero
remaining_count
. This applies also when the browsed container is completely
empty or skip_count
in mafw_source_browse()
is beyond the container's
child count (in both of these cases object_id
is NULL
).
Cancelling an ongoing browse session with mafw_source_cancel_browse()
will
result in exactly one callback with zero remaining_count
. If the last item
has already been signalled (with zero remaining_count
), cancelling will
have no effect. Otherwise the browse session will terminate immediately
with one last termination signal having zero remaining_count
.
self : |
The emitting MafwSource. |
browse_id : |
The browse session ID that these results are associated to. |
remaining_count : |
Number of remaining results in the current browse session. |
index : |
The current item's index in the current browse session. |
object_id : |
The object ID of the current item. |
metadata : |
Metadata related to object_id as "s". The tag names and
the concrete types of their values are defined in MafwMetadata. The source
is expected to make its best effort to obtain all metadata
keys requested in mafw_source_browse() , but there are no
guarantees of them all being present in metadata (usually
because the source might not support some particular key).
On the other hand, the source may include additional keys on
its own, even if not requested by the caller, however this is
not recommended.
The table is destroyed by the source after the callback returns.
|
user_data : |
Optional user data pointer passed to mafw_source_browse() .
|
error : |
Non-NULL if an error occurred.
|
void (*MafwSourceMetadataResultCb) (MafwSource *self, const gchar *object_id, GHashTable *metadata, gpointer user_data, const GError *error);
Callback prototype for metadata results. If both object_id
and error
are
set, then the error affects only the actual item (e.g. permission denied,
etc.). If error
is set, the contents of metadata
might be set NULL
.
Exactly one callback is expected for a mafw_source_get_metadata()
call.
self : |
The emitting MafwSource. |
object_id : |
The object ID of the current item. |
metadata : |
Metadata of object_id as GValue's, identical to
MafwSourceBrowseResultCb.
|
user_data : |
Optional user data pointer passed to mafw_source_get_metadata() .
|
error : |
Non-NULL if an error occurred.
|
void (*MafwSourceMetadataResultsCb) (MafwSource *self, GHashTable *metadatas, gpointer user_data, const GError *error);
Callback prototype for metadata results.
If error
is set, the contents of metadatas
might be set NULL
.
Exactly one callback is expected for a mafw_source_get_metadatas()
call.
self : |
The emitting MafwSource. |
metadatas : |
Metadatas of the asked object-ids. The key of the hash-table is the object-id, the value is the metadatas of the object as GValue's, identical to MafwSourceBrowseResultCb. |
user_data : |
Optional user data pointer passed to
mafw_source_get_metadatas() .
|
error : |
Non-NULL if an error occurred.
|
void (*MafwSourceObjectCreatedCb) (MafwSource *self, const gchar *object_id, gpointer user_data, const GError *error);
Callback prototype for object creation result. If any errors were encountered
during object creation, error
is set non-NULL
, while object_id
might also
be NULL
.
Exactly one callback is expected for a mafw_source_create_object()
call.
self : |
The emitting MafwSource. |
object_id : |
The object ID of the newly created object or NULL if it could
not be created due to an error.
|
user_data : |
Optional user data pointer passed to mafw_source_create_object() .
|
error : |
Non-NULL if an error occurred.
|
void (*MafwSourceObjectDestroyedCb) (MafwSource *self, const gchar *object_id, gpointer user_data, const GError *error);
Callback prototype for object destruction result. If any errors were
encountered during object destruction, error
is set non-NULL
.
Exactly one callback is expected for a mafw_source_destroy_object()
call.
self : |
The emitting MafwSource. |
object_id : |
The object ID of the destroyed object. |
user_data : |
Optional user data pointer passed to mafw_source_destroy_object() .
|
error : |
Non-NULL if an error occurred.
|
void (*MafwSourceMetadataSetCb) (MafwSource *self, const gchar *object_id, const gchar **failed_keys, gpointer user_data, const GError *error);
Callback prototype for metadata editing/setting result. If error
is set,
failed_keys
contains a list of metadata keys that could not be set.
Exactly one callback is expected for a mafw_source_set_metadata()
call.
self : |
The emitting MafwSource. |
object_id : |
The object ID of the modified object. |
failed_keys : |
Null-terminated array of failed metadata keys or NULL
if the operation was completely successful.
|
user_data : |
Optional user data pointer passed to mafw_source_set_metadata() .
|
error : |
Non-NULL if an error occurred.
|
guint mafw_source_browse (MafwSource *self, const gchar *object_id, gboolean recursive, const MafwFilter *filter, const gchar *sort_criteria, const gchar *const *metadata_keys, guint skip_count, guint item_count, MafwSourceBrowseResultCb browse_cb, gpointer user_data);
Starts a browse session on the given source. The caller will be notified of
the results via the browse_cb
callback function.
sort_criteria
is a comma-separated list of metadata keys, each prefixed
with '+' or '-', indicating ascending or descending ordering. For example:
"+year,+artist" sorts first by year, then artists.
skip_count
and item_count
are similar to the `LIMIT' SQL clause:
specifying them means to only return at most item_count
items, skipping
skip_count
from the beginning of the result set. If the caller is
interested in all resulting elements, item_count
should be
MAFW_SOURCE_BROWSE_ALL.
metadata_keys
being equal to MAFW_SOURCE_NO_KEYS indicates that the caller
is not interested in any metadata, only in the resulting object ids. On the
other hand, if metadata_keys
is equal to MAFW_SOURCE_ALL_KEYS then the
source should try to retrieve all possible metadata with the results.
self : |
A MafwSource instance to browse. |
object_id : |
The starting object id to browse from (usually a container). |
recursive : |
TRUE , if browsing should be recursive.
|
filter : |
Filter criteria, see MafwFilter. |
sort_criteria : |
Sort criteria (i.e. the order in which results are expected) |
metadata_keys : |
A NULL -terminated array of requested metadata keys.
|
skip_count : |
Number of items to skip from the beginning. |
item_count : |
Number of items to return. |
browse_cb : |
Function to call with browse results, or inform about the error. |
user_data : |
Optional user data pointer passed along with browse_cb .
|
Returns : | The identifier of the browse session (which is also passed
to browse_cb ). If some arguments were invalid,
MAFW_SOURCE_INVALID_BROWSE_ID is returned, but the browse_cb will
be called.
|
gboolean mafw_source_cancel_browse (MafwSource *self, guint browse_id, GError **error);
Informs a MafwSource that browse results associated with
browse_id
are no longer of any interest. Sources stop the
operation right away, but it is not guaranteed that the callback of
mafw_source_browse()
would not be invoked anymore. It is not an
error if the request has already come to end.
self : |
A MafwSource instance. |
browse_id : |
The browse session to cancel. |
error : |
Location for a GError, or NULL
|
Returns : | FALSE if the operation failed (in which case error is also set).
|
void mafw_source_get_metadata (MafwSource *self, const gchar *object_id, const gchar *const *metadata_keys, MafwSourceMetadataResultCb metadata_cb, gpointer user_data);
Queries the metadata for the given object_id
. The caller is informed of
results via the metadata_cb
callback.
If metadata_keys
is MAFW_SOURCE_ALL_KEYS then the source should
try to retrieve all possible (see MafwMetadata) metadata it can
related to the given object.
self : |
A MafwSource instance. |
object_id : |
The object ID, whose metadata is being requested. |
metadata_keys : |
A NULL -terminated array of requested metadata keys.
|
metadata_cb : |
The function to call with results. |
user_data : |
Optional user data pointer passed along with metadata_cb .
|
void mafw_source_get_metadatas (MafwSource *self, const gchar **object_ids, const gchar *const *metadata_keys, MafwSourceMetadataResultsCb metadatas_cb, gpointer user_data);
Queries the metadatas for the given object_id
. The caller is informed of
results via the metadatas_cb
callback.
If metadata_keys
is MAFW_SOURCE_ALL_KEYS then the source should
try to retrieve all possible (see MafwMetadata) metadata it can
related to the given object.
self : |
A MafwSource instance. |
object_ids : |
NULL terminated list of object IDs, whose metadata is being requested.
|
metadata_keys : |
A NULL -terminated array of requested metadata keys.
|
metadatas_cb : |
The function to call with results. |
user_data : |
Optional user data pointer passed along with metadata_cb .
|
void mafw_source_create_object (MafwSource *self, const gchar *parent, GHashTable *metadata, MafwSourceObjectCreatedCb cb, gpointer user_data);
The intended semantics of this function is to create a new object in
parent
initially having at least metadata
. What it actually does
is quite up to the source, which may interpret parent
and metadata
freely. Returns FALSE
on failure and leaves the object unchanged.
Otherwise returns TRUE
and cb
will be activated with user_data
later.
self : |
A MafwSource instance. |
parent : |
Create the object inside this container (object ID). |
metadata : |
The metadata keys and values that the new object should have
initially; Can be NULL .
|
cb : |
The function to call when the operation is finished. |
user_data : |
Optional user data pointer passed along with cb .
|
void mafw_source_destroy_object (MafwSource *self, const gchar *object_id, MafwSourceObjectDestroyedCb cb, gpointer user_data);
The intended semantics of this function is to delete an object from the
given source so that it won't be encountered in browsing the parent
container of objectid
and any further operation on it will result in a
MAFW_SOURCE_ERROR_OBJECT_ID_NOT_AVAILABLE error. However, the actual
outcome is almost entirely up to the source except for the pieces mentioned
here. On failure this function returns FALSE
and leaves the object
unchanged. Otherwise returns TRUE
and cb
will be activated with user_data
later.
self : |
A MafwSource instance. |
object_id : |
The object ID of the object to destroy. |
cb : |
The function to call when the operation is finished. |
user_data : |
Optional user data pointer passed along with cb .
|
void mafw_source_set_metadata (MafwSource *self, const gchar *object_id, GHashTable *metadata, MafwSourceMetadataSetCb cb, gpointer user_data);
Updates the given metadata properties and their values to the given
object_id
. The caller is notified of operation success via cb
. The source
may set only a subset of all the defined keys, in which case, it can report
any failed keys with the callback along with an error describing the details.
self : |
A MafwSource instance. |
object_id : |
The object ID, whose metadata is being edited. |
metadata : |
A hash table containing the metadata to set for
object_id as GValues. The tag names and the concrete type of
their values go as defined in MafwMetadata
|
cb : |
The function to call when the operation is finished. |
user_data : |
Optional user data pointer passed along with cb .
|
gboolean mafw_source_all_keys (const gchar *const *keys);
Checks whether a source processing the requested keys
should return all
possible keys.
keys : |
A NULL -terminated array of strings.
|
Returns : | TRUE if the first element of the array is a single asterisk.
|
gboolean mafw_source_split_objectid (gchar const *objectid, gchar **extensionid, gchar **itemid);
Splits an object ID to source UUID and item ID. Use this function to determine to which sources does an objectid belong to. Source developers may also use this function to figure out which item does it refer to.
objectid : |
An object id to split. |
extensionid : |
If not NULL , where to place the source UUID part of objetid
in a newly allocated string.
|
itemid : |
Similarly, but for the item ID part. |
Returns : | FALSE if objectid is invalid.
|
gchar* mafw_source_create_objectid (const gchar *uri);
Creates an object ID pointing to uri
that can be used as if it
were obtained from a source. If uri
is not an URI, it's treated
as a local file system path. In that case if it's relative it's
assumed to be relative of the program's current working directory.
Finally, if uri
is empty the returned objectid will point to the
current working directory.
uri : |
A URI to create the object ID for or a UNIX file system path. |
Returns : | A newly-created object ID (must be freed). |
"container-changed"
signalvoid user_function (MafwSource *self, gchar *object_id, gpointer user_data) : Run First / Action
Emitted when a container's contents have changed.
self : |
The emitting MafwSource instance. |
object_id : |
The object ID of the changed container. |
user_data : |
user data set when the signal handler was connected. |
"metadata-changed"
signalvoid user_function (MafwSource *self, gchar *object_id, gpointer user_data) : Run First / Action
Emitted when the metadata related to an object has changed.
self : |
The emitting MafwSource instance. |
object_id : |
The object ID, whose metadata has changed |
user_data : |
user data set when the signal handler was connected. |
"updating"
signalvoid user_function (MafwSource *self, gint progress, gint processed_items, gint remaining_items, gint remaining_time, gpointer user_data) : Run First / Action
Emitted when a source is updating. 100% means the source is updated. '-1' in any parameter means an unknown value.
self : |
The emitting MafwSource instance. |
progress : |
Percentage of completness. |
processed_items : |
How many elements has been processed so far. |
remaining_items : |
How many items remain to be processed. |
remaining_time : |
Estimated time (in seconds) to finish the update. |
user_data : |
user data set when the signal handler was connected. |