RBPlaylistManager: Rhythmbox Development Reference Manual

## RBPlaylistManager RBPlaylistManager — Playlist management object |

## Functions

RBPlaylistManager * | rb_playlist_manager_new ()
void | rb_playlist_manager_shutdown ()
gboolean | rb_playlist_manager_parse_file ()
void | rb_playlist_manager_load_playlists ()
gboolean | rb_playlist_manager_save_playlists ()
RBSource * | rb_playlist_manager_new_playlist ()
RBSource * | rb_playlist_manager_new_playlist_from_selection_data ()
GList * | rb_playlist_manager_get_playlists ()
gboolean | rb_playlist_manager_get_playlist_names ()
gboolean | rb_playlist_manager_create_static_playlist ()
gboolean | rb_playlist_manager_delete_playlist ()
gboolean | rb_playlist_manager_add_to_playlist ()
gboolean | rb_playlist_manager_remove_from_playlist ()
gboolean | rb_playlist_manager_export_playlist ()

## Properties

gchar * | playlists-file | Read / Write
RBShell * | shell | Read / Write
RBSource * | source | Read / Write

## Signals

void | load-finish | Run Last
void | load-start | Run Last
void | playlist-added | Run Last
void | playlist-created | Run Last

## Types and Values

struct | RBPlaylistManager
struct | RBPlaylistManagerClass
enum | RBPlaylistManagerError

## Object Hierarchy

        GObject
        ╰── RBPlaylistManager

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

## Functions

### rb_playlist_manager_new ()

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

Creates the RBPlaylistManager instance

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

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

#### Members

RB_PLAYLIST_MANAGER_ERROR_PARSE |  |
RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_EXISTS |  |
RB_PLAYLIST_MANAGER_ERROR_PLAYLIST_NOT_FOUND |  |

## Property Details

### The `“playlists-file”` property

      “playlists-file”           gchar *

playlists file.

Flags: Read / Write

Default value: NULL

### The `“shell”` property

      “shell”                    RBShell *

RBShell object.

Flags: Read / Write

### The `“source”` property

      “source”                   RBSource *

RBSource object.

Flags: Read / Write

## Signal Details

### The `“load-finish”` signal

    void
    user_function (RBPlaylistManager *manager,
                   gpointer           user_data)

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

#### Parameters

manager | the RBPlaylistManager |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“load-start”` signal

    void
    user_function (RBPlaylistManager *manager,
                   gpointer           user_data)

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

#### Parameters

manager | the RBPlaylistManager |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playlist-added”` signal

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

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

#### Parameters

manager | the RBPlaylistManager |
source | the new RBSource |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“playlist-created”` signal

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

Emitted when a new playlist is created.

#### Parameters

manager | the RBPlaylistManager |
source | the newly created playlist RBSource |
user_data | user data set when the signal handler was connected. |

Flags: Run Last