|
|
|
MAFW Reference Manual | |
|---|---|---|---|---|
MafwPlaylist;
#define MAFW_PLAYLIST_ERROR
enum MafwPlaylistError;
void (*MafwPlaylistGetItemsCB) (MafwPlaylist *pls,
guint index,
const gchar *object_id,
GHashTable *metadata,
gpointer cbarg);
gboolean mafw_playlist_clear (MafwPlaylist *playlist,
GError **error);
gchar* mafw_playlist_get_item (MafwPlaylist *playlist,
guint index,
GError **error);
gchar** mafw_playlist_get_items (MafwPlaylist *playlist,
guint first_index,
guint last_index,
GError **error);
gchar* mafw_playlist_get_name (MafwPlaylist *pls);
gboolean mafw_playlist_get_repeat (MafwPlaylist *pls);
guint mafw_playlist_get_size (MafwPlaylist *playlist,
GError **error);
gboolean mafw_playlist_insert_item (MafwPlaylist *playlist,
guint index,
const gchar *objectid,
GError **error);
gboolean mafw_playlist_insert_items (MafwPlaylist *playlist,
guint index,
const gchar **objectid,
GError **error);
gboolean mafw_playlist_insert_uri (MafwPlaylist *playlist,
guint index,
const gchar *uri,
GError **error);
gboolean mafw_playlist_append_item (MafwPlaylist *playlist,
const gchar *oid,
GError **error);
gboolean mafw_playlist_append_items (MafwPlaylist *playlist,
const gchar **oid,
GError **error);
gboolean mafw_playlist_append_uri (MafwPlaylist *playlist,
const gchar *uri,
GError **error);
gboolean mafw_playlist_move_item (MafwPlaylist *playlist,
guint from,
guint to,
GError **error);
gboolean mafw_playlist_remove_item (MafwPlaylist *playlist,
guint index,
GError **error);
void mafw_playlist_set_name (MafwPlaylist *pls,
const gchar *name);
void mafw_playlist_set_repeat (MafwPlaylist *pls,
gboolean repeat);
gboolean mafw_playlist_is_shuffled (MafwPlaylist *pls);
gboolean mafw_playlist_shuffle (MafwPlaylist *playlist,
GError **error);
gboolean mafw_playlist_unshuffle (MafwPlaylist *playlist,
GError **error);
void mafw_playlist_get_starting_index (MafwPlaylist *playlist,
guint *index,
gchar **object_id,
GError **error);
void mafw_playlist_get_last_index (MafwPlaylist *playlist,
guint *index,
gchar **object_id,
GError **error);
gboolean mafw_playlist_get_next (MafwPlaylist *playlist,
guint *index,
gchar **object_id,
GError **error);
gboolean mafw_playlist_get_prev (MafwPlaylist *playlist,
guint *index,
gchar **object_id,
GError **error);
gpointer mafw_playlist_get_items_md (MafwPlaylist *pls,
guint from,
gint to,
const gchar *const keys[],
MafwPlaylistGetItemsCB cb,
gpointer cbarg,
GDestroyNotify free_cbarg);
void mafw_playlist_cancel_get_items_md (gconstpointer op);
gboolean mafw_playlist_decrement_use_count (MafwPlaylist *playlist,
GError **error);
gboolean mafw_playlist_increment_use_count (MafwPlaylist *playlist,
GError **error);
"is-shuffled" gboolean : Read "name" gchar* : Read / Write "repeat" gboolean : Read / Write
Implementations of the MafwPlaylist interface allow the UI
developer to store a list of Object IDs, and make a MafwRenderer play
from it continuously using mafw_renderer_assign_playlist().
Basic operations are: inserting an item
(mafw_playlist_insert_item()), removing an item
(mafw_playlist_remove_item()), moving an item
(mafw_playlist_move_item()).
A MafwPlaylist can also be shuffled (mafw_playlist_shuffle()),
which operation randomizes the `playing order' (that renderers use to
traverse the playlist). mafw_playlist_get_items_md() provides a convenient
way for retrieving multiple items and their metadata asynchronously.
Currently the only existing playlist implementation is MafwProxyPlaylist (in the libmafw-shared library).
typedef struct _MafwPlaylist MafwPlaylist;
Instance of object implementing MafwPlaylistIface.
#define MAFW_PLAYLIST_ERROR g_quark_from_static_string("com.nokia.mafw.error.playlist")
Gets a quark for playlists errors
typedef enum
{
/* Playlist errors */
MAFW_PLAYLIST_ERROR_DATABASE,
MAFW_PLAYLIST_ERROR_INVALID_NAME,
MAFW_PLAYLIST_ERROR_INVALID_INDEX,
MAFW_PLAYLIST_ERROR_PLAYLIST_NOT_FOUND,
MAFW_PLAYLIST_ERROR_IMPORT_FAILED,
MAFW_PLAYLIST_ERROR_INVALID_IMPORT_ID
} MafwPlaylistError;
MAFW playlist error code definitions
void (*MafwPlaylistGetItemsCB) (MafwPlaylist *pls, guint index, const gchar *object_id, GHashTable *metadata, gpointer cbarg);
Callback prototype for mafw_playlist_get_items_md().
pls : |
the MafwPlaylist instance. |
index : |
item index. |
object_id : |
object_id of the item. |
metadata : |
the requested metadata. |
cbarg : |
user-specified additional argument. |
gboolean mafw_playlist_clear (MafwPlaylist *playlist, GError **error);
Removes all entries from the given playlist.
playlist : |
a MafwPlaylist instance. |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error,
details are set in the error argument.
|
gchar* mafw_playlist_get_item (MafwPlaylist *playlist, guint index, GError **error);
Gets the item at the given playlist index.
playlist : |
a MafwPlaylist instance. |
index : |
an index of an item to get from playlist. Valid value range is between 0 and (playlist size - 1). |
error : |
return location for a GError, or NULL |
| Returns : | the item at the given index or NULL if not available. Must be
freed with g_free(). In case of error, details are set in the error
argument.
|
gchar** mafw_playlist_get_items (MafwPlaylist *playlist, guint first_index, guint last_index, GError **error);
Get the items between the given indicies from the given playlist.
playlist : |
a MafwPlaylist instance. |
first_index : |
the first index of an item to get from playlist. Valid value range is between 0 and (playlist size - 1). |
last_index : |
the last index of an item to get from playlist. Valid value range is between 0 and (playlist size - 1). |
error : |
return location for a GError, or NULL |
| Returns : | NULL terminated array of the items from the given index or
NULL if not available. Must be
freed with g_strfreev(). In case of error, details are set in the error
argument.
|
gchar* mafw_playlist_get_name (MafwPlaylist *pls);
Gets the playlist name.
pls : |
a MafwPlaylist instance. |
| Returns : | a newly allocated string with the name of the pls.
|
gboolean mafw_playlist_get_repeat (MafwPlaylist *pls);
Gets the repeat property of pls.
pls : |
a MafwPlaylist instance. |
| Returns : | the repeat property of pls.
|
guint mafw_playlist_get_size (MafwPlaylist *playlist, GError **error);
Gets the number of items in the playlist.
playlist : |
a MafwPlaylist instance. |
error : |
return location for a GError, or NULL |
| Returns : | the number of elements in the playlist. In case of error, details are set in the error argument. |
gboolean mafw_playlist_insert_item (MafwPlaylist *playlist, guint index, const gchar *objectid, GError **error);
Inserts an item at the given position in the playlist. The index
parameter should be an absolute visual index (i.e. not in playing
order). If objectid is appended to the list it will be played last.
Otherwise it will inherit the playing position of the index:th item,
and all subsequent items are moved downwards.
playlist : |
a MafwPlaylist instance. |
index : |
the position to insert the item at. Valid value range is between 0 (insert before all existing items) and playlist size (append). |
objectid : |
the ID of the item to insert into the playlist. |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_insert_items (MafwPlaylist *playlist, guint index, const gchar **objectid, GError **error);
Inserts items at the given position in the playlist. The index
parameter should be an absolute visual index (i.e. not in playing
order).
playlist : |
a MafwPlaylist instance. |
index : |
the position to insert the items at. Valid value range is between 0 (insert before all existing items) and playlist size (append). |
objectid : |
NULL terminated array of object-ids to insert into the playlist. |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_insert_uri (MafwPlaylist *playlist, guint index, const gchar *uri, GError **error);
Insert an uri in the playlist.
playlist : |
playlist |
index : |
index |
uri : |
uri |
error : |
an error |
| Returns : | TRUE if ok, FALSE otherwise
|
gboolean mafw_playlist_append_item (MafwPlaylist *playlist, const gchar *oid, GError **error);
Appends objectid to the playlist. The item will be played last.
playlist : |
a MafwPlaylist instance. |
oid : |
the ID of the item to insert into the playlist. |
error : |
return location for a GError, or NULL.
|
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_append_items (MafwPlaylist *playlist, const gchar **oid, GError **error);
Appends objectids to the playlist.
playlist : |
a MafwPlaylist instance. |
oid : |
NULL terminated array of object-ids to insert into the playlist. |
error : |
return location for a GError, or NULL.
|
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_append_uri (MafwPlaylist *playlist, const gchar *uri, GError **error);
Appends the given uri to the playlist (using mafw_source_create_objectid()
to transform it to an object id).
playlist : |
a MafwPlaylist instance. |
uri : |
an uri. |
error : |
location for a GError or NULL.
|
| Returns : | TRUE if the operation was successful. Otherwise, error contains
details.
|
gboolean mafw_playlist_move_item (MafwPlaylist *playlist, guint from, guint to, GError **error);
Moves an item in the playlist from one position to another. Notice that both locations must be valid for the given playlist (i.e. within the boundaries of the playlist).
The playing order of the playlist is not affected by the operation. That is, if the $i:th item played at the $o:th position before moving the $i:th item will be played at the corresponding $o:th position after the move too.
Examples:
playlist = [A, B, C, D]
mafw_playlist_move_item(playlist, 0, 1) -> [B, A, C, D]
mafw_playlist_move_item(playlist, 3, 1) -> [B, D, A, C]
playlist : |
a MafwPlaylist instance. |
from : |
a position in the playlist to move an item from. Valid value range is between 0 and (playlist size - 1). |
to : |
a position in the playlist move the item to. Valid
value range is between 0 and playlist size, and must not
be equal to from.
|
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_remove_item (MafwPlaylist *playlist, guint index, GError **error);
Removes an item from a playlist. The index parameter is an
absolute visual index.
playlist : |
a MafwPlaylist instance. |
index : |
position of an element to remove in the playlist. Valid value is between 0 and (playlist size - 1). |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
void mafw_playlist_set_name (MafwPlaylist *pls, const gchar *name);
Sets the name of the playlist.
pls : |
a MafwPlaylist instance. |
name : |
the name to set. |
void mafw_playlist_set_repeat (MafwPlaylist *pls, gboolean repeat);
Sets the repeat property of pls.
pls : |
a MafwPlaylist instance. |
repeat : |
repeat property. |
gboolean mafw_playlist_is_shuffled (MafwPlaylist *pls);
Gets the information about shuffle.
pls : |
a MafwPlaylist instance. |
| Returns : | the is-shuffled property of pls.
|
gboolean mafw_playlist_shuffle (MafwPlaylist *playlist, GError **error);
Shuffles the playlist. Shuffling means randomizing the playlist's playing order which renderers use.
playlist : |
a MafwPlaylist instance. |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_unshuffle (MafwPlaylist *playlist, GError **error);
Restores the original playing order of a playlist.
playlist : |
a MafwPlaylist instance. |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
void mafw_playlist_get_starting_index (MafwPlaylist *playlist, guint *index, gchar **object_id, GError **error);
Sets the objectid and the visual index of the first playable item. In case
of error, error will be set, if any given.
playlist : |
a MafwPlaylist instance. |
index : |
Pointer to an unsigned-integer, where the index will be updated to visual index of the first item |
object_id : |
return location for the object-id of the first playable item |
error : |
return location for a GError, or NULL |
void mafw_playlist_get_last_index (MafwPlaylist *playlist, guint *index, gchar **object_id, GError **error);
Sets the objectid and the visual index of the last playable item. In case
of error, error will be set, if any given.
playlist : |
a MafwPlaylist instance. |
index : |
Pointer to an unsigned-integer, where the index will be updated to visual index of the last item |
object_id : |
return location for the object-id of the last playable item |
error : |
return location for a GError, or NULL |
gboolean mafw_playlist_get_next (MafwPlaylist *playlist, guint *index, gchar **object_id, GError **error);
Sets the objectid and the visual index of the next playable item. The current
item's visual index is stored in index. In case of error, error will be
set, if any given.
playlist : |
a MafwPlaylist instance. |
index : |
Pointer to an unsigned-integer what stores the current item. It will be updated to the visual index of the next playable item. |
object_id : |
return location for the object-id if the next playable item |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful, FALSE otherwise. In case of
error, details are set in the error argument.
|
gboolean mafw_playlist_get_prev (MafwPlaylist *playlist, guint *index, gchar **object_id, GError **error);
Sets the objectid and the visual index of the previous playable item. The current
item's visual index is stored in index. In case of error, error will be
set, if any given.
playlist : |
a MafwPlaylist instance. |
index : |
Pointer to an unsigned-integer what stores the current item. It will be updated to the visual index of the previous playable item. |
object_id : |
return location for the object-id if the previous playable item |
error : |
return location for a GError, or NULL |
| Returns : | TRUE if the operation was successful, FALSE otherwise. In case of
error, details are set in the error argument.
|
gpointer mafw_playlist_get_items_md (MafwPlaylist *pls, guint from, gint to, const gchar *const keys[], MafwPlaylistGetItemsCB cb, gpointer cbarg, GDestroyNotify free_cbarg);
Fetch items and metadata (keys) from pls asynchronously via an idle
callback. For each item in pls, the requested metadata keys will be
queried, and eventually cb will be called. It is not guaranteed that the
callback is called in the order of the items. At the very end, free_cbarg
is called. It is possible to cancel the operation with
mafw_playlist_cancel_get_items_md().
pls : |
a MafwPlaylist instance. |
from : |
first index, inclusive. |
to : |
last index, inclusive, or a negative number for the all remaining elements. |
keys : |
metadata keys to retrieve along with the items. |
cb : |
callback, which gets called with the results. |
cbarg : |
additional data passed to cb.
|
free_cbarg : |
destructor of cbarg, called after the callback has been called
for the very last time.
|
| Returns : | an opaque identifier which can be used to
mafw_playlist_cancel_get_items_md() the operation.
|
void mafw_playlist_cancel_get_items_md (gconstpointer op);
Cancels a previous mafw_playlist_get_items_md() operation.
op : |
the operation identifier. |
gboolean mafw_playlist_decrement_use_count (MafwPlaylist *playlist, GError **error);
Decrements the use count of the playlist. The counter must be decremented when the playlist is unassigned to some renderer.
playlist : |
a MafwPlaylist instance. |
error : |
a GError to store an error if somethings goes wrong. |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
gboolean mafw_playlist_increment_use_count (MafwPlaylist *playlist, GError **error);
Increments the use count of the playlist. The counter must be incremented when the playlist is assigned to some renderer.
playlist : |
a MafwPlaylist instance. |
error : |
a GError to store an error if somethings goes wrong. |
| Returns : | TRUE if the operation was successful. In case of error, details
are set in the error argument.
|
"is-shuffled" property"is-shuffled" gboolean : Read
If TRUE then the playlist's playing order is
different from it's visual order.
Default value: FALSE
"contents-changed" signalvoid user_function (MafwPlaylist *playlist, guint from, guint nremove, guint nreplace, gpointer user_data) : Run First
The ::contents_changed signal on MafwPlaylist is emitted when the playlist contents are modified. This can happen during insert, remove, and clear. The parametes define the first item affected by the change, number of items to remove and number of items to get in place of the removed items.
Examples:
- One item was added to index 5 to a playlist of 10 items: from = 5, nremove = 0, nreplace = 1.
- Two items were removed from indices 3 & 4 from a playlist of 10 items: from = 3, nremove = 2, nreplace = 5.
- A playlist of 10 items was cleared: from = 0, nremove = 10, nreplace = 0.
Callback prototype example:
static void mafw_playlist_changed(MafwPlaylist *playlist, guint from, guint nremove, guint nreplace);
playlist : |
The signaling MafwPlaylist object. |
from : |
The index of the first element in the range of modified items. |
nremove : |
Number of items to remove, starting at from.
|
nreplace : |
Number of items to to get (in place of removed
items), starting at from.
|
user_data : |
user data set when the signal handler was connected. |
"item-moved" signalvoid user_function (MafwPlaylist *playlist, guint from, guint to, gpointer user_data) : Run First
The ::item-moved signal on MafwPlaylist is emitted when an item of the playlist has been moved to a new place.
Callback prototype example:
static void mafw_playlist_item_moved(MafwPlaylist *playlist, guint from, guint to);
playlist : |
The signaling MafwPlaylist object. |
from : |
The old index of the item |
to : |
The new index of the item |
user_data : |
user data set when the signal handler was connected. |