MafwPlaylistManager

MafwPlaylistManager — Maintainer of the framework-wide playlists for a user

Synopsis

                    MafwPlaylistManager;
#define             MAFW_PLAYLIST_MANAGER_INVALID_IMPORT_ID
                    MafwPlaylistManagerItem;
void                (*MafwPlaylistManagerImportCb)      (MafwPlaylistManager *self,
                                                         guint import_id,
                                                         MafwProxyPlaylist *playlist,
                                                         gpointer user_data,
                                                         const GError *error);
MafwPlaylistManager* mafw_playlist_manager_get          (void);
MafwProxyPlaylist*  mafw_playlist_manager_create_playlist
                                                        (MafwPlaylistManager *self,
                                                         gchar const *name,
                                                         GError **errp);
gboolean            mafw_playlist_manager_destroy_playlist
                                                        (MafwPlaylistManager *self,
                                                         MafwProxyPlaylist *playlist,
                                                         GError **errp);
MafwProxyPlaylist*  mafw_playlist_manager_dup_playlist  (MafwPlaylistManager *self,
                                                         MafwProxyPlaylist *playlist,
                                                         gchar const *new_name,
                                                         GError **errp);
guint               mafw_playlist_manager_import        (MafwPlaylistManager *self,
                                                         const gchar *playlist,
                                                         const gchar *base_uri,
                                                         MafwPlaylistManagerImportCb cb,
                                                         gpointer user_data,
                                                         GError **error);
gboolean            mafw_playlist_manager_cancel_import (MafwPlaylistManager *self,
                                                         guint import_id,
                                                         GError **error);
MafwProxyPlaylist*  mafw_playlist_manager_get_playlist  (MafwPlaylistManager *self,
                                                         guint id,
                                                         GError **errp);
GPtrArray*          mafw_playlist_manager_get_playlists (MafwPlaylistManager *self,
                                                         GError **errp);
GArray*             mafw_playlist_manager_list_playlists
                                                        (MafwPlaylistManager *self,
                                                         GError **errp);
void                mafw_playlist_manager_free_list_of_playlists
                                                        (GArray *playlist_list);

Object Hierarchy

  GObject
   +----MafwPlaylistManager

Signals

  "playlist-created"                               : Run First / Action
  "playlist-destroyed"                             : Run First / Action
  "playlist-destruction-failed"                    : Run First / Action

Description

Framework-wide playlists are MafwPlaylist objects which represent shared resources among all applications of the framework. All applications know about the creation and the destruction of those playlists, and all of them can manipulate them equally, and will see the changes made by others.

The manager is the only one which can create MafwPlaylist objects. It ensures that the same playlist is always represented by he same object instance. Initially the list is empty, objects are created and added only when needed. The list may not contain every existing framework-wide playlists, but it should not have any one which have been destructed (for long times).

The manager communicates with a daemon (the playlist daemon) through D-BUS, which is responsible for the central maintenance of playlists. The daemon sends signals about playlist creations and destructions which are relayed by the manager to the application.

Since multiple instances of manager (in multiple applications) may be running at the same time it may happen more than one of them attempts to create or destroy the same list. This case care is taken to inform every application exactly once about the change in the list of playlists. To achieve this the manager does NOT emit GObject signals until the daemon confirms the operation. In the case of creation, the playlist is registered immediately (because its success can be taken for granted when the D-BUS method call returns). For destruction the playlist is NOT unregistered until comfirmation arrives.

One application has at most one instance of the manager, which can be accessed with mafw_playlist_manager_get(). While this object must not be unref:ed by the caller, it is free to keep a copy of the pointer.

Details

MafwPlaylistManager

typedef struct _MafwPlaylistManager MafwPlaylistManager;

Object structure

MAFW_PLAYLIST_MANAGER_INVALID_IMPORT_ID

#define MAFW_PLAYLIST_MANAGER_INVALID_IMPORT_ID (~0)

Invalid playlist import session id.

MafwPlaylistManagerItem

typedef struct {
	guint id;
	gchar *name;
} MafwPlaylistManagerItem;

