MafwPlaylist

MafwPlaylist — Playlists in Mafw

Synopsis

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

Object Hierarchy

  GInterface
   +----MafwPlaylist

Properties

  "is-shuffled"              gboolean              : Read
  "name"                     gchar*                : Read / Write
  "repeat"                   gboolean              : Read / Write

Signals

  "contents-changed"                               : Run First
  "item-moved"                                     : Run First

Description

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

Details

MafwPlaylist

typedef struct _MafwPlaylist MafwPlaylist;

Instance of object implementing MafwPlaylistIface.


MAFW_PLAYLIST_ERROR

#define MAFW_PLAYLIST_ERROR g_quark_from_static_string("com.nokia.mafw.error.playlist")

Gets a quark for playlists errors


enum MafwPlaylistError

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

MAFW_PLAYLIST_ERROR_DATABASE Something was wrong with the database access.
MAFW_PLAYLIST_ERROR_INVALID_NAME Invalid playlist name.
MAFW_PLAYLIST_ERROR_INVALID_INDEX Invalid playlist index (out of bounds).
MAFW_PLAYLIST_ERROR_PLAYLIST_NOT_FOUND Couldn't find the playlist with given id or name.
MAFW_PLAYLIST_ERROR_IMPORT_FAILED Importing the playlist failed.
MAFW_PLAYLIST_ERROR_INVALID_IMPORT_ID Import-ID not found

MafwPlaylistGetItemsCB ()

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.

mafw_playlist_clear ()

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.

mafw_playlist_get_item ()

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.

mafw_playlist_get_name ()

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.

mafw_playlist_get_repeat ()

gboolean            mafw_playlist_get_repeat            (MafwPlaylist *pls);

Gets the repeat property of pls.

pls : a MafwPlaylist instance.
Returns : the repeat property of pls.

mafw_playlist_get_size ()

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.

mafw_playlist_insert_item ()

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.

mafw_playlist_insert_uri ()

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

mafw_playlist_append_item ()

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.

mafw_playlist_append_uri ()

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.

mafw_playlist_move_item ()

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.

mafw_playlist_remove_item ()

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.

mafw_playlist_set_name ()

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.

mafw_playlist_set_repeat ()

void                mafw_playlist_set_repeat            (MafwPlaylist *pls,
                                                         gboolean repeat);

Sets the repeat property of pls.

pls : a MafwPlaylist instance.
repeat : repeat property.

mafw_playlist_is_shuffled ()

gboolean            mafw_playlist_is_shuffled           (MafwPlaylist *pls);

Gets the information about shuffle.

pls : a MafwPlaylist instance.
Returns : the is-shuffled property of pls.

mafw_playlist_shuffle ()

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.

mafw_playlist_unshuffle ()

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.

mafw_playlist_get_starting_index ()

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

mafw_playlist_get_last_index ()

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

mafw_playlist_get_next ()

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.

mafw_playlist_get_prev ()

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.

mafw_playlist_get_items_md ()

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.

mafw_playlist_cancel_get_items_md ()

void                mafw_playlist_cancel_get_items_md   (gconstpointer op);

Cancels a previous mafw_playlist_get_items_md() operation.

op : the operation identifier.

mafw_playlist_decrement_use_count ()

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.

mafw_playlist_increment_use_count ()

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.

Property Details

The "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


The "name" property

  "name"                     gchar*                : Read / Write

The name of the playlist.

Default value: ""


The "repeat" property

  "repeat"                   gboolean              : Read / Write

If TRUE, the playlist wraps around when playing continuously.

Default value: FALSE

Signal Details

The "contents-changed" signal

void                user_function                      (MafwPlaylist *mafwplaylist,
                                                        guint         arg1,
                                                        guint         arg2,
                                                        guint         arg3,
                                                        gpointer      user_data)         : Run First

mafwplaylist : the object which received the signal.
arg1 :
arg2 :
arg3 :
user_data : user data set when the signal handler was connected.

The "item-moved" signal

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