Defines | Typedefs | Enumerations | Functions

Toplist handling

Defines

#define SP_TOPLIST_REGION(a, b)   ((a) << 8 | (b))

Typedefs

typedef void toplistbrowse_complete_cb (sp_toplistbrowse *result, void *userdata)

Enumerations

enum  sp_toplisttype {
  SP_TOPLIST_TYPE_ARTISTS = 0,
  SP_TOPLIST_TYPE_ALBUMS = 1,
  SP_TOPLIST_TYPE_TRACKS = 2
}
enum  sp_toplistregion {
  SP_TOPLIST_REGION_EVERYWHERE = 0,
  SP_TOPLIST_REGION_USER = 1
}

Functions

sp_toplistbrowsesp_toplistbrowse_create (sp_session *session, sp_toplisttype type, sp_toplistregion region, const char *username, toplistbrowse_complete_cb *callback, void *userdata)
bool sp_toplistbrowse_is_loaded (sp_toplistbrowse *tlb)
sp_error sp_toplistbrowse_error (sp_toplistbrowse *tlb)
sp_error sp_toplistbrowse_add_ref (sp_toplistbrowse *tlb)
sp_error sp_toplistbrowse_release (sp_toplistbrowse *tlb)
int sp_toplistbrowse_num_artists (sp_toplistbrowse *tlb)
sp_artistsp_toplistbrowse_artist (sp_toplistbrowse *tlb, int index)
int sp_toplistbrowse_num_albums (sp_toplistbrowse *tlb)
sp_albumsp_toplistbrowse_album (sp_toplistbrowse *tlb, int index)
int sp_toplistbrowse_num_tracks (sp_toplistbrowse *tlb)
sp_tracksp_toplistbrowse_track (sp_toplistbrowse *tlb, int index)
int sp_toplistbrowse_backend_request_duration (sp_toplistbrowse *tlb)

Define Documentation

#define SP_TOPLIST_REGION (   a,
  b 
)    ((a) << 8 | (b))

Convenience macro to create a toplist region. Toplist regions are ISO 3166-1 country codes (in uppercase) encoded in an integer. There are also some reserved codes used to denote non-country regions. See sp_toplistregion

Example: SP_TOPLIST_REGION('S', 'E') for Sweden

Examples:
toplist.c.

Typedef Documentation

typedef void toplistbrowse_complete_cb(sp_toplistbrowse *result, void *userdata)

The type of a callback used in sp_toplistbrowse_create()

When the callback is called, the metadata of all tracks belonging to it will have been loaded, so sp_track_is_loaded() will return non-zero. The same goes for the similar toplist data.

Parameters:
[in] result The same pointer returned by sp_toplistbrowse_create()
[in] userdata The opaque pointer given to sp_toplistbrowse_create()

Enumeration Type Documentation

Special toplist regions

Enumerator:
SP_TOPLIST_REGION_EVERYWHERE 

Global toplist.

SP_TOPLIST_REGION_USER 

Toplist for a given user.

Toplist types

Enumerator:
SP_TOPLIST_TYPE_ARTISTS 

Top artists.

SP_TOPLIST_TYPE_ALBUMS 

Top albums.

SP_TOPLIST_TYPE_TRACKS 

Top tracks.


Function Documentation

sp_error sp_toplistbrowse_add_ref ( sp_toplistbrowse tlb  ) 

Increase the reference count of an toplist browse result

Parameters:
[in] tlb The toplist browse result object
Returns:
One of the following errors, from sp_error SP_ERROR_OK
sp_album* sp_toplistbrowse_album ( sp_toplistbrowse tlb,
int  index 
)

Return the album at the given index in the given toplist browse object

Parameters:
[in] tlb Toplist object
[in] index Index of the wanted album. Should be in the interval [0, sp_toplistbrowse_num_albums() - 1]
Returns:
The album at the given index in the given toplist browse object
Examples:
toplist.c.
sp_artist* sp_toplistbrowse_artist ( sp_toplistbrowse tlb,
int  index 
)

Return the artist at the given index in the given toplist browse object

Parameters:
[in] tlb Toplist object
[in] index Index of the wanted artist. Should be in the interval [0, sp_toplistbrowse_num_artists() - 1]
Returns:
The artist at the given index in the given toplist browse object
Examples:
toplist.c.
int sp_toplistbrowse_backend_request_duration ( sp_toplistbrowse tlb  ) 

Return the time (in ms) that was spent waiting for the Spotify backend to serve the request

Parameters:
[in] tlb Toplist object
Returns:
-1 if the request was served from the local cache If the result is not yet loaded the return value is undefined
sp_toplistbrowse* sp_toplistbrowse_create ( sp_session session,
sp_toplisttype  type,
sp_toplistregion  region,
const char *  username,
toplistbrowse_complete_cb callback,
void *  userdata 
)

Initiate a request for browsing an toplist

The user is responsible for freeing the returned toplist browse using sp_toplistbrowse_release(). This can be done in the callback.

Parameters:
[in] session Session object
[in] type Type of toplist to be browsed. see the sp_toplisttype enum for possible values
[in] region Region. see sp_toplistregion enum. Country specific regions are coded as two chars in an integer. Sweden would correspond to 'S' << 8 | 'E'
[in] username If region is SP_TOPLIST_REGION_USER this specifies which user to get toplists for. NULL means the logged in user.
[in] callback Callback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
[in] userdata Userdata passed to callback.
Returns:
Toplist browse object
See also:
toplistbrowse_complete_cb
Examples:
toplist.c.
sp_error sp_toplistbrowse_error ( sp_toplistbrowse tlb  ) 

Check if browsing returned an error code.

Parameters:
[in] tlb Toplist browse object
Returns:
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_IS_LOADING SP_ERROR_OTHER_PERMANENT SP_ERROR_OTHER_TRANSIENT
bool sp_toplistbrowse_is_loaded ( sp_toplistbrowse tlb  ) 

Check if an toplist browse request is completed

Parameters:
[in] tlb Toplist browse object
Returns:
True if browsing is completed, false if not
int sp_toplistbrowse_num_albums ( sp_toplistbrowse tlb  ) 

Given an toplist browse object, return number of albums

Parameters:
[in] tlb Toplist browse object
Returns:
Number of albums on toplist
Examples:
toplist.c.
int sp_toplistbrowse_num_artists ( sp_toplistbrowse tlb  ) 

Given an toplist browse object, return number of artists

Parameters:
[in] tlb Toplist browse object
Returns:
Number of artists on toplist
Examples:
toplist.c.
int sp_toplistbrowse_num_tracks ( sp_toplistbrowse tlb  ) 

Given an toplist browse object, return number of tracks

Parameters:
[in] tlb Toplist browse object
Returns:
Number of tracks on toplist
Examples:
toplist.c.
sp_error sp_toplistbrowse_release ( sp_toplistbrowse tlb  ) 

Decrease the reference count of an toplist browse result

Parameters:
[in] tlb The toplist browse result object
Returns:
One of the following errors, from sp_error SP_ERROR_OK
Examples:
toplist.c.
sp_track* sp_toplistbrowse_track ( sp_toplistbrowse tlb,
int  index 
)

Return the track at the given index in the given toplist browse object

Parameters:
[in] tlb Toplist object
[in] index Index of the wanted track. Should be in the interval [0, sp_toplistbrowse_num_tracks() - 1]
Returns:
The track at the given index in the given toplist browse object
Examples:
toplist.c.

Generated on Wed Jun 13 2012 14:22:40.
Copyright © 2006–2012 Spotify Ltd