libspotify
Macros | Typedefs | Enumerations | Functions
Toplist handling

Macros

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

Detailed Description

Macro Definition Documentation

#define SP_TOPLIST_REGION (   a,
 
)    ((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]resultThe same pointer returned by sp_toplistbrowse_create()
[in]userdataThe 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]tlbThe 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]tlbToplist object
[in]indexIndex 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]tlbToplist object
[in]indexIndex 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]tlbToplist 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]sessionSession object
[in]typeType of toplist to be browsed. see the sp_toplisttype enum for possible values
[in]regionRegion. see sp_toplistregion enum. Country specific regions are coded as two chars in an integer. Sweden would correspond to 'S' << 8 | 'E'
[in]usernameIf region is SP_TOPLIST_REGION_USER this specifies which user to get toplists for. NULL means the logged in user.
[in]callbackCallback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
[in]userdataUserdata 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]tlbToplist 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]tlbToplist 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]tlbToplist 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]tlbToplist 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]tlbToplist 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]tlbThe 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]tlbToplist object
[in]indexIndex 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 Tue Jun 4 2013 15:11:47.
Copyright © 2006–2013 Spotify Ltd