TotemPlPlaylist

## TotemPlPlaylist TotemPlPlaylist — playlist object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <totem-pl-playlist.h>

    typedef             TotemPlPlaylist;
    typedef             TotemPlPlaylistClass;
    TotemPlPlaylist *   totem_pl_playlist_new               (void);
    guint               totem_pl_playlist_size              (TotemPlPlaylist *playlist);
    void                totem_pl_playlist_prepend           (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);
    void                totem_pl_playlist_append            (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);
    void                totem_pl_playlist_insert            (TotemPlPlaylist *playlist,
                                                             gint position,
                                                             TotemPlPlaylistIter *iter);
    gboolean            totem_pl_playlist_iter_first        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);
    gboolean            totem_pl_playlist_iter_next         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);
    gboolean            totem_pl_playlist_iter_prev         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);
    gboolean            totem_pl_playlist_get_value         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             const gchar *key,
                                                             GValue *value);
    void                totem_pl_playlist_get_valist        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             va_list args);
    void                totem_pl_playlist_get               (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             ...);
    gboolean            totem_pl_playlist_set_value         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             const gchar *key,
                                                             GValue *value);
    void                totem_pl_playlist_set_valist        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             va_list args);
    void                totem_pl_playlist_set               (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             ...);

## Object Hierarchy

      GObject
       +----TotemPlPlaylist

## Description

TotemPlPlaylist represents a playlist, provides API to either navigate through the playlist elements, or perform additions or modifications. See also `totem_pl_parser_save()`.

## Details

### TotemPlPlaylist

    typedef struct TotemPlPlaylist TotemPlPlaylist;

All the fields in the TotemPlPlaylist structure are private and should never be accessed directly.

### TotemPlPlaylistClass

    typedef struct TotemPlPlaylistClass TotemPlPlaylistClass;

All the fields in the TotemPlPlaylistClass structure are private and should never be accessed directly.

### totem_pl_playlist_new ()

    TotemPlPlaylist *   totem_pl_playlist_new               (void);

Creates a new TotemPlPlaylist object.

Returns : | The newly created TotemPlPlaylist

### totem_pl_playlist_size ()

    guint               totem_pl_playlist_size              (TotemPlPlaylist *playlist);

Returns the number of elements in `playlist`.

`playlist` : | a TotemPlPlaylist
Returns : | The number of elements

### totem_pl_playlist_prepend ()

    void                totem_pl_playlist_prepend           (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);

Prepends a new empty element to `playlist`, and modifies `iter` so it points to it. To fill in values, you need to call `totem_pl_playlist_set()` or `totem_pl_playlist_set_value()`.

`playlist` : | a TotemPlPlaylist
`iter` : | an unset TotemPlPlaylistIter for returning the location

### totem_pl_playlist_append ()

    void                totem_pl_playlist_append            (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);

Appends a new empty element to `playlist`, and modifies `iter` so it points to it. To fill in values, you need to call `totem_pl_playlist_set()` or `totem_pl_playlist_set_value()`.

`playlist` : | a TotemPlPlaylist
`iter` : | an unset TotemPlPlaylistIter for returning the location

### totem_pl_playlist_insert ()

    void                totem_pl_playlist_insert            (TotemPlPlaylist *playlist,
                                                             gint position,
                                                             TotemPlPlaylistIter *iter);

Inserts a new empty element to `playlist` at `position`, and modifies `iter` so it points to it. To fill in values, you need to call `totem_pl_playlist_set()` or `totem_pl_playlist_set_value()`.

`position` may be minor than 0 to prepend elements, or bigger than the current `playlist` size to append elements.

`playlist` : | a TotemPlPlaylist
`position` : | position in the playlist
`iter` : | an unset TotemPlPlaylistIter for returning the location

### totem_pl_playlist_iter_first ()

    gboolean            totem_pl_playlist_iter_first        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);

Modifies `iter` so it points to the first element in `playlist`.

`playlist` : | a TotemPlPlaylist
`iter` : | an unset TotemPlPlaylistIter for returning the location
Returns : | `TRUE` if there is such first element.

### totem_pl_playlist_iter_next ()

    gboolean            totem_pl_playlist_iter_next         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);

Modifies `iter` so it points to the next element it previously pointed to. This function will return `FALSE` if there was no next element, or `iter` didn't actually point to any element in `playlist`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
Returns : | `TRUE` if there was next element.

### totem_pl_playlist_iter_prev ()

    gboolean            totem_pl_playlist_iter_prev         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter);

Modifies `iter` so it points to the previous element it previously pointed to. This function will return `FALSE` if there was no previous element, or `iter` didn't actually point to any element in `playlist`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
Returns : | `TRUE` if there was previous element.

### totem_pl_playlist_get_value ()

    gboolean            totem_pl_playlist_get_value         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             const gchar *key,
                                                             GValue *value);

Gets the value for `key` (Such as `TOTEM_PL_PARSER_FIELD_URI`) in the playlist item pointed by `iter`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`key` : | data key
`value` : | an empty GValue to set
Returns : | `TRUE` if `iter` contains data for `key`.

### totem_pl_playlist_get_valist ()

    void                totem_pl_playlist_get_valist        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             va_list args);

See `totem_pl_playlist_get()`, this function takes a va_list.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`args` : | a va_list

### totem_pl_playlist_get ()

    void                totem_pl_playlist_get               (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             ...);

Gets the value for one or more keys from the element pointed by `iter`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`...` : | pairs of key/return location for value, terminated by `NULL`

### totem_pl_playlist_set_value ()

    gboolean            totem_pl_playlist_set_value         (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             const gchar *key,
                                                             GValue *value);

Sets the value for `key` in the element pointed by `iter`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`key` : | key to set the value for
`value` : | GValue containing the key value
Returns : | `TRUE` if the value could be stored in `playlist`

### totem_pl_playlist_set_valist ()

    void                totem_pl_playlist_set_valist        (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             va_list args);

See `totem_pl_playlist_set()`, this function takes a va_list.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`args` : | a va_list

### totem_pl_playlist_set ()

    void                totem_pl_playlist_set               (TotemPlPlaylist *playlist,
                                                             TotemPlPlaylistIter *iter,
                                                             ...);

Sets the value for one or several keys in the element pointed by `iter`.

`playlist` : | a TotemPlPlaylist
`iter` : | a TotemPlPlaylistIter pointing to some item in `playlist`
`...` : | key/value string pairs, terminated with `NULL`