libspotify
Enumerations | Functions
Links (Spotify URIs)

Enumerations

enum  sp_linktype {
  SP_LINKTYPE_INVALID = 0,
  SP_LINKTYPE_TRACK = 1,
  SP_LINKTYPE_ALBUM = 2,
  SP_LINKTYPE_ARTIST = 3,
  SP_LINKTYPE_SEARCH = 4,
  SP_LINKTYPE_PLAYLIST = 5,
  SP_LINKTYPE_PROFILE = 6,
  SP_LINKTYPE_STARRED = 7,
  SP_LINKTYPE_LOCALTRACK = 8,
  SP_LINKTYPE_IMAGE = 9
}
 

Functions

sp_linksp_link_create_from_string (const char *link)
 
sp_linksp_link_create_from_track (sp_track *track, int offset)
 
sp_linksp_link_create_from_album (sp_album *album)
 
sp_linksp_link_create_from_album_cover (sp_album *album, sp_image_size size)
 
sp_linksp_link_create_from_artist (sp_artist *artist)
 
sp_linksp_link_create_from_artist_portrait (sp_artist *artist, sp_image_size size)
 
sp_linksp_link_create_from_artistbrowse_portrait (sp_artistbrowse *arb, int index)
 
sp_linksp_link_create_from_search (sp_search *search)
 
sp_linksp_link_create_from_playlist (sp_playlist *playlist)
 
sp_linksp_link_create_from_user (sp_user *user)
 
sp_linksp_link_create_from_image (sp_image *image)
 
int sp_link_as_string (sp_link *link, char *buffer, int buffer_size)
 
sp_linktype sp_link_type (sp_link *link)
 
sp_tracksp_link_as_track (sp_link *link)
 
sp_tracksp_link_as_track_and_offset (sp_link *link, int *offset)
 
sp_albumsp_link_as_album (sp_link *link)
 
sp_artistsp_link_as_artist (sp_link *link)
 
sp_usersp_link_as_user (sp_link *link)
 
sp_error sp_link_add_ref (sp_link *link)
 
sp_error sp_link_release (sp_link *link)
 

Detailed Description

These functions handle links to Spotify entities in a way that allows you to not care about the textual representation of the link.

Enumeration Type Documentation

Link types

Enumerator
SP_LINKTYPE_INVALID 

Link type not valid - default until the library has parsed the link, or when parsing failed.

SP_LINKTYPE_TRACK 

Link type is track.

SP_LINKTYPE_ALBUM 

Link type is album.

SP_LINKTYPE_ARTIST 

Link type is artist.

SP_LINKTYPE_SEARCH 

Link type is search.

SP_LINKTYPE_PLAYLIST 

Link type is playlist.

SP_LINKTYPE_PROFILE 

Link type is profile.

SP_LINKTYPE_STARRED 

Link type is starred.

SP_LINKTYPE_LOCALTRACK 

Link type is a local file.

SP_LINKTYPE_IMAGE 

Link type is an image.

Function Documentation

sp_error sp_link_add_ref ( sp_link link)

Increase the reference count of a link

Parameters
[in]linkThe link object
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_album* sp_link_as_album ( sp_link link)

The album representation for the given link

Parameters
[in]linkThe Spotify link whose album you are interested in
Returns
The album representation of the given album link If the link is not of album type then NULL is returned
Examples:
browse.c.
sp_artist* sp_link_as_artist ( sp_link link)

The artist representation for the given link

Parameters
[in]linkThe Spotify link whose artist you are interested in
Returns
The artist representation of the given link If the link is not of artist type then NULL is returned
Examples:
browse.c.
int sp_link_as_string ( sp_link link,
char *  buffer,
int  buffer_size 
)

Create a string representation of the given Spotify link

Parameters
[in]linkThe Spotify link whose string representation you are interested in
[out]bufferThe buffer to hold the string representation of link
[in]buffer_sizeThe max size of the buffer that will hold the string representation The resulting string is guaranteed to always be null terminated if buffer_size > 0
Returns
The number of characters in the string representation of the link. If this value is greater or equal than buffer_size, output was truncated.
Examples:
browse.c, and toplist.c.
sp_track* sp_link_as_track ( sp_link link)

The track representation for the given link

