Playlist subsystem


Data Structures

struct  sp_playlist_callbacks
struct  sp_playlistcontainer_callbacks

Functions

bool sp_playlist_is_loaded (sp_playlist *playlist)
void sp_playlist_add_callbacks (sp_playlist *playlist, sp_playlist_callbacks *callbacks, void *userdata)
void sp_playlist_remove_callbacks (sp_playlist *playlist, sp_playlist_callbacks *callbacks, void *userdata)
int sp_playlist_num_tracks (sp_playlist *playlist)
sp_tracksp_playlist_track (sp_playlist *playlist, int index)
const char * sp_playlist_name (sp_playlist *playlist)
sp_error sp_playlist_rename (sp_playlist *playlist, const char *new_name)
sp_usersp_playlist_owner (sp_playlist *playlist)
bool sp_playlist_is_collaborative (sp_playlist *playlist)
void sp_playlist_set_collaborative (sp_playlist *playlist, bool collaborative)
bool sp_playlist_has_pending_changes (sp_playlist *playlist)
sp_error sp_playlist_add_tracks (sp_playlist *playlist, const sp_track **tracks, int num_tracks, int position)
sp_error sp_playlist_remove_tracks (sp_playlist *playlist, const int *tracks, int num_tracks)
sp_error sp_playlist_reorder_tracks (sp_playlist *playlist, const int *tracks, int num_tracks, int new_position)
void sp_playlistcontainer_add_callbacks (sp_playlistcontainer *pc, sp_playlistcontainer_callbacks *callbacks, void *userdata)
void sp_playlistcontainer_remove_callbacks (sp_playlistcontainer *pc, sp_playlistcontainer_callbacks *callbacks, void *userdata)
int sp_playlistcontainer_num_playlists (sp_playlistcontainer *pc)
sp_playlistsp_playlistcontainer_playlist (sp_playlistcontainer *pc, int index)
sp_playlistsp_playlistcontainer_add_new_playlist (sp_playlistcontainer *pc, const char *name)
sp_playlistsp_playlistcontainer_add_playlist (sp_playlistcontainer *pc, sp_link *link)
sp_error sp_playlistcontainer_remove_playlist (sp_playlistcontainer *pc, int index)
sp_error sp_playlistcontainer_move_playlist (sp_playlistcontainer *pc, int index, int new_position)

Detailed Description

The playlist subsystem handles playlists and playlist containers (list of playlists).

The playlist container functions are always valid, but your playlists are not guaranteed to be loaded until the sp_session_callbacks::logged_in callback has been issued.


Function Documentation

void sp_playlist_add_callbacks ( sp_playlist playlist,
sp_playlist_callbacks callbacks,
void *  userdata 
)

Register interest in the given playlist

Here is a snippet from jukebox.c:

    sp_playlist_add_callbacks(pl, &pl_callbacks, NULL);

Parameters:
[in] playlist Playlist object
[in] callbacks Callbacks, see sp_playlist_callbacks
[in] userdata Userdata to be passed to callbacks
See also:
sp_playlist_remove_callbacks
Examples:
jukebox.c.

sp_error sp_playlist_add_tracks ( sp_playlist playlist,
const sp_track **  tracks,
int  num_tracks,
int  position 
)

Add tracks to a playlist

Parameters:
[in] playlist Playlist object
[in] tracks Array of pointer to tracks.
[in] num_tracks Length of tracks array
[in] position Start position in playlist where to insert the tracks

bool sp_playlist_has_pending_changes ( sp_playlist playlist  ) 

Check if a playlist has pending changes

Pending changes are local changes that have not yet been acknowledged by the server.

Parameters:
[in] playlist Playlist object
Returns:
A flag representing if there are pending changes or not

bool sp_playlist_is_collaborative ( sp_playlist playlist  ) 

Return collaborative status for a playlist.

A playlist in collaborative state can be modifed by all users, not only the user owning the list

Parameters:
[in] playlist Playlist object
Returns:
true if playlist is collaborative, otherwise false

bool sp_playlist_is_loaded ( sp_playlist playlist  ) 

Get load status for the specified playlist

Parameters:
[in] playlist Playlist object
Returns:
True if playlist is loaded, otherwise false

const char* sp_playlist_name ( sp_playlist playlist  ) 

Return name of given playlist

Parameters:
[in] playlist Playlist object
Returns:
The name of the given playlist
Examples:
jukebox.c.

int sp_playlist_num_tracks ( sp_playlist playlist  ) 

Return number of tracks in the given playlist

Parameters:
[in] playlist Playlist object
Returns:
The number of tracks in the playlist
Examples:
jukebox.c.

sp_user* sp_playlist_owner ( sp_playlist playlist  ) 

Return a pointer to the user for the given playlist

Parameters:
[in] playlist Playlist object
Returns:
User object

void sp_playlist_remove_callbacks ( sp_playlist playlist,
sp_playlist_callbacks callbacks,
void *  userdata 
)

