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
}

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_artist (sp_artist *artist)
sp_linksp_link_create_from_search (sp_search *search)
sp_linksp_link_create_from_playlist (sp_playlist *playlist)
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_albumsp_link_as_album (sp_link *link)
sp_artistsp_link_as_artist (sp_link *link)
void sp_link_add_ref (sp_link *link)
void 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.


Function Documentation

void sp_link_add_ref ( sp_link link  ) 

Increase the reference count of a link

Parameters:
[in] link The link object

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

Here is a snippet from link.c:

static void print_link(sp_link *link)
{
    char spotify_uri[256];

    if (0 > sp_link_as_string(link, spotify_uri, sizeof(spotify_uri))) {
        fprintf(stderr, "failed to render Spotify URI from link\n");
        g_exit_code = 8;
        return;
    }

    printf("%s link %s\n", get_link_type_label(link), spotify_uri);
}

static void try_links(sp_session *session)
{
    const char SPOTIFY_URI[] = "spotify:track:6JEK0CvvjDjjMUBFoXShNZ";
    sp_link *link = sp_link_create_from_string(SPOTIFY_URI);

    if (!link) {
        fprintf(stderr, "failed to get link from a Spotify URI\n");
        g_exit_code = 6;
        return;
    }

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:
link.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:
track.c.

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

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

Here is a snippet from link.c:

    sp_link *link = sp_link_create_from_string(SPOTIFY_URI);

    if (!link) {
        fprintf(stderr, "failed to get link from a Spotify URI\n");
        g_exit_code = 6;
        return;
    }

    print_link(link);

    // The create function will have increased the reference count for us.
    sp_link_release(link);

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, link.c, and track.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()

void sp_link_release ( sp_link link  ) 

Decrease the reference count of a link

Parameters:
[in] link The link object
Examples:
browse.c, link.c, and track.c.

sp_linktype sp_link_type ( sp_link link  ) 

The link type of the specified link

Here is a snippet from link.c:

static const char* get_link_type_label(sp_link *link)
{
    static const char *LINK_TYPES[] = {
        "invalid",
        "track",
        "album",
        "artist",
        "search",
        "playlist"
    };

    return LINK_TYPES[sp_link_type(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:
link.c.


Generated on Tue Apr 7 15:21:55 2009.
Copyright © 2006–2009 Spotify Ltd