Parameters
[in]linkThe Spotify link whose track you are interested in
Returns
The track representation of the given track link If the link is not of track type then NULL is returned.
Examples:
browse.c.
sp_track* sp_link_as_track_and_offset ( sp_link link,
int *  offset 
)

The track and offset into track representation for the given link

Parameters
[in]linkThe Spotify link whose track you are interested in
[out]offsetPointer to offset into track (in milliseconds). If the link does not contain an offset this will be set to 0.
Returns
The track representation of the given track link If the link is not of track type then NULL is returned.
sp_user* sp_link_as_user ( sp_link link)

The user representation for the given link

Parameters
[in]linkThe Spotify link whose user you are interested in
Returns
The user representation of the given link If the link is not of user type then NULL is returned
sp_link* sp_link_create_from_album ( sp_album album)

Create a link object from an album

Parameters
[in]albumAn album object
Returns
A link representing the album
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_link* sp_link_create_from_album_cover ( sp_album album,
sp_image_size  size 
)

Create an image link object from an album

Parameters
[in]albumAn album object
[in]sizeThe desired size of the image
Returns
A link representing the album cover. Type is set to SP_LINKTYPE_IMAGE
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_link* sp_link_create_from_artist ( sp_artist artist)

Creates a link object from an artist

Parameters
[in]artistAn artist object
Returns
A link object representing the artist
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_link* sp_link_create_from_artist_portrait ( sp_artist artist,
sp_image_size  size 
)

Creates a link object pointing to an artist portrait

Parameters
[in]artistArtist browse object
[in]sizeThe desired size of the image
Returns
A link object representing an image
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_artistbrowse_num_portraits()
Examples:
toplist.c.
sp_link* sp_link_create_from_artistbrowse_portrait ( sp_artistbrowse arb,
int  index 
)

Creates a link object from an artist portrait

Parameters
[in]arbArtist browse object
[in]indexThe index of the portrait. Should be in the interval [0, sp_artistbrowse_num_portraits() - 1]
Returns
A link object representing an image
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_artistbrowse_num_portraits()
Note
The difference from sp_link_create_from_artist_portrait() is that the artist browse object may contain multiple portraits.
sp_link* sp_link_create_from_image ( sp_image image)

Create a link object representing the given image

Parameters
[in]imageImage object
Returns
A link representing the image.
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_link* sp_link_create_from_playlist ( sp_playlist playlist)

Create a link object representing the given playlist

Parameters
[in]playlistPlaylist object
Returns
A link representing the playlist
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
Note
Due to reasons in the playlist backend design and the Spotify URI scheme you need to wait for the playlist to be loaded before you can successfully construct an URI. If sp_link_create_from_playlist() returns NULL, try again after teh playlist_state_changed callback has fired.
sp_link* sp_link_create_from_search ( sp_search search)

Generate a link object representing the current search

Parameters
[in]searchSearch object
Returns
A link representing the search
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_link* sp_link_create_from_string ( const char *  link)

Create a Spotify link given a string

Parameters
[in]linkA string representation of a Spotify link
Returns
A link representation of the given string representation. If the link could not be parsed, this function returns NULL.
Note
You need to release the link when you are done with it.
See Also
sp_link_type()
sp_link_release()
Examples:
browse.c.
sp_link* sp_link_create_from_track ( sp_track track,
int  offset 
)

Generates a link object from a track

Parameters
[in]trackA track object
[in]offsetOffset in track in ms.
Returns
A link representing the track
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
Examples:
browse.c.
sp_link* sp_link_create_from_user ( sp_user user)

Create a link object representing the given playlist

Parameters
[in]userUser object
Returns
A link representing the profile.
Note
You need to release the link when you are done with it.
See Also
sp_link_release()
sp_error sp_link_release ( sp_link link)

Decrease the reference count of a link

Parameters
[in]linkThe link object
Returns
One of the following errors, from sp_error SP_ERROR_OK
Examples:
browse.c, and toplist.c.
sp_linktype sp_link_type ( sp_link link)

The link type of the specified link

Parameters
[in]linkThe Spotify link whose type you are interested in
Returns
The link type of the specified link - see the sp_linktype enum for possible values
Examples:
browse.c.

Generated on Tue Jun 4 2013 15:11:47.
Copyright © 2006–2013 Spotify Ltd