Unregister interest in the given playlist

The combination of (callbacks, userdata) is used to find the entry to be removed

Here is a snippet from jukebox.c:

    sp_playlist_remove_callbacks(pl, &pl_callbacks, NULL);

Parameters:
[in] playlist Playlist object
[in] callbacks Callbacks, see sp_playlist_callbacks
[in] userdata Userdata to be passed to callbacks
See also:
sp_playlist_add_callbacks
Examples:
jukebox.c.

sp_error sp_playlist_remove_tracks ( sp_playlist playlist,
const int *  tracks,
int  num_tracks 
)

Remove tracks from a playlist

Parameters:
[in] playlist Playlist object
[in] tracks Array of pointer to track indices. A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata, whereas [0, 1, 1] is invalid.
[in] num_tracks Length of tracks array
Examples:
jukebox.c.

sp_error sp_playlist_rename ( sp_playlist playlist,
const char *  new_name 
)

Rename the given playlist The name must not consist of only spaces and it must be shorter than 256 characters.

Parameters:
[in] playlist Playlist object
[in] new_name New name for playlist

sp_error sp_playlist_reorder_tracks ( sp_playlist playlist,
const int *  tracks,
int  num_tracks,
int  new_position 
)

Move tracks in playlist

Parameters:
[in] playlist Playlist object
[in] tracks Array of pointer to track indices to be moved. A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata, whereas [0, 1, 1] is invalid.
[in] num_tracks Length of tracks array
[in] new_position New position for tracks

void sp_playlist_set_collaborative ( sp_playlist playlist,
bool  collaborative 
)

Set collaborative status for a playlist.

A playlist in collaborative state can be modifed by all users, not only the user owning the list

Parameters:
[in] playlist Playlist object
[in] collaborative True or false

sp_track* sp_playlist_track ( sp_playlist playlist,
int  index 
)

Return the track at the given index in the given playlist

Parameters:
[in] playlist Playlist object
[in] index Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
Returns:
The track at the given index
Examples:
jukebox.c.

void sp_playlistcontainer_add_callbacks ( sp_playlistcontainer pc,
sp_playlistcontainer_callbacks callbacks,
void *  userdata 
)

Register interest in changes to a playlist container

Parameters:
[in] pc Playlist container
[in] callbacks Callbacks, see sp_playlistcontainer_callbacks
[in] userdata Opaque value passed to callbacks.
See also:
sp_session_playlistcontainer()

sp_playlistcontainer_remove_callbacks

Examples:
jukebox.c.

sp_playlist* sp_playlistcontainer_add_new_playlist ( sp_playlistcontainer pc,
const char *  name 
)

Add an empty playlist at the end of the playlist container. The name must not consist of only spaces and it must be shorter than 256 characters.

Parameters:
[in] pc Playlist container
[in] name Name of new playlist
Returns:
Pointer to the new playlist. Can be NULL if the operation fails.

sp_playlist* sp_playlistcontainer_add_playlist ( sp_playlistcontainer pc,
sp_link link 
)

Add an existing playlist at the end of the given playlist container

Parameters:
[in] pc Playlist container
[in] link Link object pointing to a playlist
Returns:
Pointer to the new playlist. Will be NULL if the playlist already exists.

sp_error sp_playlistcontainer_move_playlist ( sp_playlistcontainer pc,
int  index,
int  new_position 
)

Move a playlist in the playlist container

Parameters:
[in] pc Playlist container
[in] index Index of playlist to be moved
[in] new_position New position for the playlist

int sp_playlistcontainer_num_playlists ( sp_playlistcontainer pc  ) 

Return the number of playlists in the given playlist container

Parameters:
[in] pc Playlist container
Returns:
Number of playlists, -1 if undefined
See also:
sp_session_playlistcontainer()
Examples:
jukebox.c.

sp_playlist* sp_playlistcontainer_playlist ( sp_playlistcontainer pc,
int  index 
)

Return a pointer to the playlist at a specific index

Parameters:
[in] pc Playlist container
[in] index Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]
Returns:
Number of playlists.
See also:
sp_session_playlistcontainer()
Examples:
jukebox.c.

void sp_playlistcontainer_remove_callbacks ( sp_playlistcontainer pc,
sp_playlistcontainer_callbacks callbacks,
void *  userdata 
)

Unregister interest in changes to a playlist container

Parameters:
[in] pc Playlist container
[in] callbacks Callbacks, see sp_playlistcontainer_callbacks
[in] userdata Opaque value passed to callbacks.
See also:
sp_session_playlistcontainer()

sp_playlistcontainer_add_callbacks

sp_error sp_playlistcontainer_remove_playlist ( sp_playlistcontainer pc,
int  index 
)

Remove playlist at index from the given playlist container

Parameters:
[in] pc Playlist container
[in] index Index of playlist to be removed


Generated on Tue Apr 7 15:21:55 2009.
Copyright © 2006–2009 Spotify Ltd