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_track * sp_playlist_track (sp_playlist *playlist, int index)
int sp_playlist_track_create_time (sp_playlist *playlist, int index)
sp_user * sp_playlist_track_creator (sp_playlist *playlist, int index)
bool sp_playlist_track_seen (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_user * sp_playlist_owner (sp_playlist *playlist)
bool sp_playlist_is_collaborative (sp_playlist *playlist)
void sp_playlist_set_collaborative (sp_playlist *playlist, bool collaborative)
void sp_playlist_set_autolink_tracks (sp_playlist *playlist, bool link)
const char * sp_playlist_get_description (sp_playlist *playlist)
bool sp_playlist_get_image (sp_playlist *playlist, byte image[20])
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_session *session)
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)
sp_playlist * sp_playlist_create (sp_session *session, sp_link *link)
void sp_playlist_add_ref (sp_playlist *playlist)
void sp_playlist_release (sp_playlist *playlist)
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_playlist * sp_playlistcontainer_playlist (sp_playlistcontainer *pc, int index)
sp_playlist_type sp_playlistcontainer_playlist_type (sp_playlistcontainer *pc, int index)
const char * sp_playlistcontainer_playlist_folder_name (sp_playlistcontainer *pc, int index)
sp_uint64 sp_playlistcontainer_playlist_folder_id (sp_playlistcontainer *pc, int index)
sp_playlist * sp_playlistcontainer_add_new_playlist (sp_playlistcontainer *pc, const char *name)
sp_playlist * sp_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)
sp_user * sp_playlistcontainer_owner (sp_playlistcontainer *pc)

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: 



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 











      

        

          void sp_playlist_add_ref           
          (
          sp_playlist * 
           playlist          
           ) 
          
        

      








Increase the reference count of a playlist


Parameters:

  

    
[in] playlist The playlist object 

  













      

        

          sp_error sp_playlist_add_tracks           
          (
          sp_playlist * 
           playlist, 
        

        

          
          
          const sp_track ** 
           tracks, 
        

        

          
          
          int 
           num_tracks, 
        

        

          
          
          int 
           position, 
        

        

          
          
          sp_session * 
           session 
        

        

          
          )
          
        

      








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 

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


Parameters:

  

    
[in] session Session object 

    
[in] link Link object referring to a playlist

  




Returns:
A playlist. The reference is owned by the caller and should be released with sp_playlist_release() 











      

        

          const char* sp_playlist_get_description           
          (
          sp_playlist * 
           playlist          
           ) 
          
        

      








Get description for a playlist


Parameters:

  

    
[in] playlist Playlist object

  




Returns:
Playlist description or NULL if unset 











      

        

          bool sp_playlist_get_image           
          (
          sp_playlist * 
           playlist, 
        

        

          
          
          byte 
           image[20] 
        

        

          
          )
          
        

      








Get description for a playlist


Parameters:

  

    
[in] playlist Playlist object 

    
[out] image 20 byte image id

  




Returns:
TRUE if playlist has an image, FALSE if not 











      

        

          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. If it's false, you have to wait until playlist_state_changed happens, and check again if is_loaded has changed


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 











      

        

          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 











      

        

          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_release           
          (
          sp_playlist * 
           playlist          
           ) 
          
        

      








Decrease the reference count of a playlist


Parameters:

  

    
[in] playlist The playlist 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:  


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 











      

        

          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 

  













      

        

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


Parameters:

  

    
[in] playlist Playlist object 

    
[in] link True or false 

  













      

        

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











      

        

          int sp_playlist_track_create_time           
          (
          sp_playlist * 
           playlist, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return when the given index was added to the playlist


Parameters:

  

    
[in] playlist Playlist object 

    
[in] index Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]

  




Returns:
Time, Seconds since unix epoch. 











      

        

          sp_user* sp_playlist_track_creator           
          (
          sp_playlist * 
           playlist, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return user that added the given index in the playlist


Parameters:

  

    
[in] playlist Playlist object 

    
[in] index Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]

  




Returns:
User object 











      

        

          bool sp_playlist_track_seen           
          (
          sp_playlist * 
           playlist, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return if a playlist entry is marked as seen or not


Parameters:

  

    
[in] playlist Playlist object 

    
[in] index Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]

  




Returns:
Seen state 











      

        

          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 











      

        

          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() 











      

        

          sp_user* sp_playlistcontainer_owner           
          (
          sp_playlistcontainer * 
           pc          
           ) 
          
        

      








Return a pointer to the user object of the owner.


Parameters:

  

    
[in] pc Playlist container. 

  




Returns:
The user object or NULL if unknown or none. 











      

        

          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() 











      

        

          sp_uint64 sp_playlistcontainer_playlist_folder_id           
          (
          sp_playlistcontainer * 
           pc, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return the folder id at index 


Parameters:

  

    
[in] pc Playlist container 

    
[in] index Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]

  




Returns:
The group ID


See also:
sp_session_playlistcontainer() 











      

        

          const char* sp_playlistcontainer_playlist_folder_name           
          (
          sp_playlistcontainer * 
           pc, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return the folder name at index 


Parameters:

  

    
[in] pc Playlist container 

    
[in] index Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]

  




Returns:
The folder name


See also:
sp_session_playlistcontainer() 











      

        

          sp_playlist_type sp_playlistcontainer_playlist_type           
          (
          sp_playlistcontainer * 
           pc, 
        

        

          
          
          int 
           index 
        

        

          
          )
          
        

      








Return the type of the playlist at a index 


Parameters:

  

    
[in] pc Playlist container 

    
[in] index Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]

  




Returns:
Type of the playlist, 


See also:
sp_playlist_type

sp_session_playlistcontainer() 











      

        

          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 Wed Nov 3 12:46:14 2010.

Copyright © 2006–2009 Spotify Ltd