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.
typedef struct sp_playlist_callbacks sp_playlist_callbacks |
Playlist callbacks
Used to get notifications when playlists are updated. If some callbacks should not be of interest, set them to NULL.
typedef struct sp_playlistcontainer_callbacks sp_playlistcontainer_callbacks |
Playlist container callbacks. If some callbacks should not be of interest, set them to NULL.
sp_error 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);
[in] | playlist | Playlist object |
[in] | callbacks | Callbacks, see sp_playlist_callbacks |
[in] | userdata | Userdata to be passed to callbacks |
sp_error sp_playlist_add_ref | ( | sp_playlist * | playlist | ) |
Increase the reference count of a playlist
[in] | playlist | The playlist object |
sp_error sp_playlist_add_tracks | ( | sp_playlist * | playlist, | |
sp_track *const * | tracks, | |||
int | num_tracks, | |||
int | position, | |||
sp_session * | session | |||
) |
Add tracks to a playlist
[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 |
[in] | session | Your session object |
sp_playlist* sp_playlist_create | ( | sp_session * | session, | |
sp_link * | link | |||
) |
Load an already existing playlist without adding it to a playlistcontainer.
[in] | session | Session object |
[in] | link | Link object referring to a playlist |
const char* sp_playlist_get_description | ( | sp_playlist * | playlist | ) |
Get description for a playlist
[in] | playlist | Playlist object |
bool sp_playlist_get_image | ( | sp_playlist * | playlist, | |
byte | image[20] | |||
) |
Get description for a playlist
[in] | playlist | Playlist object |
[out] | image | 20 byte image id |
int sp_playlist_get_offline_download_completed | ( | sp_session * | session, | |
sp_playlist * | playlist | |||
) |
Get download progress for an offline playlist
[in] | session | Session object |
[in] | playlist | Playlist object |
sp_playlist_offline_status sp_playlist_get_offline_status | ( | sp_session * | session, | |
sp_playlist * | playlist | |||
) |
Get offline status for a playlist
[in] | session | Session object |
[in] | playlist | Playlist object |
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.
[in] | playlist | Playlist object |
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
[in] | playlist | Playlist object |
bool sp_playlist_is_in_ram | ( | sp_session * | session, | |
sp_playlist * | playlist | |||
) |
Return whether a playlist is loaded in RAM (as opposed to only stored on disk)
[in] | session | Session object |
[in] | playlist | Playlist object |
The easiest way to detect this case is when sp_playlist_is_in_ram() returns false and sp_link_create_from_playlist() returns NULL
bool sp_playlist_is_loaded | ( | sp_playlist * | playlist | ) |
Get load status for the specified playlist. If it's false, you have to wait until playlist_state_changed happens, and check again if is_loaded has changed
[in] | playlist | Playlist object |
const char* sp_playlist_name | ( | sp_playlist * | playlist | ) |
unsigned int sp_playlist_num_subscribers | ( | sp_playlist * | playlist | ) |
Return number of subscribers for a given playlist
[in] | playlist | Playlist object |
int sp_playlist_num_tracks | ( | sp_playlist * | playlist | ) |
sp_user* sp_playlist_owner | ( | sp_playlist * | playlist | ) |
Return a pointer to the user for the given playlist
[in] | playlist | Playlist object |
sp_error sp_playlist_release | ( | sp_playlist * | playlist | ) |
sp_error 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);
[in] | playlist | Playlist object |
[in] | callbacks | Callbacks, see sp_playlist_callbacks |
[in] | userdata | Userdata to be passed to callbacks |
sp_error sp_playlist_remove_tracks | ( | sp_playlist * | playlist, | |
const int * | tracks, | |||
int | num_tracks | |||
) |
Remove tracks from a playlist
[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 |
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.
[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
[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 |
sp_error sp_playlist_set_autolink_tracks | ( | sp_playlist * | playlist, | |
bool | link | |||
) |
Set autolinking state for a playlist.
If a playlist is autolinked, unplayable tracks will be made playable by linking them to other Spotify tracks, where possible.
[in] | playlist | Playlist object |
[in] | link | True or false |
sp_error sp_playlist_set_collaborative | ( | sp_playlist * | playlist, | |
bool | collaborative | |||
) |
Set collaborative status for a playlist.
A playlist in collaborative state can be modified by all users, not only the user owning the list
[in] | playlist | Playlist object |
[in] | collaborative | True or false |
sp_error sp_playlist_set_in_ram | ( | sp_session * | session, | |
sp_playlist * | playlist, | |||
bool | in_ram | |||
) |
Return whether a playlist is loaded in RAM (as opposed to only stored on disk)
[in] | session | Session object |
[in] | playlist | Playlist object |
[in] | in_ram | Controls whether or not to keep the list in RAM |
sp_error sp_playlist_set_offline_mode | ( | sp_session * | session, | |
sp_playlist * | playlist, | |||
bool | offline | |||
) |
Mark a playlist to be synchronized for offline playback. The playlist must be in the users playlistcontainer
[in] | session | Session object |
[in] | playlist | Playlist object |
[in] | offline | True iff playlist should be offline, false otherwise |
sp_subscribers* sp_playlist_subscribers | ( | sp_playlist * | playlist | ) |
Return subscribers for a playlist
[in] | playlist | Playlist object |
sp_error sp_playlist_subscribers_free | ( | sp_subscribers * | subscribers | ) |
Free object returned from sp_playlist_subscribers()
[in] | subscribers | Subscribers object |
sp_track* sp_playlist_track | ( | sp_playlist * | playlist, | |
int | index | |||
) |
Return the track at the given index in a playlist
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
int sp_playlist_track_create_time | ( | sp_playlist * | playlist, | |
int | index | |||
) |
Return when the given index was added to the playlist
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
sp_user* sp_playlist_track_creator | ( | sp_playlist * | playlist, | |
int | index | |||
) |
Return user that added the given index in the playlist
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
const char* sp_playlist_track_message | ( | sp_playlist * | playlist, | |
int | index | |||
) |
Return a message attached to a playlist item. Typically used on inbox.
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
bool sp_playlist_track_seen | ( | sp_playlist * | playlist, | |
int | index | |||
) |
Return if a playlist entry is marked as seen or not
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
sp_error sp_playlist_track_set_seen | ( | sp_playlist * | playlist, | |
int | index, | |||
bool | seen | |||
) |
Set seen status of a playlist entry
[in] | playlist | Playlist object |
[in] | index | Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1] |
[in] | seen | Seen status to be set |
sp_error sp_playlist_update_subscribers | ( | sp_session * | session, | |
sp_playlist * | playlist | |||
) |
Ask library to update the subscription count for a playlist
When the subscription info has been fetched from the Spotify backend the playlist subscribers_changed() callback will be invoked. In that callback use sp_playlist_num_subscribers() and/or sp_playlist_subscribers() to get information about the subscribers. You can call those two functions anytime you want but the information might not be up to date in such cases
[in] | session | Session object |
[in] | playlist | Playlist object |
sp_error sp_playlistcontainer_add_callbacks | ( | sp_playlistcontainer * | pc, | |
sp_playlistcontainer_callbacks * | callbacks, | |||
void * | userdata | |||
) |
Register interest in changes to a playlist container
[in] | pc | Playlist container |
[in] | callbacks | Callbacks, see sp_playlistcontainer_callbacks |
[in] | userdata | Opaque value passed to callbacks. |
sp_error sp_playlistcontainer_add_folder | ( | sp_playlistcontainer * | pc, | |
int | index, | |||
const char * | name | |||
) |
Add a playlist folder
[in] | pc | Playlist container |
[in] | index | Position of SP_PLAYLIST_TYPE_START_FOLDER entry |
[in] | name | Name of group |
To remove a playlist folder both of these must be deleted or the list will be left in an inconsistant state.
There is no way to rename a playlist folder. Instead you need to remove the folder and recreate it again.
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.
[in] | pc | Playlist container |
[in] | name | Name of new playlist |
sp_playlist* sp_playlistcontainer_add_playlist | ( | sp_playlistcontainer * | pc, | |
sp_link * | link | |||
) |
Add an existing playlist at the end of the given playlist container
[in] | pc | Playlist container |
[in] | link | Link object pointing to a playlist |
sp_error sp_playlistcontainer_add_ref | ( | sp_playlistcontainer * | pc | ) |
Increase reference count on playlistconatiner object
[in] | pc | Playlist container. |
int sp_playlistcontainer_clear_unseen_tracks | ( | sp_playlistcontainer * | pc, | |
sp_playlist * | playlist | |||
) |
Clears a playlist from unseen tracks, so that next call to sp_playlistcontainer_get_unseen_tracks() will return 0 until a new track is added to the playslist
.
[in] | pc | Playlist container. |
[in] | playlist | Playlist object. |
int sp_playlistcontainer_get_unseen_tracks | ( | sp_playlistcontainer * | pc, | |
sp_playlist * | playlist, | |||
sp_track ** | tracks, | |||
int | num_tracks | |||
) |
Get the number of new tracks in a playlist since the corresponding function sp_playlistcontainer_clear_unseen_tracks() was called. The function always returns the number of new tracks, and fills the tracks
array with the new tracks, but not more than specified in num_tracks
. The function will return a negative value on failure.
[in] | pc | Playlist container. |
[in] | playlist | Playlist object. |
[out] | tracks | Array of pointer to new tracks (maybe NULL) |
[in] | num_tracks | Size of tracks array |
bool sp_playlistcontainer_is_loaded | ( | sp_playlistcontainer * | pc | ) |
Return true if the playlistcontainer is fully loaded
[in] | pc | Playlist container |
sp_error sp_playlistcontainer_move_playlist | ( | sp_playlistcontainer * | pc, | |
int | index, | |||
int | new_position, | |||
bool | dry_run | |||
) |
Move a playlist in the playlist container
[in] | pc | Playlist container |
[in] | index | Index of playlist to be moved |
[in] | new_position | New position for the playlist |
[in] | dry_run | Do not execute the move, only check if it possible |
int sp_playlistcontainer_num_playlists | ( | sp_playlistcontainer * | pc | ) |
Return the number of playlists in the given playlist container
[in] | pc | Playlist container |
sp_user* sp_playlistcontainer_owner | ( | sp_playlistcontainer * | pc | ) |
Return a pointer to the user object of the owner.
[in] | pc | Playlist container. |
sp_playlist* sp_playlistcontainer_playlist | ( | sp_playlistcontainer * | pc, | |
int | index | |||
) |
Return a pointer to the playlist at a specific index
[in] | pc | Playlist container |
[in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
sp_uint64 sp_playlistcontainer_playlist_folder_id | ( | sp_playlistcontainer * | pc, | |
int | index | |||
) |
Return the folder id at index
[in] | pc | Playlist container |
[in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
sp_error sp_playlistcontainer_playlist_folder_name | ( | sp_playlistcontainer * | pc, | |
int | index, | |||
char * | buffer, | |||
int | buffer_size | |||
) |
Return the folder name at index
[in] | pc | Playlist container |
[in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]. Index should point at a start-folder entry, otherwise the empty string is written to buffer. |
[in] | buffer | Pointer to char[] where to store folder name |
[in] | buffer_size | Size of array |
sp_playlist_type sp_playlistcontainer_playlist_type | ( | sp_playlistcontainer * | pc, | |
int | index | |||
) |
Return the type of the playlist at a index
[in] | pc | Playlist container |
[in] | index | Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1] |
sp_error sp_playlistcontainer_release | ( | sp_playlistcontainer * | pc | ) |
Release reference count on playlistconatiner object
[in] | pc | Playlist container. |
sp_error sp_playlistcontainer_remove_callbacks | ( | sp_playlistcontainer * | pc, | |
sp_playlistcontainer_callbacks * | callbacks, | |||
void * | userdata | |||
) |
Unregister interest in changes to a playlist container
[in] | pc | Playlist container |
[in] | callbacks | Callbacks, see sp_playlistcontainer_callbacks |
[in] | userdata | Opaque value passed to callbacks. |
sp_error sp_playlistcontainer_remove_playlist | ( | sp_playlistcontainer * | pc, | |
int | index | |||
) |
Remove playlist at index from the given playlist container
[in] | pc | Playlist container |
[in] | index | Index of playlist to be removed |