MafwSource

MafwSource — base class for sources

Synopsis

                    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                (*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_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);

Object Hierarchy

  GObject
   +----MafwExtension
         +----MafwSource

Signals

  "container-changed"                              : Run First / Action
  "metadata-changed"                               : Run First / Action

Description

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.

Details

MafwSource

typedef struct _MafwSource MafwSource;

MafwSource object structure


MAFW_SOURCE_ERROR

#define MAFW_SOURCE_ERROR g_quark_from_static_string("com.nokia.mafw.error.source")

Gets a quark for source errors


MAFW_SOURCE_BROWSE_ALL

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


MAFW_SOURCE_INVALID_BROWSE_ID

#define MAFW_SOURCE_INVALID_BROWSE_ID (~0)

Invalid browse session id.


MAFW_SOURCE_KEY_WILDCARD

#define MAFW_SOURCE_KEY_WILDCARD "*"

Wildcard to get all available metadata.


MAFW_SOURCE_NO_KEYS

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


MAFW_SOURCE_ALL_KEYS

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


MAFW_SOURCE_LIST()

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

Note

The returned array is allocated on the stack, thus it becomes invalid after exiting the current frame. To keep it afterwards wrap it in g_strdupv().

... : list of elements

MAFW_SOURCE_MKPTRLIST()

#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

MAFW_SOURCE_PTRLIST()

#define             MAFW_SOURCE_PTRLIST(...)

Like MAFW_SOURCE_LIST() but returns an unterminated void-pointer array.

... : list of elements

enum MafwSourceError

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

MAFW_SOURCE_ERROR_INVALID_OBJECT_ID Object id syntax not valid.
MAFW_SOURCE_ERROR_OBJECT_ID_NOT_AVAILABLE Item with the specified object id was not found.
MAFW_SOURCE_ERROR_INVALID_SEARCH_STRING Invalid search filter syntax.
MAFW_SOURCE_ERROR_INVALID_SORT_STRING Invalid sort criteria syntax.
MAFW_SOURCE_ERROR_INVALID_BROWSE_ID The specified browse id didn't exist.
MAFW_SOURCE_ERROR_PEER Error occurred in the peer.
MAFW_SOURCE_ERROR_BROWSE_RESULT_FAILED Browse result parsing failed
MAFW_SOURCE_ERROR_GET_METADATA_RESULT_FAILED Metadata result parsing failed
MAFW_SOURCE_ERROR_UNSUPPORTED_METADATA_KEY Source doesn't support the provided metadata key
MAFW_SOURCE_ERROR_DESTROY_OBJECT_FAILED
MAFW_SOURCE_ERROR_PLAYLIST_PARSING_FAILED

MafwSourceBrowseResultCb ()

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.

MafwSourceMetadataResultCb ()

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.

MafwSourceObjectCreatedCb ()

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.

MafwSourceObjectDestroyedCb ()

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.

MafwSourceMetadataSetCb ()

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.

mafw_source_browse ()

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.

mafw_source_cancel_browse ()

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

mafw_source_get_metadata ()

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.

mafw_source_create_object ()

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.

mafw_source_destroy_object ()

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.

mafw_source_set_metadata ()

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.

mafw_source_all_keys ()

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.

mafw_source_split_objectid ()

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.

mafw_source_create_objectid ()

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

Signal Details

The "container-changed" signal

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

The "metadata-changed" signal

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