RBPlaylistManager

## RBPlaylistManager RBPlaylistManager — Playlist management object |

## Synopsis

    struct              RBPlaylistManager;
    struct              RBPlaylistManagerClass;
    enum                RBPlaylistManagerError;
    RBPlaylistManager * rb_playlist_manager_new             (RBShell *shell,
                                                             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

## 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

### struct RBPlaylistManager

    struct RBPlaylistManager;

### struct RBPlaylistManagerClass

    struct RBPlaylistManagerClass {
    	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);
    };

### 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_ERROR_PARSE` |
`RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_EXISTS` |
`RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_NOT_FOUND` |

### rb_playlist_manager_new ()

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

Creates the RBPlaylistManager instance

`shell` : | the RBShell
`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. [transfer none]

### 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. [transfer none]

### rb_playlist_manager_get_playlists ()

    GList *             rb_playlist_manager_get_playlists   (RBPlaylistManager *mgr);

Returns a GList containing all local playlist source objects.

`mgr` : | the RBPlaylistManager
Returns : | list of playlists. [element-type RB.Source][transfer container]

### 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. [out callee-allocates][transfer full]
`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.

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