mafw_playlist_manager_list_playlists() returns a GList of this structures.

guint id; playlist id
gchar *name; a dynamically allocated UTF-8 string.

MafwPlaylistManagerImportCb ()

void                (*MafwPlaylistManagerImportCb)      (MafwPlaylistManager *self,
                                                         guint import_id,
                                                         MafwProxyPlaylist *playlist,
                                                         gpointer user_data,
                                                         const GError *error);

Callback prototype for playlist import result. If any errors were encountered during playlist importing, error is set non-NULL, while playlist might also be NULL.

self : The emitting MafwPlaylistManager.
import_id : The import-ID of the import session
playlist : The created playlist
user_data : Optional user data pointer passed to mafw_source_create_object().
error : Non-NULL if an error occurred.

mafw_playlist_manager_get ()

MafwPlaylistManager* mafw_playlist_manager_get          (void);

Method supporting the singleton.

Returns : the playlist manager of a process. A process has only one object like this, and it must not be released by the caller.

mafw_playlist_manager_create_playlist ()

MafwProxyPlaylist*  mafw_playlist_manager_create_playlist
                                                        (MafwPlaylistManager *self,
                                                         gchar const *name,
                                                         GError **errp);

Creates a playlist with name (an UTF-8 string), makes it available to other applications, and returns the object, to be g_object_unref()ed by the caller. If a playlist with name already existed it is not created again, but the same object is returned. If a new playlist was created, the "playlist_created" signal is emitted. On error errp is set.

self : a MafwPlaylistManager instance.
name : name of the playlist.
errp : a GError to store an error if needed
Returns : a MafwProxyPlaylist which has name or NULL on error. In this case no new playlist is created.

mafw_playlist_manager_destroy_playlist ()

gboolean            mafw_playlist_manager_destroy_playlist
                                                        (MafwPlaylistManager *self,
                                                         MafwProxyPlaylist *playlist,
                                                         GError **errp);

Decreases the refcount of playlist and begins its removal from the list of framework-wide playlists. playlist may remain included in response to inquires about the list of playlists for a while. When the removal is complete a "playlist_destroyed" signal is emitted. If the playlist cannot be removed because it is being used by some renderer a "playlist_destruction_failed" signal is emitted. Attempts to destroy nonexisting playlists result in no operation.

self : the MafwPlaylistManager object
playlist : the playlist to destroy.
errp : a GError to store an error if needed
Returns : the outcome of the request. On failure no playlist is destroyed.

mafw_playlist_manager_dup_playlist ()

MafwProxyPlaylist*  mafw_playlist_manager_dup_playlist  (MafwPlaylistManager *self,
                                                         MafwProxyPlaylist *playlist,
                                                         gchar const *new_name,
                                                         GError **errp);

Duplicates the playist to new_name. If a playlist with new_name already existed it is not created again. If playlist was duplicated, the "playlist_created" signal is emitted. On error errp is set.

self : A MafwPlaylistManager instance.
playlist : playlist to duplicate
new_name : name for the duplicated playlist.
errp : a GError to store an error if needed
Returns : The new duplicated playlist, or NULL if there was any error. Unref it, if you don't need this object.

mafw_playlist_manager_import ()

guint               mafw_playlist_manager_import        (MafwPlaylistManager *self,
                                                         const gchar *playlist,
                                                         const gchar *base_uri,
                                                         MafwPlaylistManagerImportCb cb,
                                                         gpointer user_data,
                                                         GError **error);

Imports external playlists files and shares them in mafw environment.

self : a MafwPlaylistManager instance.
playlist : Uri to playlist, playlist object id or container objectid.
base_uri : If not NULL, used as prefix to resolve relative paths found from playlist.
cb : callback to be called, when it finished with the import, or error occured
user_data : Optional user data pointer passed along with browse_cb.
error : Return location for a GError, or NULL
Returns : The identifier of the import session (which is also passed to cb). If some arguments were invalid, MAFW_PLAYLIST_MANAGER_INVALID_IMPORT_ID is returned.

mafw_playlist_manager_cancel_import ()

