rb-playlist-manager

rb-playlist-manager — Playlist management object

Synopsis

                    RBPlaylistManager;
                    RBPlaylistManagerClass;
enum                RBPlaylistManagerError;
RBPlaylistManager*  rb_playlist_manager_new             (RBShell *shell,
                                                         RBSourceList *sourcelist,
                                                         const char *playlists_file);
void                rb_playlist_manager_shutdown        (RBPlaylistManager *mgr);
gboolean            rb_playlist_manager_parse_file      (RBPlaylistManager *mgr,
                                                         const char *uri,
                                                         GError **error);
void                rb_playlist_manager_load_playlists  (RBPlaylistManager *mgr);
gboolean            rb_playlist_manager_save_playlists  (RBPlaylistManager *mgr,
                                                         gboolean force);
RBSource*           rb_playlist_manager_new_playlist    (RBPlaylistManager *mgr,
                                                         const char *suggested_name,
                                                         gboolean automatic);
RBSource*           rb_playlist_manager_new_playlist_from_selection_data
                                                        (RBPlaylistManager *mgr,
                                                         GtkSelectionData *data);
GList*              rb_playlist_manager_get_playlists   (RBPlaylistManager *mgr);
gboolean            rb_playlist_manager_get_playlist_names
                                                        (RBPlaylistManager *mgr,
                                                         gchar ***playlists,
                                                         GError **error);
gboolean            rb_playlist_manager_create_static_playlist
                                                        (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         GError **error);
gboolean            rb_playlist_manager_delete_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         GError **error);
gboolean            rb_playlist_manager_add_to_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         GError **error);
gboolean            rb_playlist_manager_remove_from_playlist
                                                        (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         GError **error);
gboolean            rb_playlist_manager_export_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         gboolean m3u_format,
                                                         GError **error);

Object Hierarchy

  GObject
   +----RBPlaylistManager

Properties

  "playlists-file"           gchar*                : Read / Write
  "shell"                    RBShell*              : Read / Write
  "source"                   RBSource*             : Read / Write
  "sourcelist"               RBSourceList*         : Read / Write / Construct Only

Signals

  "load-finish"                                    : Run Last
  "load-start"                                     : Run Last
  "playlist-added"                                 : Run Last
  "playlist-created"                               : Run Last

Description

The playlist manager loads and saves the on-disk playlist file, provides UI actions and a DBus interface for dealing with playlists, and internal interfaces for creating playlists.

Details

RBPlaylistManager

typedef struct _RBPlaylistManager RBPlaylistManager;


RBPlaylistManagerClass

typedef struct {
	GObjectClass parent_class;

	/* signals */
	void	(*playlist_added) (RBPlaylistManager *manager, RBSource *source);
	void	(*playlist_created) (RBPlaylistManager *manager, RBSource *source);
	void	(*load_start) (RBPlaylistManager *manager);
	void	(*load_finish) (RBPlaylistManager *manager);
} RBPlaylistManagerClass;


enum RBPlaylistManagerError

typedef enum
{
	RB_PLAYLIST_MANAGER_ERROR_PARSE,
	RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_EXISTS,
	RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_NOT_FOUND
} RBPlaylistManagerError;


rb_playlist_manager_new ()

RBPlaylistManager*  rb_playlist_manager_new             (RBShell *shell,
                                                         RBSourceList *sourcelist,
                                                         const char *playlists_file);

Creates the RBPlaylistManager instance

shell :

the RBShell

sourcelist :

the RBSourceList

playlists_file :

the full path to the playlist file to load

Returns :

the RBPlaylistManager

rb_playlist_manager_shutdown ()

void                rb_playlist_manager_shutdown        (RBPlaylistManager *mgr);

Shuts down the playlist manager, making sure any outstanding playlist save operation finishes.

mgr :

the RBPlaylistManager

rb_playlist_manager_parse_file ()

gboolean            rb_playlist_manager_parse_file      (RBPlaylistManager *mgr,
                                                         const char *uri,
                                                         GError **error);

Parses a playlist file, adding entries to the database and to a new static playlist. If the playlist file includes a title, the static playlist created will have the same title.

mgr :

the RBPlaylistManager

uri :

URI of the playlist to load

error :

returns a GError in case of error

Returns :

TRUE on success

rb_playlist_manager_load_playlists ()

void                rb_playlist_manager_load_playlists  (RBPlaylistManager *mgr);

Loads the user's playlists, or if the playlist file does not exists, reads the default playlist file. Should be called only once on startup.

mgr :

the RBPlaylistManager

rb_playlist_manager_save_playlists ()

gboolean            rb_playlist_manager_save_playlists  (RBPlaylistManager *mgr,
                                                         gboolean force);

Saves the user's playlists. If the force flag is TRUE, the playlists will always be saved. Otherwise, the playlists will only be saved if a playlist has been created, modified, or deleted since the last time the playlists were saved, and no save operation is currently taking place.

mgr :

the RBPlaylistManager

force :

if TRUE, save playlists synchronously and unconditionally

Returns :

TRUE if a playlist save operation has been started

