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] link The 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] link The 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] link The 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] link The Spotify link whose string representation you are interested in
[out] buffer The buffer to hold the string representation of link
[in] buffer_size The 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] link The 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] link The Spotify link whose track you are interested in
[out] offset Pointer 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] link The 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] album An 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] album An album object
[in] size The 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] artist An 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] artist Artist browse object
[in] size The 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] arb Artist browse object
[in] index The 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] image Image 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] playlist Playlist 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] search Search 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] link A 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] track A track object
[in] offset Offset 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] user User 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] link The 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] link The 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 Wed Jun 13 2012 14:22:40.
Copyright © 2006–2012 Spotify Ltd