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.

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.

MAFW_SOURCE_PTRLIST()

#define             MAFW_SOURCE_PTRLIST(...)

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

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

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.

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.

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.

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.

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.

mafw_source_browse ()

guint               mafw_source_browse                  (MafwSource *self,
                                                         const gchar *object_id,
                                                         gboolean recursive,
                                                         const gchar *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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.