gboolean            mafw_playlist_manager_cancel_import (MafwPlaylistManager *self,
                                                         guint import_id,
                                                         GError **error);

Cancels an already running import session.

self : A MafwPlaylistManager instance.
import_id : The import session to cancel.
error : Location for a GError, or NULL
Returns : FALSE if the operation failed (in which case error is also set).

mafw_playlist_manager_get_playlist ()

MafwProxyPlaylist*  mafw_playlist_manager_get_playlist  (MafwPlaylistManager *self,
                                                         guint id,
                                                         GError **errp);

Finds out whether a playlist with id exists in the framework.

self : the MafwPlaylistManager
id : ID of a playlist for which the object to be returned.
errp : a GError to store an error if needed
Returns : the MafwProxyPlaylist representation of the playlist or NULL if it doesn't exist or an error encountered. This case errp is set. Otherwise it is guaranteed that a playlist with a given ID is always represented by the same object.

mafw_playlist_manager_get_playlists ()

GPtrArray*          mafw_playlist_manager_get_playlists (MafwPlaylistManager *self,
                                                         GError **errp);

Gets the playlists stored on the manager

self : the MafwPlaylistManager
errp : a GError to store the error if needed
Returns : NULL on error and sets errp. Otherwise an array of MafwPlaylist objects enumerating all the framework-wide playlists. The array is kept up to date with changes in the list of known playlists. The caller may not modify nor free the returned array. Objects in the list are the same as one would get from mafw_playlist_manager_get_playlist().

mafw_playlist_manager_list_playlists ()

GArray*             mafw_playlist_manager_list_playlists
                                                        (MafwPlaylistManager *self,
                                                         GError **errp);

List the playlist stored in the MiasPlaylistManager

self : a MafwPlaylistManager
errp : a GError to store an error if needed
Returns : NULL on error and sets errp. Otherwise a zero-terminated array of MafwPlaylistManagerItem objects of the shared playlists the framework currently knows about. The list is not kept up to date with respect to changes in the shared playlists and is not ordered by any means. It is the caller's responsibility to free the returned array, for example with mafw_playlist_manager_free_list_of_playlists().

mafw_playlist_manager_free_list_of_playlists ()

void                mafw_playlist_manager_free_list_of_playlists
                                                        (GArray *playlist_list);

Releases playlist_list and all dynamically allocated structures contained therein. If playlist_list is NULL it does nothing.

playlist_list : an array of MafwPlaylistManagerItem to free or NULL.

Signal Details

The "playlist-created" signal

void                user_function                      (MafwPlaylistManager *playlist,
                                                        GObject             *arg1,
                                                        gpointer             user_data)      : Run First / Action

This signal informs the application that playlist has been created. It is guaranteed that the framework will always represent the playlist with playlist (this object).

playlist : the playlist object of MafwPlaylist just created.
user_data : user data set when the signal handler was connected.

The "playlist-destroyed" signal

void                user_function                      (MafwPlaylistManager *playlist,
                                                        GObject             *arg1,
                                                        gpointer             user_data)      : Run First / Action

This signal informs the application that the framework is no longer handling playlist, which, after the emission of the signal is unref()ed. While the application may keep the object by increasing its reference count, all further operations on it will fail. This signal is only sent about playlists the application has a reference to, ie. it was obtained via mafw_playlist_manager_get_playlist() or mafw_playlist_manager_list_playlists().

playlist : the playlist object of MafwPlaylist just destroyed.
user_data : user data set when the signal handler was connected.

The "playlist-destruction-failed" signal

void                user_function                      (MafwPlaylistManager *playlist,
                                                        GObject             *arg1,
                                                        gpointer             user_data)      : Run First / Action

This signal informs the application that the destruction of the playlist is not allowed. This signal is only sent about playlists the application has a reference to, ie. it was obtained via mafw_playlist_manager_get_playlist() or mafw_playlist_manager_list_playlists().

playlist : the playlist object of MafwPlaylist which destruction is not allowed.
user_data : user data set when the signal handler was connected.
Generated by GTK-Doc V1.10