rb_playlist_manager_new_playlist ()

RBSource*           rb_playlist_manager_new_playlist    (RBPlaylistManager *mgr,
                                                         const char *suggested_name,
                                                         gboolean automatic);

Creates a new playlist and adds it to the source list.

mgr :

the RBPlaylistManager

suggested_name :

optional name to use for the new playlist

automatic :

if TRUE, create an auto playlist

Returns :

the new playlist object.

rb_playlist_manager_new_playlist_from_selection_data ()

RBSource*           rb_playlist_manager_new_playlist_from_selection_data
                                                        (RBPlaylistManager *mgr,
                                                         GtkSelectionData *data);

Creates a new playlist based on selection data from gtk. Used to implement playlist creation through drag and drop to the source list.

mgr :

the RBPlaylistManager

data :

the GtkSelectionData from which to create a playlist

Returns :

the new playlist.

rb_playlist_manager_get_playlists ()

GList*              rb_playlist_manager_get_playlists   (RBPlaylistManager *mgr);

mgr :

the RBPlaylistManager

Returns :

a GList containing all local playlist source objects.

rb_playlist_manager_get_playlist_names ()

gboolean            rb_playlist_manager_get_playlist_names
                                                        (RBPlaylistManager *mgr,
                                                         gchar ***playlists,
                                                         GError **error);

Allocates and returns an array containing the names of all local playlists. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

playlists :

holds the array of playlist names on reutrn

error :

holds a GError on return on failure

Returns :

TRUE if successful.

rb_playlist_manager_create_static_playlist ()

gboolean            rb_playlist_manager_create_static_playlist
                                                        (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         GError **error);

Creates a new static playlist source with the given name. Will fail if a playlist with that name already exists. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

name :

name of the new playlist

error :

holds a GError on return on failure

Returns :

TRUE if successful.

rb_playlist_manager_delete_playlist ()

gboolean            rb_playlist_manager_delete_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         GError **error);

Deletes the specified playlist. Will fail if no playlist with that name exists. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

name :

name of the playlist to delete

error :

holds a GError on return on failure

Returns :

TRUE if successful.

rb_playlist_manager_add_to_playlist ()

gboolean            rb_playlist_manager_add_to_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         GError **error);

Adds an entry to the specified playlist. Fails if no playlist with that name exists. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

name :

name of the playlist to add to

uri :

URI of the entry to add to the playlist

error :

holds a GError on return on failure

Returns :

TRUE if successful.

rb_playlist_manager_remove_from_playlist ()

gboolean            rb_playlist_manager_remove_from_playlist
                                                        (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         GError **error);

Removes an entry from the specified playlist. Fails if no playlist with that name exists. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

name :

name of the playlist to remove from

uri :

URI of the entry to remove from the playlist

error :

holds a GError on return on failure

Returns :

TRUE if successful.

rb_playlist_manager_export_playlist ()

gboolean            rb_playlist_manager_export_playlist (RBPlaylistManager *mgr,
                                                         const gchar *name,
                                                         const gchar *uri,
                                                         gboolean m3u_format,
                                                         GError **error);

Saves the specified playlist to a file in either M3U or PLS format. This is part of the playlist manager dbus interface.

mgr :

the RBPlaylistManager

name :

name of the playlist to export

uri :

playlist save location

m3u_format :

if TRUE, save in M3U format, otherwise save in PLS format

error :

holds a GError on return on failure

Returns :

TRUE if successful.

Property Details

The "playlists-file" property

  "playlists-file"           gchar*                : Read / Write

playlists file.

Default value: NULL


The "shell" property

  "shell"                    RBShell*              : Read / Write

RBShell object.


The "source" property

  "source"                   RBSource*             : Read / Write

RBSource object.


The "sourcelist" property

  "sourcelist"               RBSourceList*         : Read / Write / Construct Only

RBSourceList.

Signal Details

The "load-finish" signal

void                user_function                      (RBPlaylistManager *manager,
                                                        gpointer           user_data)      : Run Last

Emitted when the playlist manager finishes loading the user's playlist file.

manager :

the RBPlaylistManager

user_data :

user data set when the signal handler was connected.

The "load-start" signal

void                user_function                      (RBPlaylistManager *manager,
                                                        gpointer           user_data)      : Run Last

Emitted when the playlist manager starts loading the user's playlist file.

manager :

the RBPlaylistManager

user_data :

user data set when the signal handler was connected.

The "playlist-added" signal

void                user_function                      (RBPlaylistManager *manager,
                                                        GObject           *source,
                                                        gpointer           user_data)      : Run Last

Emitted when a playlist is added, including when being loaded from the user's playlist file.

manager :

the RBPlaylistManager

source :

the new RBSource

user_data :

user data set when the signal handler was connected.

The "playlist-created" signal

void                user_function                      (RBPlaylistManager *manager,
                                                        GObject           *source,
                                                        gpointer           user_data)      : Run Last

Emitted when a new playlist is created.

manager :

the RBPlaylistManager

source :

the newly created playlist RBSource

user_data :

user data set when the signal handler was connected.