spotify 12.0.3 → 12.2.0

data/.travis.yml

@@ -1,4 +1,3 @@
 rvm:
-  - 1.8.7
   - 1.9.2
   - 1.9.3

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+[v12.2.0][]
+-----------
+- fix SessionConfig missing ca_certs_filename struct field on Linux
+
 __v12.1.0__
 -----------
 - erroneously released (wrong version number, does not follow version policy)
@@ -126,6 +130,7 @@ v0.0.0
 ------
 - release to register rubygems.org name
 
+[v12.2.0]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.3...v12.2.0
 [v12.0.3]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.2...v12.0.3
 [v12.0.2]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.1...v12.0.2
 [v12.0.1]: https://github.com/Burgestrand/libspotify-ruby/compare/v12.0.0...v12.0.1

data/Rakefile

@@ -5,10 +5,6 @@ rescue LoadError
   # do not require bundler rake tasks
 end
 
-require 'rake/testtask'
-Rake::TestTask.new do |spec|
-  spec.pattern = 'spec/*_spec.rb'
-end
 
 require 'yard'
 YARD::Rake::YardocTask.new
@@ -22,5 +18,16 @@ task :console do
   exec "irb", "-Ilib", "-rspotify"
 end
 
-task :spec => :test
-task :default => :test
+require 'rake/testtask'
+Rake::TestTask.new(:test_mac) do |spec|
+  spec.pattern = 'spec/*_spec.rb'
+  spec.ruby_opts = ['-r ./spec/mac-platform']
+end
+
+Rake::TestTask.new(:test_linux) do |spec|
+  spec.pattern = 'spec/*_spec.rb'
+  spec.ruby_opts = ['-r ./spec/linux-platform']
+end
+
+desc "Run the tests for both Linux and Mac OS"
+task :default => [:test_mac, :test_linux]

data/lib/spotify/functions.rb

@@ -22,31 +22,52 @@ module Spotify
     raise
   end
 
-  # Fetches the associated value of an enum from a given symbol.
-  #
-  # @example retrieving a value
-  #    Spotify.enum_value!(:ok, "error value") # => 0
-  #
-  # @example failing to retrieve a value
-  #    Spotify.enum_value!(:moo, "connection rule") # => ArgumentError, invalid connection rule: :moo
-  #
-  # @param [Symbol] symbol
-  # @param [#to_s] type used as error message when the symbol does not resolve
-  # @raise ArgumentError on failure
-  def self.enum_value!(symbol, type)
-    enum_value(symbol) or raise ArgumentError, "invalid #{type}: #{symbol}"
-  end
+  class << self
+    # Fetches the associated value of an enum from a given symbol.
+    #
+    # @example retrieving a value
+    #    Spotify.enum_value!(:ok, "error value") # => 0
+    #
+    # @example failing to retrieve a value
+    #    Spotify.enum_value!(:moo, "connection rule") # => ArgumentError, invalid connection rule: :moo
+    #
+    # @param [Symbol] symbol
+    # @param [#to_s] type used as error message when the symbol does not resolve
+    # @raise ArgumentError on failure
+    def enum_value!(symbol, type)
+      enum_value(symbol) or raise ArgumentError, "invalid #{type}: #{symbol}"
+    end
 
-  # Override FFI::Library#attach_function to always add the `:blocking` option.
-  #
-  # The reason for this is that which libspotify functions may call callbacks
-  # is unspecified. And really… I don’t know of any drawbacks with this method.
-  def self.attach_function(*arguments, &block)
-    options = arguments.pop if arguments.last.is_a?(Hash)
-    options ||= {}
-    options = { :blocking => true }.merge(options)
-    arguments << options
-    super(*arguments, &block)
+    # Override FFI::Library#attach_function to always add the `:blocking` option.
+    #
+    # The reason for this is that which libspotify functions may call callbacks
+    # is unspecified. And really… I don’t know of any drawbacks with this method.
+    def attach_function(*arguments, &block)
+      options = arguments.pop if arguments.last.is_a?(Hash)
+      options ||= {}
+      options = { :blocking => true }.merge(options)
+      arguments << options
+      super(*arguments, &block)
+    end
+
+    # @return [Boolean] true if on Linux
+    def linux?
+      platform == :linux
+    end
+
+    # @return [Boolean] true if on Mac OS
+    def mac?
+      platform == :mac
+    end
+
+    # @return [Symbol] platform as either :mac or :linux
+    def platform
+      case RUBY_PLATFORM
+      when /darwin/ then :mac
+      when /linux/ then :linux
+      else :unknown
+      end
+    end
   end
 
   # libspotify API version
@@ -133,9 +154,9 @@ module Spotify
   # @attr [Fixnum] sample_rate
   # @attr [Fixnum] channels
   class AudioFormat < FFI::Struct
-    layout :sample_type, :sampletype,
-           :sample_rate, :int,
-           :channels, :int
+    layout :sample_type => :sampletype,
+           :sample_rate => :int,
+           :channels => :int
   end
 
   # FFI::Struct for Audio Buffer Stats.
@@ -143,8 +164,8 @@ module Spotify
   # @attr [Fixnum] samples
   # @attr [Fixnum] stutter
   class AudioBufferStats < FFI::Struct
-    layout :samples, :int,
-           :stutter, :int
+    layout :samples => :int,
+           :stutter => :int
   end
 
   #
@@ -171,27 +192,27 @@ module Spotify
   # @attr [callback(:session, AudioBufferStats):void] get_audio_buffer_stats
   # @attr [callback(:session)::void] offline_status_updated
   class SessionCallbacks < FFI::Struct
-    layout :logged_in, callback([ :session, :error ], :void),
-           :logged_out, callback([ :session ], :void),
-           :metadata_updated, callback([ :session ], :void),
-           :connection_error, callback([ :session, :error ], :void),
-           :message_to_user, callback([ :session, :utf8_string ], :void),
-           :notify_main_thread, callback([ :session ], :void),
-           :music_delivery, callback([ :session, AudioFormat, :frames, :int ], :int),
-           :play_token_lost, callback([ :session ], :void),
-           :log_message, callback([ :session, :utf8_string ], :void),
-           :end_of_track, callback([ :session ], :void),
-           :streaming_error, callback([ :session, :error ], :void),
-           :userinfo_updated, callback([ :session ], :void),
-           :start_playback, callback([ :session ], :void),
-           :stop_playback, callback([ :session ], :void),
-           :get_audio_buffer_stats, callback([ :session, AudioBufferStats ], :void),
-           :offline_status_updated, callback([ :session ], :void),
-           :offline_error, callback([ :session, :error ], :void),
-           :credentials_blob_updated, callback([ :session, :string ], :void),
-           :connectionstate_updated, callback([ :session ], :void),
-           :scrobble_error, callback([ :session, :error ], :void),
-           :private_session_mode_changed, callback([ :session, :bool ], :void)
+    layout :logged_in => callback([ :session, :error ], :void),
+           :logged_out => callback([ :session ], :void),
+           :metadata_updated => callback([ :session ], :void),
+           :connection_error => callback([ :session, :error ], :void),
+           :message_to_user => callback([ :session, :utf8_string ], :void),
+           :notify_main_thread => callback([ :session ], :void),
+           :music_delivery => callback([ :session, AudioFormat, :frames, :int ], :int),
+           :play_token_lost => callback([ :session ], :void),
+           :log_message => callback([ :session, :utf8_string ], :void),
+           :end_of_track => callback([ :session ], :void),
+           :streaming_error => callback([ :session, :error ], :void),
+           :userinfo_updated => callback([ :session ], :void),
+           :start_playback => callback([ :session ], :void),
+           :stop_playback => callback([ :session ], :void),
+           :get_audio_buffer_stats => callback([ :session, AudioBufferStats ], :void),
+           :offline_status_updated => callback([ :session ], :void),
+           :offline_error => callback([ :session, :error ], :void),
+           :credentials_blob_updated => callback([ :session, :string ], :void),
+           :connectionstate_updated => callback([ :session ], :void),
+           :scrobble_error => callback([ :session, :error ], :void),
+           :private_session_mode_changed => callback([ :session, :bool ], :void)
   end
 
   # FFI::Struct for Session configuration.
@@ -206,22 +227,25 @@ module Spotify
   # @attr [Fixnum] dont_save_metadata_for_playlists
   # @attr [Fixnum] initially_unload_playlists
   class SessionConfig < FFI::Struct
-    layout :api_version, :int,
-           :cache_location, :string_pointer,
-           :settings_location, :string_pointer,
-           :application_key, :pointer,
-           :application_key_size, :size_t,
-           :user_agent, :string_pointer,
-           :callbacks, SessionCallbacks.by_ref,
-           :userdata, :userdata,
-           :compress_playlists, :bool,
-           :dont_save_metadata_for_playlists, :bool,
-           :initially_unload_playlists, :bool,
-           :device_id, :string_pointer,
-           :proxy, :string_pointer,
-           :proxy_username, :string_pointer,
-           :proxy_password, :string_pointer,
-           :tracefile, :string_pointer
+    it = {}
+    it[:api_version] = :int
+    it[:cache_location] = :string_pointer
+    it[:settings_location] = :string_pointer
+    it[:application_key] = :pointer
+    it[:application_key_size] = :size_t
+    it[:user_agent] = :string_pointer
+    it[:callbacks] = SessionCallbacks.by_ref
+    it[:userdata] = :userdata
+    it[:compress_playlists] = :bool
+    it[:dont_save_metadata_for_playlists] = :bool
+    it[:initially_unload_playlists] = :bool
+    it[:device_id] = :string_pointer
+    it[:proxy] = :string_pointer
+    it[:proxy_username] = :string_pointer
+    it[:proxy_password] = :string_pointer
+    it[:ca_certs_filename] = :string_pointer if Spotify.linux?
+    it[:tracefile] = :string_pointer
+    layout(it)
   end
 
   # FFI::Struct for Offline Sync Status
@@ -236,15 +260,15 @@ module Spotify
   # @attr [Fixnum] error_tracks
   # @attr [Fixnum] syncing
   class OfflineSyncStatus < FFI::Struct
-    layout :queued_tracks, :int,
-           :queued_bytes, :uint64,
-           :done_tracks, :int,
-           :done_bytes, :uint64,
-           :copied_tracks, :int,
-           :copied_bytes, :uint64,
-           :willnotcopy_tracks, :int,
-           :error_tracks, :int,
-           :syncing, :bool
+    layout :queued_tracks => :int,
+           :queued_bytes => :uint64,
+           :done_tracks => :int,
+           :done_bytes => :uint64,
+           :copied_tracks => :int,
+           :copied_bytes => :uint64,
+           :willnotcopy_tracks => :int,
+           :error_tracks => :int,
+           :syncing => :bool
   end
 
   #
@@ -542,19 +566,19 @@ module Spotify
   # @attr [callback(:playlist, :int, :utf8_string, :userdata):void] track_message_changed
   # @attr [callback(:playlist, :userdata):void] subscribers_changed
   class PlaylistCallbacks < FFI::Struct
-    layout :tracks_added, callback([ :playlist, :array, :int, :int, :userdata ], :void),
-           :tracks_removed, callback([ :playlist, :array, :int, :userdata ], :void),
-           :tracks_moved, callback([ :playlist, :array, :int, :int, :userdata ], :void),
-           :playlist_renamed, callback([ :playlist, :userdata ], :void),
-           :playlist_state_changed, callback([ :playlist, :userdata ], :void),
-           :playlist_update_in_progress, callback([ :playlist, :bool, :userdata ], :void),
-           :playlist_metadata_updated, callback([ :playlist, :userdata ], :void),
-           :track_created_changed, callback([ :playlist, :int, :user, :int, :userdata ], :void),
-           :track_seen_changed, callback([ :playlist, :int, :bool, :userdata ], :void),
-           :description_changed, callback([ :playlist, :utf8_string, :userdata ], :void),
-           :image_changed, callback([ :playlist, :image_id, :userdata ], :void),
-           :track_message_changed, callback([ :playlist, :int, :utf8_string, :userdata ], :void),
-           :subscribers_changed, callback([ :playlist, :userdata ], :void)
+    layout :tracks_added => callback([ :playlist, :array, :int, :int, :userdata ], :void),
+           :tracks_removed => callback([ :playlist, :array, :int, :userdata ], :void),
+           :tracks_moved => callback([ :playlist, :array, :int, :int, :userdata ], :void),
+           :playlist_renamed => callback([ :playlist, :userdata ], :void),
+           :playlist_state_changed => callback([ :playlist, :userdata ], :void),
+           :playlist_update_in_progress => callback([ :playlist, :bool, :userdata ], :void),
+           :playlist_metadata_updated => callback([ :playlist, :userdata ], :void),
+           :track_created_changed => callback([ :playlist, :int, :user, :int, :userdata ], :void),
+           :track_seen_changed => callback([ :playlist, :int, :bool, :userdata ], :void),
+           :description_changed => callback([ :playlist, :utf8_string, :userdata ], :void),
+           :image_changed => callback([ :playlist, :image_id, :userdata ], :void),
+           :track_message_changed => callback([ :playlist, :int, :utf8_string, :userdata ], :void),
+           :subscribers_changed => callback([ :playlist, :userdata ], :void)
   end
 
   # FFI::Struct for Subscribers of a Playlist.
@@ -562,8 +586,8 @@ module Spotify
   # @attr [Fixnum] count
   # @attr [Array<Pointer<String>>] subscribers
   class Subscribers < FFI::Struct
-    layout :count, :uint,
-           :subscribers, [:pointer, 1] # array of pointers to strings
+    layout :count => :uint,
+           :subscribers => [:pointer, 1] # array of pointers to strings
 
     # Redefined, as the layout of the Struct can only be determined
     # at run-time.

data/lib/spotify/types/pointer.rb

@@ -1,5 +1,3 @@
-require 'set'
-
 module Spotify
   # The Pointer is a kind of AutoPointer specially tailored for Spotify
   # objects, that releases the raw pointer on GC.

data/lib/spotify/version.rb

@@ -1,4 +1,4 @@
 module Spotify
   # See README for versioning policy.
-  VERSION = [12, 0, 3].join('.')
+  VERSION = [12, 2, 0].join('.')
 end

data/spec/api-linux.h

@@ -0,0 +1,3966 @@
+/*
+ * Copyright (c) 2006-2012 Spotify Ltd
+ *
+ * The terms of use for this and related files can be read in
+ * the associated LICENSE file, usually stored in share/doc/libspotify/LICENSE.
+ */
+
+/**
+ * @file   api.h    Public API for libspotify
+ *
+ * @note   All input strings are expected to be in UTF-8
+ * @note   All output strings are in UTF-8.
+ *
+ * @note   All usernames are valid XMPP nodeprep identifiers:
+ *         http://tools.ietf.org/html/rfc3920#appendix-A
+ *         If you need to store user data, we strongly advise you
+ *         to use the canonical form of the username.
+ */
+
+#ifndef PUBLIC_API_H
+#define PUBLIC_API_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef SP_CALLCONV
+#ifdef _WIN32
+#define SP_CALLCONV __stdcall
+#else
+#define SP_CALLCONV
+#endif
+#endif
+
+#ifndef SP_LIBEXPORT
+#ifdef _WIN32
+#define SP_LIBEXPORT(x) x __stdcall
+#else
+#define SP_LIBEXPORT(x) x
+#endif
+#endif
+
+/* Includes */
+#include <stddef.h>
+
+#ifdef _WIN32
+typedef unsigned __int64 sp_uint64;
+#else
+#include <stdint.h>
+typedef uint64_t sp_uint64;
+#endif
+
+/* General types */
+
+#if !defined(__cplusplus) && !defined(__bool_true_false_are_defined)
+typedef unsigned char bool;
+#endif
+
+typedef unsigned char byte;
+
+/**
+ * @defgroup types Spotify types & structs
+ *
+ * @{
+ */
+
+typedef struct sp_session sp_session; ///< Representation of a session
+typedef struct sp_track sp_track; ///< A track handle
+typedef struct sp_album sp_album; ///< An album handle
+typedef struct sp_artist sp_artist; ///< An artist handle
+typedef struct sp_artistbrowse sp_artistbrowse; ///< A handle to an artist browse result
+typedef struct sp_albumbrowse sp_albumbrowse; ///< A handle to an album browse result
+typedef struct sp_toplistbrowse sp_toplistbrowse; ///< A handle to a toplist browse result
+typedef struct sp_search sp_search; ///< A handle to a search result
+typedef struct sp_link sp_link; ///< A handle to the libspotify internal representation of a URI
+typedef struct sp_image sp_image; ///< A handle to an image
+typedef struct sp_user sp_user; ///< A handle to a user
+typedef struct sp_playlist sp_playlist; ///< A playlist handle
+typedef struct sp_playlistcontainer sp_playlistcontainer; ///< A playlist container (playlist containing other playlists) handle
+typedef struct sp_inbox sp_inbox; ///< Add to inbox request handle
+/** @} */
+
+/**
+ * @defgroup error Error Handling
+ *
+ * All functions in libspotify use the same set of error codes. Most of them return
+ * an error code, and let the result of the operation be stored in an out-parameter.
+ *
+ * @{
+ */
+
+/**
+ * Error codes returned by various functions
+ */
+typedef enum sp_error {
+  SP_ERROR_OK                        = 0,  ///< No errors encountered
+  SP_ERROR_BAD_API_VERSION           = 1,  ///< The library version targeted does not match the one you claim you support
+  SP_ERROR_API_INITIALIZATION_FAILED = 2,  ///< Initialization of library failed - are cache locations etc. valid?
+  SP_ERROR_TRACK_NOT_PLAYABLE        = 3,  ///< The track specified for playing cannot be played
+  SP_ERROR_BAD_APPLICATION_KEY       = 5,  ///< The application key is invalid
+  SP_ERROR_BAD_USERNAME_OR_PASSWORD  = 6,  ///< Login failed because of bad username and/or password
+  SP_ERROR_USER_BANNED               = 7,  ///< The specified username is banned
+  SP_ERROR_UNABLE_TO_CONTACT_SERVER  = 8,  ///< Cannot connect to the Spotify backend system
+  SP_ERROR_CLIENT_TOO_OLD            = 9,  ///< Client is too old, library will need to be updated
+  SP_ERROR_OTHER_PERMANENT           = 10, ///< Some other error occurred, and it is permanent (e.g. trying to relogin will not help)
+  SP_ERROR_BAD_USER_AGENT            = 11, ///< The user agent string is invalid or too long
+  SP_ERROR_MISSING_CALLBACK          = 12, ///< No valid callback registered to handle events
+  SP_ERROR_INVALID_INDATA            = 13, ///< Input data was either missing or invalid
+  SP_ERROR_INDEX_OUT_OF_RANGE        = 14, ///< Index out of range
+  SP_ERROR_USER_NEEDS_PREMIUM        = 15, ///< The specified user needs a premium account
+  SP_ERROR_OTHER_TRANSIENT           = 16, ///< A transient error occurred.
+  SP_ERROR_IS_LOADING                = 17, ///< The resource is currently loading
+  SP_ERROR_NO_STREAM_AVAILABLE       = 18, ///< Could not find any suitable stream to play
+  SP_ERROR_PERMISSION_DENIED         = 19, ///< Requested operation is not allowed
+  SP_ERROR_INBOX_IS_FULL             = 20, ///< Target inbox is full
+  SP_ERROR_NO_CACHE                  = 21, ///< Cache is not enabled
+  SP_ERROR_NO_SUCH_USER              = 22, ///< Requested user does not exist
+  SP_ERROR_NO_CREDENTIALS            = 23, ///< No credentials are stored
+  SP_ERROR_NETWORK_DISABLED          = 24, ///< Network disabled
+  SP_ERROR_INVALID_DEVICE_ID         = 25, ///< Invalid device ID
+  SP_ERROR_CANT_OPEN_TRACE_FILE      = 26, ///< Unable to open trace file
+  SP_ERROR_APPLICATION_BANNED        = 27, ///< This application is no longer allowed to use the Spotify service
+  SP_ERROR_OFFLINE_TOO_MANY_TRACKS   = 31, ///< Reached the device limit for number of tracks to download
+  SP_ERROR_OFFLINE_DISK_CACHE        = 32, ///< Disk cache is full so no more tracks can be downloaded to offline mode
+  SP_ERROR_OFFLINE_EXPIRED           = 33, ///< Offline key has expired, the user needs to go online again
+  SP_ERROR_OFFLINE_NOT_ALLOWED       = 34, ///< This user is not allowed to use offline mode
+  SP_ERROR_OFFLINE_LICENSE_LOST      = 35, ///< The license for this device has been lost. Most likely because the user used offline on three other device
+  SP_ERROR_OFFLINE_LICENSE_ERROR     = 36, ///< The Spotify license server does not respond correctly
+  SP_ERROR_LASTFM_AUTH_ERROR         = 39, ///< A LastFM scrobble authentication error has occurred
+  SP_ERROR_INVALID_ARGUMENT          = 40, ///< An invalid argument was specified
+  SP_ERROR_SYSTEM_FAILURE            = 41, ///< An operating system error
+} sp_error;
+
+/**
+ * Convert a numeric libspotify error code to a text string. The error message is in
+ * English. This function is useful for logging purposes.
+ *
+ * @param[in]   error   The error code to lookup
+ */
+SP_LIBEXPORT(const char*) sp_error_message(sp_error error);
+
+/** @} */
+
+
+
+/**
+ * @defgroup session Session handling
+ *
+ * The concept of a session is fundamental for all communication with the Spotify ecosystem - it is the
+ * object responsible for communicating with the Spotify service. You will need to instantiate a
+ * session that then can be used to request artist information, perform searches etc.
+ *
+ * @{
+ */
+
+/**
+ * Current version of the application interface, that is, the API described by this file.
+ *
+ * This value should be set in the sp_session_config struct passed to sp_session_create().
+ *
+ * If an (upgraded) library is no longer compatible with this version the error #SP_ERROR_BAD_API_VERSION will be
+ * returned from sp_session_create(). Future versions of the library will provide you with some kind of mechanism
+ * to request an updated version of the library.
+ */
+#define SPOTIFY_API_VERSION 12
+
+/**
+ * Describes the current state of the connection
+ */
+typedef enum sp_connectionstate {
+  SP_CONNECTION_STATE_LOGGED_OUT   = 0, ///< User not yet logged in
+  SP_CONNECTION_STATE_LOGGED_IN    = 1, ///< Logged in against a Spotify access point
+  SP_CONNECTION_STATE_DISCONNECTED = 2, ///< Was logged in, but has now been disconnected
+  SP_CONNECTION_STATE_UNDEFINED    = 3, ///< The connection state is undefined
+  SP_CONNECTION_STATE_OFFLINE    = 4  ///< Logged in in offline mode
+} sp_connectionstate;
+
+
+/**
+ * Sample type descriptor
+ */
+typedef enum sp_sampletype {
+  SP_SAMPLETYPE_INT16_NATIVE_ENDIAN = 0, ///< 16-bit signed integer samples
+} sp_sampletype;
+
+/**
+ * Audio format descriptor
+ */
+typedef struct sp_audioformat {
+  sp_sampletype sample_type;   ///< Sample type enum,
+  int sample_rate;             ///< Audio sample rate, in samples per second.
+  int channels;                ///< Number of channels. Currently 1 or 2.
+} sp_audioformat;
+
+/**
+ * Bitrate definitions for music streaming
+ */
+typedef enum sp_bitrate {
+  SP_BITRATE_160k      = 0, ///< Bitrate 160kbps
+  SP_BITRATE_320k      = 1, ///< Bitrate 320kbps
+  SP_BITRATE_96k       = 2, ///< Bitrate 96kbps
+} sp_bitrate;
+
+/**
+ * Playlist types
+ */
+typedef enum sp_playlist_type {
+  SP_PLAYLIST_TYPE_PLAYLIST     = 0, ///< A normal playlist.
+  SP_PLAYLIST_TYPE_START_FOLDER = 1, ///< Marks a folder starting point,
+  SP_PLAYLIST_TYPE_END_FOLDER   = 2, ///< and ending point.
+  SP_PLAYLIST_TYPE_PLACEHOLDER  = 3, ///< Unknown entry.
+} sp_playlist_type;
+
+
+
+/**
+ * Search types
+ */
+typedef enum sp_search_type {
+  SP_SEARCH_STANDARD  = 0,
+  SP_SEARCH_SUGGEST = 1,
+} sp_search_type;
+
+/**
+ * Playlist offline status
+ */
+typedef enum sp_playlist_offline_status {
+  SP_PLAYLIST_OFFLINE_STATUS_NO          = 0, ///< Playlist is not offline enabled
+  SP_PLAYLIST_OFFLINE_STATUS_YES         = 1, ///< Playlist is synchronized to local storage
+  SP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING = 2, ///< This playlist is currently downloading. Only one playlist can be in this state any given time
+  SP_PLAYLIST_OFFLINE_STATUS_WAITING     = 3, ///< Playlist is queued for download
+} sp_playlist_offline_status;
+
+/**
+ * Track availability
+ */
+typedef enum sp_availability {
+  SP_TRACK_AVAILABILITY_UNAVAILABLE = 0, ///< Track is not available
+  SP_TRACK_AVAILABILITY_AVAILABLE   = 1, ///< Track is available and can be played
+  SP_TRACK_AVAILABILITY_NOT_STREAMABLE = 2, ///< Track can not be streamed using this account
+  SP_TRACK_AVAILABILITY_BANNED_BY_ARTIST = 3, ///< Track not available on artist's reqeust
+} sp_track_availability;
+
+/**
+ * Track offline status
+ */
+typedef enum sp_track_offline_status {
+  SP_TRACK_OFFLINE_NO             = 0, ///< Not marked for offline
+  SP_TRACK_OFFLINE_WAITING        = 1, ///< Waiting for download
+  SP_TRACK_OFFLINE_DOWNLOADING    = 2, ///< Currently downloading
+  SP_TRACK_OFFLINE_DONE           = 3, ///< Downloaded OK and can be played
+  SP_TRACK_OFFLINE_ERROR          = 4, ///< Error during download
+  SP_TRACK_OFFLINE_DONE_EXPIRED   = 5, ///< Downloaded OK but not playable due to expiery
+  SP_TRACK_OFFLINE_LIMIT_EXCEEDED = 6, ///< Waiting because device have reached max number of allowed tracks
+  SP_TRACK_OFFLINE_DONE_RESYNC    = 7, ///< Downloaded OK and available but scheduled for re-download
+} sp_track_offline_status;
+
+/**
+ * Image size
+ */
+typedef enum sp_image_size {
+  SP_IMAGE_SIZE_NORMAL                  = 0, ///< Normal image size
+  SP_IMAGE_SIZE_SMALL                   = 1, ///< Small image size
+  SP_IMAGE_SIZE_LARGE                   = 2, ///< Large image size
+} sp_image_size;
+
+/**
+ * Buffer stats used by get_audio_buffer_stats callback
+ */
+typedef struct sp_audio_buffer_stats {
+  int samples;                      ///< Samples in buffer
+  int stutter;                      ///< Number of stutters (audio dropouts) since last query
+} sp_audio_buffer_stats;
+
+/**
+ * List of subscribers returned by sp_playlist_subscribers()
+ */
+typedef struct sp_subscribers {
+  unsigned int count;    ///< Number of elements in 'subscribers'
+  char *subscribers[1];  ///< Actual size is 'count'. Array of pointers to canonical usernames
+} sp_subscribers;
+
+
+/**
+ * Current connection type set using sp_session_set_connection_type()
+ */
+typedef enum sp_connection_type {
+  SP_CONNECTION_TYPE_UNKNOWN        = 0, ///< Connection type unknown (Default)
+  SP_CONNECTION_TYPE_NONE           = 1, ///< No connection
+  SP_CONNECTION_TYPE_MOBILE         = 2, ///< Mobile data (EDGE, 3G, etc)
+  SP_CONNECTION_TYPE_MOBILE_ROAMING = 3, ///< Roamed mobile data (EDGE, 3G, etc)
+  SP_CONNECTION_TYPE_WIFI           = 4, ///< Wireless connection
+  SP_CONNECTION_TYPE_WIRED          = 5, ///< Ethernet cable, etc
+} sp_connection_type;
+
+
+/**
+ * Connection rules, bitwise OR of flags
+ *
+ * The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC
+ */
+typedef enum sp_connection_rules {
+  SP_CONNECTION_RULE_NETWORK                = 0x1, ///< Allow network traffic. When not set libspotify will force itself into offline mode
+  SP_CONNECTION_RULE_NETWORK_IF_ROAMING     = 0x2, ///< Allow network traffic even if roaming
+  SP_CONNECTION_RULE_ALLOW_SYNC_OVER_MOBILE = 0x4, ///< Set to allow syncing of offline content over mobile connections
+  SP_CONNECTION_RULE_ALLOW_SYNC_OVER_WIFI   = 0x8, ///< Set to allow syncing of offline content over WiFi
+} sp_connection_rules;
+
+
+/**
+ * Controls the type of data that will be included in artist browse queries
+ */
+typedef enum sp_artistbrowse_type {
+  SP_ARTISTBROWSE_FULL,         /**< All information except tophit tracks
+                   This mode is deprecated and will removed in a future release */
+  SP_ARTISTBROWSE_NO_TRACKS,    /**< Only albums and data about them, no tracks.
+             In other words, sp_artistbrowse_num_tracks() will return 0
+              */
+  SP_ARTISTBROWSE_NO_ALBUMS,    /**< Only return data about the artist (artist name, similar artist
+             biography, etc
+             No tracks or album will be abailable.
+             sp_artistbrowse_num_tracks() and sp_artistbrowse_num_albums()
+             will both return 0
+              */
+} sp_artistbrowse_type;
+
+typedef enum sp_social_provider {
+  SP_SOCIAL_PROVIDER_SPOTIFY,
+  SP_SOCIAL_PROVIDER_FACEBOOK,
+  SP_SOCIAL_PROVIDER_LASTFM,
+} sp_social_provider;
+
+typedef enum sp_scrobbling_state {
+  SP_SCROBBLING_STATE_USE_GLOBAL_SETTING    = 0,
+  SP_SCROBBLING_STATE_LOCAL_ENABLED         = 1,
+  SP_SCROBBLING_STATE_LOCAL_DISABLED        = 2,
+  SP_SCROBBLING_STATE_GLOBAL_ENABLED        = 3,
+  SP_SCROBBLING_STATE_GLOBAL_DISABLED       = 4,
+} sp_scrobbling_state;
+
+
+/**
+ * Offline sync status
+ */
+typedef struct sp_offline_sync_status {
+  /**
+   * Queued tracks/bytes is things left to sync in current sync
+   * operation
+   */
+  int queued_tracks;
+  sp_uint64 queued_bytes;
+
+  /**
+   * Done tracks/bytes is things marked for sync that existed on
+   * device before current sync operation
+   */
+  int done_tracks;
+  sp_uint64 done_bytes;
+
+  /**
+   * Copied tracks/bytes is things that has been copied in
+   * current sync operation
+   */
+  int copied_tracks;
+  sp_uint64 copied_bytes;
+
+  /**
+   * Tracks that are marked as synced but will not be copied
+   * (for various reasons)
+   */
+  int willnotcopy_tracks;
+
+  /**
+   * A track is counted as error when something goes wrong while
+   * syncing the track
+   */
+  int error_tracks;
+
+  /**
+   * Set if sync operation is in progress
+   */
+  bool syncing;
+
+} sp_offline_sync_status;
+
+
+/**
+ * Session callbacks
+ *
+ * Registered when you create a session.
+ * If some callbacks should not be of interest, set them to NULL.
+ */
+typedef struct sp_session_callbacks {
+
+  /**
+   * Called when login has been processed and was successful
+   *
+   * @param[in]  session    Session
+   * @param[in]  error      One of the following errors, from ::sp_error
+   *                        SP_ERROR_OK
+   *                        SP_ERROR_CLIENT_TOO_OLD
+   *                        SP_ERROR_UNABLE_TO_CONTACT_SERVER
+   *                        SP_ERROR_BAD_USERNAME_OR_PASSWORD
+   *                        SP_ERROR_USER_BANNED
+   *                        SP_ERROR_USER_NEEDS_PREMIUM
+   *                        SP_ERROR_OTHER_TRANSIENT
+   *                        SP_ERROR_OTHER_PERMANENT
+   */
+  void (SP_CALLCONV *logged_in)(sp_session *session, sp_error error);
+
+  /**
+   * Called when logout has been processed. Either called explicitly
+   * if you initialize a logout operation, or implicitly if there
+   * is a permanent connection error
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *logged_out)(sp_session *session);
+  /**
+   * Called whenever metadata has been updated
+   *
+   * If you have metadata cached outside of libspotify, you should purge
+   * your caches and fetch new versions.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *metadata_updated)(sp_session *session);
+
+  /**
+   * Called when there is a connection error, and the library has problems
+   * reconnecting to the Spotify service. Could be called multiple times (as
+   * long as the problem is present)
+   *
+   *
+   * @param[in]  session    Session
+   * @param[in]  error      One of the following errors, from ::sp_error
+   *                        SP_ERROR_OK
+   *                        SP_ERROR_CLIENT_TOO_OLD
+   *                        SP_ERROR_UNABLE_TO_CONTACT_SERVER
+   *                        SP_ERROR_BAD_USERNAME_OR_PASSWORD
+   *                        SP_ERROR_USER_BANNED
+   *                        SP_ERROR_USER_NEEDS_PREMIUM
+   *                        SP_ERROR_OTHER_TRANSIENT
+   *                        SP_ERROR_OTHER_PERMANENT
+   */
+  void (SP_CALLCONV *connection_error)(sp_session *session, sp_error error);
+
+  /**
+   * Called when the access point wants to display a message to the user
+   *
+   * In the desktop client, these are shown in a blueish toolbar just below the
+   * search box.
+   *
+   * @param[in]  session    Session
+   * @param[in]  message    String in UTF-8 format.
+   */
+  void (SP_CALLCONV *message_to_user)(sp_session *session, const char *message);
+
+  /**
+   * Called when processing needs to take place on the main thread.
+   *
+   * You need to call sp_session_process_events() in the main thread to get
+   * libspotify to do more work. Failure to do so may cause request timeouts,
+   * or a lost connection.
+   *
+   * @param[in]  session    Session
+   *
+   * @note This function is called from an internal session thread - you need to have proper synchronization!
+   */
+  void (SP_CALLCONV *notify_main_thread)(sp_session *session);
+
+  /**
+   * Called when there is decompressed audio data available.
+   *
+   * @param[in]  session    Session
+   * @param[in]  format     Audio format descriptor sp_audioformat
+   * @param[in]  frames     Points to raw PCM data as described by \p format
+   * @param[in]  num_frames Number of available samples in \p frames.
+   *                        If this is 0, a discontinuity has occurred (such as after a seek). The application
+   *                        should flush its audio fifos, etc.
+   *
+   * @return                Number of frames consumed.
+   *                        This value can be used to rate limit the output from the library if your
+   *                        output buffers are saturated. The library will retry delivery in about 100ms.
+   *
+   * @note This function is called from an internal session thread - you need to have proper synchronization!
+   *
+   * @note This function must never block. If your output buffers are full you must return 0 to signal
+   *       that the library should retry delivery in a short while.
+   */
+  int (SP_CALLCONV *music_delivery)(sp_session *session, const sp_audioformat *format, const void *frames, int num_frames);
+
+  /**
+   * Music has been paused because an account only allows music
+   * to be played from one location simultaneously.
+   *
+   * @note When this callback is invoked the application should
+   *       behave just as if the user pressed the pause
+   *       button. The application should also display a message
+   *       to the user indicating the playback has been paused
+   *       because another application is playing using the same
+   *       account.
+   *
+   * @note IT MUST NOT automatically resume playback but must
+   *       instead wait for the user to press play.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *play_token_lost)(sp_session *session);
+
+  /**
+   * Logging callback.
+   *
+   * @param[in]  session    Session
+   * @param[in]  data       Log data
+   */
+  void (SP_CALLCONV *log_message)(sp_session *session, const char *data);
+
+  /**
+   * End of track.
+   * Called when the currently played track has reached its end.
+   *
+   * @note This function is invoked from the main thread
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *end_of_track)(sp_session *session);
+
+  /**
+   * Streaming error.
+   * Called when streaming cannot start or continue.
+   *
+   * @note This function is invoked from the main thread
+   *
+   * @param[in]  session    Session
+   * @param[in]  error      One of the following errors, from ::sp_error
+   *                        SP_ERROR_NO_STREAM_AVAILABLE
+   *                        SP_ERROR_OTHER_TRANSIENT
+   *                        SP_ERROR_OTHER_PERMANENT
+   */
+  void (SP_CALLCONV *streaming_error)(sp_session *session, sp_error error);
+
+  /**
+   * Called after user info (anything related to sp_user objects) have been updated.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *userinfo_updated)(sp_session *session);
+
+  /**
+   * Called when audio playback should start
+   *
+   * @note For this to work correctly the application must also implement get_audio_buffer_stats()
+   *
+   * @note This function is called from an internal session thread - you need to have proper synchronization!
+   *
+   * @note This function must never block.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *start_playback)(sp_session *session);
+
+
+  /**
+   * Called when audio playback should stop
+   *
+   * @note For this to work correctly the application must also implement get_audio_buffer_stats()
+   *
+   * @note This function is called from an internal session thread - you need to have proper synchronization!
+   *
+   * @note This function must never block.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *stop_playback)(sp_session *session);
+
+  /**
+   * Called to query application about its audio buffer
+   *
+   * @note This function is called from an internal session thread - you need to have proper synchronization!
+   *
+   * @note This function must never block.
+   *
+   * @param[in]  session    Session
+   * @param[out] stats      Stats struct to be filled by application
+   */
+  void (SP_CALLCONV *get_audio_buffer_stats)(sp_session *session, sp_audio_buffer_stats *stats);
+
+  /**
+   * Called when offline synchronization status is updated
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *offline_status_updated)(sp_session *session);
+
+  /**
+   * Called when offline synchronization status is updated
+   *
+   * @param[in]  session    Session
+   * @param[in]  error      Offline error. Will be SP_ERROR_OK if the offline synchronization
+   *                        error state has cleared
+   */
+  void (SP_CALLCONV *offline_error)(sp_session *session, sp_error error);
+
+  /**
+   * Called when storable credentials have been updated, usually called when
+   * we have connected to the AP.
+   *
+   * @param[in]  session    Session
+   * @param[in]  blob   Blob is a null-terminated string which contains
+   *        an encrypted token that can be stored safely on disk
+   *        instead of storing plaintext passwords.
+   */
+  void (SP_CALLCONV *credentials_blob_updated)(sp_session *session, const char *blob);
+
+  /**
+   * Called when the connection state has updated - such as when logging in, going offline, etc.
+   *
+   * @param[in]  session    Session
+   */
+  void (SP_CALLCONV *connectionstate_updated)(sp_session *session);
+
+   /**
+  * Called when there is a scrobble error event
+  *
+  * @param[in]  session    Session
+  * @param[in]  error      Scrobble error. Currently SP_ERROR_LASTFM_AUTH_ERROR.
+  */
+  void (SP_CALLCONV *scrobble_error)(sp_session *session, sp_error error);
+
+   /**
+  * Called when there is a change in the private session mode
+  *
+  * @param[in]  session    Session
+  * @param[in]  isPrivate  True if in private session, false otherwhise
+  */
+  void (SP_CALLCONV *private_session_mode_changed)(sp_session *session, bool is_private);
+} sp_session_callbacks;
+
+/**
+ * Session config
+ */
+typedef struct sp_session_config {
+  int api_version;                       ///< The version of the Spotify API your application is compiled with. Set to #SPOTIFY_API_VERSION
+  const char *cache_location;            /**< The location where Spotify will write cache files.
+            *   This cache include tracks, cached browse results and coverarts.
+                                          *   Set to empty string ("") to disable cache
+            */
+  const char *settings_location;         /**< The location where Spotify will write setting files and per-user
+            *   cache items. This includes playlists, track metadata, etc.
+            *   'settings_location' may be the same path as 'cache_location'.
+            *   'settings_location' folder will not be created (unlike 'cache_location'),
+            *   if you don't want to create the folder yourself, you can set 'settings_location' to 'cache_location'.
+            */
+  const void *application_key;           ///< Your application key
+  size_t application_key_size;           ///< The size of the application key in bytes
+  const char *user_agent;                /**< "User-Agent" for your application - max 255 characters long
+                 The User-Agent should be a relevant, customer facing identification of your application
+                 */
+
+  const sp_session_callbacks *callbacks; ///< Delivery callbacks for session events, or NULL if you are not interested in any callbacks (not recommended!)
+  void *userdata;                        ///< User supplied data for your application
+
+  /**
+   * Compress local copy of playlists, reduces disk space usage
+   */
+  bool compress_playlists;
+
+  /**
+   * Don't save metadata for local copies of playlists
+   * Reduces disk space usage at the expense of needing
+   * to request metadata from Spotify backend when loading list
+   */
+  bool dont_save_metadata_for_playlists;
+
+  /**
+   * Avoid loading playlists into RAM on startup.
+   * See sp_playlist_is_in_ram() for more details.
+   */
+  bool initially_unload_playlists;
+
+  /**
+   * Device ID for offline synchronization and logging purposes. The Device Id must be unique to the particular device instance,
+   * i.e. no two units must supply the same Device ID. The Device ID must not change between sessions or power cycles.
+   * Good examples is the device's MAC address or unique serial number.
+   */
+  const char *device_id;
+
+  /**
+   * Url to the proxy server that should be used.
+   * The format is protocol://<host>:port (where protocal is http/https/socks4/socks5)
+   */
+  const char *proxy;
+  /**
+   * Username to authenticate with proxy server
+   */
+  const char *proxy_username;
+  /**
+   * Password to authenticate with proxy server
+   */
+  const char *proxy_password;
+
+  /**
+   * Path to a file containing the root ca certificates that the peer should be verified with.
+       * The file must be a concatenation of all certificates in PEM format. Provided with libspotify
+   * is a sample pem file in examples. It is recommended that the application export a similar file from
+   * the local certificate store.
+       */
+  const char *ca_certs_filename;
+
+  /**
+   * Path to API trace file
+   */
+  const char *tracefile;
+
+} sp_session_config;
+
+/**
+ * Initialize a session. The session returned will be initialized, but you will need
+ * to log in before you can perform any other operation
+ * Currently it is not supported to have multiple active sessions, and it's recommended to only call this once per process.
+ *
+ * Here is a snippet from \c spshell.c:
+ * @dontinclude spshell.c
+ * @skip config.api_version
+ * @until }
+ *
+ * @param[in]   config    The configuration to use for the session
+ * @param[out]  sess      If successful, a new session - otherwise NULL
+ *
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ *                        SP_ERROR_BAD_API_VERSION
+ *                        SP_ERROR_BAD_USER_AGENT
+ *                        SP_ERROR_BAD_APPLICATION_KEY
+ *                        SP_ERROR_API_INITIALIZATION_FAILED
+ *                        SP_ERROR_INVALID_DEVICE_ID
+ */
+SP_LIBEXPORT(sp_error) sp_session_create(const sp_session_config *config, sp_session **sess);
+
+/**
+ * Release the session. This will clean up all data and connections associated with the session
+ *
+ * @param[in]   sess      Session object returned from sp_session_create()
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_release(sp_session *sess);
+
+
+/**
+ * Logs in the specified username/password combo. This initiates the login in the background.
+ * A callback is called when login is complete
+ *
+ * An application MUST NEVER store the user's password in clear text.
+ * If automatic relogin is required, use sp_session_relogin()
+ *
+ * Here is a snippet from \c spshell.c:
+ * @dontinclude spshell.c
+ * @skip sp_session_login
+ * @until }
+ *
+ * @param[in]   session             Your session object
+ * @param[in]   username            The username to log in
+ * @param[in]   password            The password for the specified username
+ * @param[in]   remember_me         If set, the username / password will be remembered by libspotify
+ * @param[in]   blob              If you have received a blob in the #credentials_blob_updated
+ *                                  you can pas this here instead of password
+ * @return                          One of the following errors, from ::sp_error
+ *                                  SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_login(sp_session *session, const char *username, const char *password, bool remember_me, const char *blob);
+
+
+/**
+ * Log in the remembered user if last user that logged in logged in with remember_me set.
+ * If no credentials are stored, this will return SP_ERROR_NO_CREDENTIALS.
+ *
+ * @param[in]   session      Your session object
+ *
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ *                         SP_ERROR_NO_CREDENTIALS
+ */
+SP_LIBEXPORT(sp_error) sp_session_relogin(sp_session *session);
+
+
+/**
+ * Get username of the user that will be logged in via sp_session_relogin()
+ *
+ * @param[in]   session      Your session object
+ * @param[out]  buffer       The buffer to hold the username
+ * @param[in]   buffer_size  The max size of the buffer that will hold the username.
+ *                           The resulting string is guaranteed to always be null terminated if
+ *                           buffer_size > 0
+ *
+ * @return                   The number of characters in the username.
+ *                           If value is greater or equal than \p buffer_size, output was truncated.
+ *                           If returned value is -1 no credentials are stored in libspotify.
+ */
+SP_LIBEXPORT(int) sp_session_remembered_user(sp_session *session, char *buffer, size_t buffer_size);
+
+
+/**
+ * Get a pointer to a string representing the user's login username.
+ *
+ * @param[in]   session         Your session object
+ *
+ * @return                   A string representing the login username.
+ */
+SP_LIBEXPORT(const char *) sp_session_user_name(sp_session *session);
+
+
+/**
+ * Remove stored credentials in libspotify. If no credentials are currently stored, nothing will happen.
+ *
+ * @param[in]   session      Your session object
+ * @return                   One of the following errors, from ::sp_error
+ *                           SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_forget_me(sp_session *session);
+
+
+/**
+ * Fetches the currently logged in user
+ *
+ * @param[in]   session    Your session object
+ *
+ * @return                 The logged in user (or NULL if not logged in)
+ */
+SP_LIBEXPORT(sp_user *) sp_session_user(sp_session *session);
+
+/**
+ * Logs out the currently logged in user
+ *
+ * Always call this before terminating the application and libspotify is currently
+ * logged in. Otherwise, the settings and cache may be lost.
+ *
+ * @param[in]   session    Your session object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_logout(sp_session *session);
+
+
+/**
+ * Flush the caches
+ *
+ * This will make libspotify write all data that is meant to be stored
+ * on disk to the disk immediately. libspotify does this periodically
+ * by itself and also on logout. So under normal conditions this
+ * should never need to be used.
+ *
+ * @param[in]   session    Your session object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_flush_caches(sp_session *session);
+
+/**
+ * The connection state of the specified session.
+ *
+ * @param[in]   session    Your session object
+ *
+ * @return                 The connection state - see the sp_connectionstate enum for possible values
+ */
+SP_LIBEXPORT(sp_connectionstate) sp_session_connectionstate(sp_session *session);
+
+/**
+ * The userdata associated with the session
+ *
+ * @param[in]   session    Your session object
+ *
+ * @return                 The userdata that was passed in on session creation
+ */
+SP_LIBEXPORT(void *) sp_session_userdata(sp_session *session);
+
+/**
+ * Set maximum cache size.
+ *
+ * @param[in]   session    Your session object
+ * @param[in]   size       Maximum cache size in megabytes.
+ *                         Setting it to 0 (the default) will let libspotify automatically
+ *                         resize the cache (10% of disk free space)
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_cache_size(sp_session *session, size_t size);
+
+/**
+ * Make the specified session process any pending events
+ *
+ * @param[in]   session         Your session object
+ * @param[out]  next_timeout    Stores the time (in milliseconds) until you should call this function again
+ * @return                      One of the following errors, from ::sp_error
+ *                              SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_process_events(sp_session *session, int *next_timeout);
+
+/**
+ * Loads the specified track
+ *
+ * After successfully loading the track, you have the option of running
+ * sp_session_player_play() directly, or using sp_session_player_seek() first.
+ * When this call returns, the track will have been loaded, unless an error occurred.
+ *
+ * @param[in]   session    Your session object
+ * @param[in]   track      The track to be loaded
+ *
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ *                         SP_ERROR_MISSING_CALLBACK
+ *                         SP_ERROR_TRACK_NOT_PLAYABLE
+ *
+ */
+SP_LIBEXPORT(sp_error) sp_session_player_load(sp_session *session, sp_track *track);
+
+/**
+ * Seek to position in the currently loaded track
+ *
+ * @param[in]   session    Your session object
+ * @param[in]   offset     Track position, in milliseconds.
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_player_seek(sp_session *session, int offset);
+
+/**
+ * Play or pause the currently loaded track
+ *
+ * @param[in]   session    Your session object
+ * @param[in]   play       If set to true, playback will occur. If set to false, the playback will be paused.
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_player_play(sp_session *session, bool play);
+
+/**
+ * Stops the currently playing track
+ *
+ * This frees some resources held by libspotify to identify the currently
+ * playing track.
+ *
+ * @param[in]   session    Your session object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_player_unload(sp_session *session);
+
+/**
+ * Prefetch a track
+ *
+ * Instruct libspotify to start loading of a track into its cache.
+ * This could be done by an application just before the current track ends.
+ *
+ * @param[in]   session    Your session object
+ * @param[in]   track      The track to be prefetched
+ *
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_NO_CACHE
+ *                         SP_ERROR_OK
+ *
+ * @note Prefetching is only possible if a cache is configured
+ *
+ */
+SP_LIBEXPORT(sp_error) sp_session_player_prefetch(sp_session *session, sp_track *track);
+
+/**
+ * Returns the playlist container for the currently logged in user.
+ *
+ * @param[in]   session    Your session object
+ *
+ * @return                 Playlist container object, NULL if not logged in
+ */
+SP_LIBEXPORT(sp_playlistcontainer *) sp_session_playlistcontainer(sp_session *session);
+
+/**
+ * Returns an inbox playlist for the currently logged in user
+ *
+ * @param[in]  session        Session object
+ *
+ * @return     A playlist or NULL if no user is logged in
+ * @note You need to release the playlist when you are done with it.
+ * @see sp_playlist_release()
+ */
+SP_LIBEXPORT(sp_playlist *) sp_session_inbox_create(sp_session *session);
+
+/**
+ * Returns the starred list for the current user
+ *
+ * @param[in]  session        Session object
+ *
+ * @return     A playlist or NULL if no user is logged in
+ * @note You need to release the playlist when you are done with it.
+ * @see sp_playlist_release()
+ */
+SP_LIBEXPORT(sp_playlist *) sp_session_starred_create(sp_session *session);
+
+/**
+ * Returns the starred list for a user
+ *
+ * @param[in]  session        Session object
+ * @param[in]  canonical_username       Canonical username
+ *
+ * @return     A playlist or NULL if no user is logged in
+ * @note You need to release the playlist when you are done with it.
+ * @see sp_playlist_release()
+ */
+SP_LIBEXPORT(sp_playlist *) sp_session_starred_for_user_create(sp_session *session, const char *canonical_username);
+
+/**
+ * Return the published container for a given @a canonical_username,
+ * or the currently logged in user if @a canonical_username is NULL.
+ *
+ * When done with the list you should call sp_playlistconatiner_release() to
+ * decrese the reference you own by having created it.
+ *
+ * @param[in]   session    Your session object.
+ * @param[in]   canonical_username   The canonical username, or NULL.
+ *
+ * @return Playlist container object, NULL if not logged in.
+ */
+SP_LIBEXPORT(sp_playlistcontainer *) sp_session_publishedcontainer_for_user_create(sp_session *session, const char *canonical_username);
+
+
+/**
+ * Set preferred bitrate for music streaming
+ *
+ * @param[in]  session        Session object
+ * @param[in]  bitrate        Preferred bitrate, see ::sp_bitrate for possible values
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ *                            SP_ERROR_INVALID_ARGUMENT
+ */
+SP_LIBEXPORT(sp_error) sp_session_preferred_bitrate(sp_session *session, sp_bitrate bitrate);
+
+
+/**
+ * Set preferred bitrate for offline sync
+ *
+ * @param[in]  session        Session object
+ * @param[in]  bitrate        Preferred bitrate, see ::sp_bitrate for possible values
+ * @param[in]  allow_resync   Set to true if libspotify should resynchronize already synchronized tracks. Usually you should set this to false.
+ * @return                   One of the following errors, from ::sp_error
+ *                           SP_ERROR_OK
+ *                           SP_ERROR_INVALID_ARGUMENT
+ */
+SP_LIBEXPORT(sp_error) sp_session_preferred_offline_bitrate(sp_session *session, sp_bitrate bitrate, bool allow_resync);
+
+
+/**
+ * Return status of volume normalization
+ *
+ * @param[in]  session        Session object
+ *
+ * @return true iff volume normalization is enabled
+ *
+ */
+SP_LIBEXPORT(bool) sp_session_get_volume_normalization(sp_session *session);
+
+
+/**
+ * Set volume normalization
+ *
+ * @param[in]  session        Session object
+ * @param[in]  on             True iff volume normalization should be enabled
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_volume_normalization(sp_session *session, bool on);
+
+
+/**
+ * Set if private session is enabled. This disables sharing what the user is listening to
+ * to services such as Spotify Social, Facebook and LastFM. The private session will
+ * last for a time, and then libspotify will revert to the normal state. The private
+ * session is prolonged by user activity.
+ *
+ * @param[in]  session         Session object
+ * @param[in]  enabled         True iff private session should be enabled
+ * @return                     One of the following errors, from ::sp_error
+ *                             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_private_session(sp_session *session, bool enabled);
+
+/**
+ * Return True if private session is enabled
+ *
+ * @param[in]  session         Session object
+ *
+ * @return     True if private session is enabled
+ */
+SP_LIBEXPORT(bool) sp_session_is_private_session(sp_session *session);
+
+/**
+ * Set if scrobbling is enabled. This api allows setting local overrides of the global scrobbling settings.
+ * Changing the global settings are currently not supported.
+ *
+ * @param[in]  session         Session object
+ * @param[in]  provider        The scrobbling provider referred to
+ * @param[in]  state           The state to set the provider to
+ *
+ * @return     error code
+ *
+ * @see sp_social_provider
+ * @see sp_scrobbling_state
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_scrobbling(sp_session *session, sp_social_provider provider, sp_scrobbling_state state);
+
+/**
+ * Return the scrobbling state. This makes it possible to find out if scrobbling is locally overrided or
+ * if the global setting is used.
+ *
+ * @param[in]  session         Session object
+ * @param[in]  provider        The scrobbling provider referred to
+ * @param[out] state           The output variable receiving the sp_scrobbling_state state
+ *
+ * @return     error code
+ */
+SP_LIBEXPORT(sp_error) sp_session_is_scrobbling(sp_session *session, sp_social_provider provider, sp_scrobbling_state* state);
+
+/**
+ * Return True if scrobbling settings should be shown to the user. Currently this setting is relevant
+ * only to the facebook provider.
+ * The returned value may be false if the user is not connected to facebook,
+ * or if the user has opted out from facebook social graph.
+ *
+ * @param[in]  session         Session object
+ * @param[in]  provider        The scrobbling provider referred to
+ * @param[out] out             True iff scrobbling is possible
+ *
+ * @return     error code
+ */
+  SP_LIBEXPORT(sp_error) sp_session_is_scrobbling_possible(sp_session *session, sp_social_provider provider, bool* out);
+
+/**
+ * Set the user's credentials with a social provider.
+ * Currently this is only relevant for LastFm
+ * Call sp_session_set_scrobbling to force an authentication attempt
+ * with the LastFm server. If authentication fails a scrobble_error callback will be
+ * sent.
+ *
+ * @param[in]  session         Session object
+ * @param[in]  provider        The scrobbling provider referred to
+ * @param[in]  username        The user name
+ * @param[in]  password        The password
+ *
+ * @return     error code
+
+ * @see sp_session_set_scrobbling
+ * @see sp_session_callbacks#scrobble_error
+ * @return                     One of the following errors, from ::sp_error
+ *                             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_social_credentials(sp_session *session, sp_social_provider provider, const char* username, const char* password);
+
+/**
+ * Set to true if the connection is currently routed over a roamed connectivity
+ *
+ * @param[in]  session        Session object
+ * @param[in]  type           Connection type
+ *
+ * @note       Used in conjunction with sp_session_set_connection_rules() to control
+ *             how libspotify should behave in respect to network activity and offline
+ *             synchronization.
+ * @see        sp_connection_type
+ * @return     One of the following errors, from ::sp_error
+ *             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_connection_type(sp_session *session, sp_connection_type type);
+
+
+/**
+ * Set rules for how libspotify connects to Spotify servers and synchronizes offline content
+ *
+ * @param[in]  session        Session object
+ * @param[in]  rules          Connection rules
+ *
+ * @note       Used in conjunction with sp_session_set_connection_type() to control
+ *             how libspotify should behave in respect to network activity and offline
+ *             synchronization.
+ * @see        sp_connection_rules
+ * @return     One of the following errors, from ::sp_error
+ *             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_session_set_connection_rules(sp_session *session, sp_connection_rules rules);
+
+
+
+/**
+ * Get total number of tracks that needs download before everything
+ * from all playlists that is marked for offline is fully synchronized
+ *
+ * @param[in]  session        Session object
+ *
+ * @return Number of tracks
+ */
+SP_LIBEXPORT(int) sp_offline_tracks_to_sync(sp_session *session);
+
+/**
+ * Return number of playlisys that is marked for offline synchronization
+ *
+ * @param[in]  session        Session object
+ *
+ * @return Number of playlists
+ */
+SP_LIBEXPORT(int) sp_offline_num_playlists(sp_session *session);
+
+/**
+ * Return offline synchronization status. When the internal status is
+ * updated the offline_status_updated() callback will be invoked.
+ *
+ * @param[in]  session        Session object
+ * @param[out] status         Status object that will be filled with info
+ *
+ * @return false if no synching is in progress (in which case the contents
+ *               of status is undefined)
+ *
+ */
+SP_LIBEXPORT(bool) sp_offline_sync_get_status(sp_session *session, sp_offline_sync_status *status);
+
+/**
+ * Return remaining time (in seconds) until the offline key store expires
+ * and the user is required to relogin
+ *
+ * @param[in]  session        Session object
+ * @return                    Seconds until expiration
+ *
+ */
+SP_LIBEXPORT(int) sp_offline_time_left(sp_session *session);
+
+/**
+ * Get currently logged in users country
+ * updated the offline_status_updated() callback will be invoked.
+ *
+ * @param[in]  session        Session object
+ *
+ * @return  Country encoded in an integer 'SE' = 'S' << 8 | 'E'
+ */
+SP_LIBEXPORT(int) sp_session_user_country(sp_session *session);
+
+
+/** @} */
+
+
+/**
+ * @defgroup link Links (Spotify URIs)
+ *
+ * These functions handle links to Spotify entities in a way that allows you to
+ * not care about the textual representation of the link.
+ * @{
+ */
+
+/**
+ * Link types
+ */
+typedef enum {
+  SP_LINKTYPE_INVALID  = 0, ///< Link type not valid - default until the library has parsed the link, or when parsing failed
+  SP_LINKTYPE_TRACK    = 1, ///< Link type is track
+  SP_LINKTYPE_ALBUM    = 2, ///< Link type is album
+  SP_LINKTYPE_ARTIST   = 3, ///< Link type is artist
+  SP_LINKTYPE_SEARCH   = 4, ///< Link type is search
+  SP_LINKTYPE_PLAYLIST = 5, ///< Link type is playlist
+  SP_LINKTYPE_PROFILE  = 6, ///< Link type is profile
+  SP_LINKTYPE_STARRED  = 7, ///< Link type is starred
+  SP_LINKTYPE_LOCALTRACK  = 8, ///< Link type is a local file
+  SP_LINKTYPE_IMAGE = 9, ///< Link type is an image
+} sp_linktype;
+
+/**
+ * Create a Spotify link given a string
+ *
+ * @param[in]   link       A string representation of a Spotify link
+ *
+ * @return                 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 sp_link_type()
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_string(const char *link);
+
+/**
+ * Generates a link object from a track
+ *
+ * @param[in]   track        A track object
+ * @param[in]   offset       Offset in track in ms.
+ *
+ * @return                   A link representing the track
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_track(sp_track *track, int offset);
+
+/**
+ * Create a link object from an album
+ *
+ * @param[in]   album      An album object
+ *
+ * @return                 A link representing the album
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_album(sp_album *album);
+
+/**
+ * Create an image link object from an album
+ *
+ * @param[in]   album      An album object
+ * @param[in]   size       The desired size of the image
+ *
+ * @return                 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 sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_album_cover(sp_album *album, sp_image_size size);
+
+/**
+ * Creates a link object from an artist
+ *
+ * @param[in]   artist     An artist object
+ *
+ * @return                 A link object representing the artist
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_artist(sp_artist *artist);
+
+/**
+ * Creates a link object pointing to an artist portrait
+ *
+ * @param[in]   artist     Artist browse object
+ * @param[in]   size       The desired size of the image
+ *
+ * @return                 A link object representing an image
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ * @see sp_artistbrowse_num_portraits()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_artist_portrait(sp_artist *artist, sp_image_size size);
+
+
+/**
+ * Creates a link object from an artist portrait
+ *
+ * @param[in]   arb        Artist browse object
+ * @param[in]   index      The index of the portrait. Should be in the interval [0, sp_artistbrowse_num_portraits() - 1]
+ *
+ * @return                 A link object representing an image
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ * @see 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_LIBEXPORT(sp_link *) sp_link_create_from_artistbrowse_portrait(sp_artistbrowse *arb, int index);
+
+
+/**
+ * Generate a link object representing the current search
+ *
+ * @param[in]  search       Search object
+ *
+ * @return                  A link representing the search
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_search(sp_search *search);
+
+/**
+ * Create a link object representing the given playlist
+ *
+ * @param[in]  playlist       Playlist object
+ *
+ * @return                    A link representing the playlist
+ *
+ * @note You need to release the link when you are done with it.
+ * @see 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_LIBEXPORT(sp_link *) sp_link_create_from_playlist(sp_playlist *playlist);
+
+/**
+ * Create a link object representing the given playlist
+ *
+ * @param[in]  user       User object
+ *
+ * @return                    A link representing the profile.
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_user(sp_user *user);
+
+/**
+ * Create a link object representing the given image
+ *
+ * @param[in]  image          Image object
+ *
+ * @return                    A link representing the image.
+ *
+ * @note You need to release the link when you are done with it.
+ * @see sp_link_release()
+ */
+SP_LIBEXPORT(sp_link *) sp_link_create_from_image(sp_image *image);
+
+/**
+ * Create a string representation of the given Spotify link
+ *
+ * @param[in]   link         The Spotify link whose string representation you are interested in
+ * @param[out]  buffer       The buffer to hold the string representation of link
+ * @param[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
+ *
+ * @return                   The number of characters in the string representation of the link. If this
+ *                           value is greater or equal than \p buffer_size, output was truncated.
+ */
+SP_LIBEXPORT(int) sp_link_as_string(sp_link *link, char *buffer, int buffer_size);
+
+/**
+ * The link type of the specified link
+ *
+ * @param[in]   link       The Spotify link whose type you are interested in
+ *
+ * @return                 The link type of the specified link - see the sp_linktype enum for possible values
+ */
+SP_LIBEXPORT(sp_linktype) sp_link_type(sp_link *link);
+
+/**
+ * The track representation for the given link
+ *
+ * @param[in]   link       The Spotify link whose track you are interested in
+ *
+ * @return                 The track representation of the given track link
+ *                         If the link is not of track type then NULL is returned.
+ */
+SP_LIBEXPORT(sp_track *) sp_link_as_track(sp_link *link);
+
+/**
+ * The track and offset into track representation for the given link
+ *
+ * @param[in]   link       The Spotify link whose track you are interested in
+ * @param[out]  offset     Pointer to offset into track (in milliseconds). If the link
+ *                         does not contain an offset this will be set to 0.
+ *
+ * @return                 The track representation of the given track link
+ *                         If the link is not of track type then NULL is returned.
+ */
+SP_LIBEXPORT(sp_track *) sp_link_as_track_and_offset(sp_link *link, int *offset);
+
+/**
+ * The album representation for the given link
+ *
+ * @param[in]   link       The Spotify link whose album you are interested in
+ *
+ * @return                 The album representation of the given album link
+ *                         If the link is not of album type then NULL is returned
+ */
+SP_LIBEXPORT(sp_album *) sp_link_as_album(sp_link *link);
+
+/**
+ * The artist representation for the given link
+ *
+ * @param[in]   link       The Spotify link whose artist you are interested in
+ *
+ * @return                 The artist representation of the given link
+ *                         If the link is not of artist type then NULL is returned
+ */
+SP_LIBEXPORT(sp_artist *) sp_link_as_artist(sp_link *link);
+
+
+/**
+ * The user representation for the given link
+ *
+ * @param[in]   link       The Spotify link whose user you are interested in
+ *
+ * @return                 The user representation of the given link
+ *                         If the link is not of user type then NULL is returned
+ */
+SP_LIBEXPORT(sp_user *) sp_link_as_user(sp_link *link);
+
+
+/**
+ * Increase the reference count of a link
+ *
+ * @param[in]   link       The link object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_link_add_ref(sp_link *link);
+
+/**
+ * Decrease the reference count of a link
+ *
+ * @param[in]   link       The link object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_link_release(sp_link *link);
+
+/** @} */
+
+
+
+/**
+ * @defgroup track Track subsystem
+ * @{
+ */
+
+/**
+ * Return whether or not the track metadata is loaded.
+ *
+ * @param[in]   track      The track
+ *
+ * @return                 True if track is loaded
+ *
+ * @note  This is equivalent to checking if sp_track_error() not returns SP_ERROR_IS_LOADING.
+ */
+SP_LIBEXPORT(bool) sp_track_is_loaded(sp_track *track);
+
+/**
+ * Return an error code associated with a track. For example if it could not load
+ *
+ * @param[in]   track      The track
+ *
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ *                         SP_ERROR_IS_LOADING
+ *                         SP_ERROR_OTHER_PERMANENT
+ */
+SP_LIBEXPORT(sp_error) sp_track_error(sp_track *track);
+
+
+/**
+ * Return offline status for a track. sp_session_callbacks::metadata_updated() will be invoked when
+ * offline status of a track changes
+ *
+ * @param[in]   track      The track
+ *
+ * @return                 Stats as described by ::sp_track_offline_status
+ *
+ */
+SP_LIBEXPORT(sp_track_offline_status) sp_track_offline_get_status(sp_track *track);
+
+/**
+ * Return availability for a track
+ *
+ * @param[in]   session    Session
+ * @param[in]   track      The track
+ *
+ * @return                 Availability status, see ::sp_track_availability
+ *
+ * @note The track must be loaded or this function will always SP_TRACK_AVAILABILITY_UNAVAILABLE
+ * @see sp_track_is_loaded()
+ */
+SP_LIBEXPORT(sp_track_availability) sp_track_get_availability(sp_session *session, sp_track *track);
+
+/**
+ * Return true if the track is a local file.
+ *
+ * @param[in]   session    Session
+ * @param[in]   track      The track
+ *
+ * @return                 True if track is a local file.
+ *
+ * @note The track must be loaded or this function will always return false.
+ * @see sp_track_is_loaded()
+ */
+SP_LIBEXPORT(bool) sp_track_is_local(sp_session *session, sp_track *track);
+
+/**
+ * Return true if the track is autolinked to another track.
+ *
+ * @param[in]   session    Session
+ * @param[in]   track      The track
+ *
+ * @return                 True if track is autolinked.
+ *
+ * @note The track must be loaded or this function will always return false.
+ * @see sp_track_is_loaded()
+ */
+SP_LIBEXPORT(bool) sp_track_is_autolinked(sp_session *session, sp_track *track);
+
+
+/**
+ * Return the actual track that will be played if the given track is played
+ *
+ * @param[in]   session    Session
+ * @param[in]   track      The track
+ *
+ * @return                 A track
+ *
+ */
+SP_LIBEXPORT(sp_track *) sp_track_get_playable(sp_session *session, sp_track *track);
+
+/**
+ * Return true if the track is a placeholder. Placeholder tracks are used
+ * to store other objects than tracks in the playlist. Currently this is
+ * used in the inbox to store artists, albums and playlists.
+ *
+ * Use sp_link_create_from_track() to get a link object that points
+ * to the real object this "track" points to.
+ *
+ * @param[in]   track      The track
+ *
+ * @return                 True if track is a placeholder
+ *
+ * @note Contrary to most functions the track does not have to be
+ *       loaded for this function to return correct value
+ */
+SP_LIBEXPORT(bool) sp_track_is_placeholder(sp_track *track);
+
+
+/**
+ * Return true if the track is starred by the currently logged in user.
+ *
+ * @param[in]   session    Session
+ * @param[in]   track      The track
+ *
+ * @return                 True if track is starred.
+ *
+ * @note The track must be loaded or this function will always return false.
+ * @see sp_track_is_loaded()
+ */
+SP_LIBEXPORT(bool) sp_track_is_starred(sp_session *session, sp_track *track);
+
+/**
+ * Star/Unstar the specified track
+ *
+ * @param[in]   session    Session
+ * @param[in]   tracks     Array of pointer to tracks.
+ * @param[in]   num_tracks Length of \p tracks array
+ * @param[in]   star       Starred status of the track
+ *
+ * @note This will fail silently if playlists are disabled.
+ * @see sp_set_playlists_enabled()
+ */
+SP_LIBEXPORT(sp_error) sp_track_set_starred(sp_session *session, sp_track *const*tracks, int num_tracks, bool star);
+
+/**
+ * The number of artists performing on the specified track
+ *
+ * @param[in]   track     The track whose number of participating artists you are interested in
+ *
+ * @return                The number of artists performing on the specified track.
+ *                        If no metadata is available for the track yet, this function returns 0.
+ */
+SP_LIBEXPORT(int) sp_track_num_artists(sp_track *track);
+
+/**
+ * The artist matching the specified index performing on the current track.
+ *
+ * @param[in]   track      The track whose participating artist you are interested in
+ * @param[in]   index      The index for the participating artist. Should be in the interval [0, sp_track_num_artists() - 1]
+ *
+ * @return                 The participating artist, or NULL if invalid index
+ */
+SP_LIBEXPORT(sp_artist *) sp_track_artist(sp_track *track, int index);
+
+/**
+ * The album of the specified track
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 The album of the given track. You need to increase the refcount
+ *                         if you want to keep the pointer around.
+ *                         If no metadata is available for the track yet, this function returns 0.
+ */
+SP_LIBEXPORT(sp_album *) sp_track_album(sp_track *track);
+
+/**
+ * The string representation of the specified track's name
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 The string representation of the specified track's name.
+ *                         Returned string is valid as long as the album object stays allocated
+ *                         and no longer than the next call to sp_session_process_events()
+ *                         If no metadata is available for the track yet, this function returns empty string.
+ */
+SP_LIBEXPORT(const char *) sp_track_name(sp_track *track);
+
+/**
+ * The duration, in milliseconds, of the specified track
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 The duration of the specified track, in milliseconds
+ *                         If no metadata is available for the track yet, this function returns 0.
+ */
+SP_LIBEXPORT(int) sp_track_duration(sp_track *track);
+
+/**
+ * Returns popularity for track
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 Popularity in range 0 to 100, 0 if undefined.
+ *                         If no metadata is available for the track yet, this function returns 0.
+ */
+SP_LIBEXPORT(int) sp_track_popularity(sp_track *track);
+
+/**
+ * Returns the disc number for a track
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 Disc index. Possible values are [1, total number of discs on album]
+ *                         This function returns valid data only for tracks appearing in a browse
+ *                         artist or browse album result (otherwise returns 0).
+ */
+SP_LIBEXPORT(int) sp_track_disc(sp_track *track);
+
+/**
+ * Returns the position of a track on its disc
+ *
+ * @param[in]   track      A track object
+ *
+ * @return                 Track position, starts at 1 (relative the corresponding disc)
+ *                         This function returns valid data only for tracks appearing in a browse
+ *                         artist or browse album result (otherwise returns 0).
+ */
+SP_LIBEXPORT(int) sp_track_index(sp_track *track);
+
+/**
+ * Returns the newly created local track
+ *
+ * @param[in]   artist     Name of the artist
+ * @param[in]   title      Song title
+ * @param[in]   album      Name of the album, or an empty string if not available
+ * @param[in]   length      Length in MS, or -1 if not available.
+ *
+ * @return                 A track.
+ */
+SP_LIBEXPORT(sp_track *) sp_localtrack_create(const char *artist, const char *title, const char *album, int length);
+
+/**
+ * Increase the reference count of a track
+ *
+ * @param[in]   track       The track object
+ * @return                  One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_track_add_ref(sp_track *track);
+
+/**
+ * Decrease the reference count of a track
+ *
+ * @param[in]   track       The track object
+ * @return                  One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_track_release(sp_track *track);
+
+/** @} */
+
+
+
+/**
+ * @defgroup album Album subsystem
+ * @{
+ */
+
+/**
+ * Album types
+ */
+typedef enum {
+  SP_ALBUMTYPE_ALBUM       = 0, ///< Normal album
+  SP_ALBUMTYPE_SINGLE      = 1, ///< Single
+  SP_ALBUMTYPE_COMPILATION = 2, ///< Compilation
+  SP_ALBUMTYPE_UNKNOWN     = 3, ///< Unknown type
+} sp_albumtype;
+
+/**
+ * Check if the album object is populated with data
+ *
+ * @param[in]  album       Album object
+ * @return True if metadata is present, false if not
+ */
+SP_LIBEXPORT(bool) sp_album_is_loaded(sp_album *album);
+
+
+/**
+ * Return true if the album is available in the current region.
+ *
+ * @param[in]   album      The album
+ *
+ * @return                 True if album is available for playback, otherwise false.
+ *
+ * @note The album must be loaded or this function will always return false.
+ * @see sp_album_is_loaded()
+ */
+SP_LIBEXPORT(bool) sp_album_is_available(sp_album *album);
+
+/**
+ * Get the artist associated with the given album
+ *
+ * @param[in]  album       Album object
+ * @return A reference to the artist. NULL if the metadata has not been loaded yet
+ */
+SP_LIBEXPORT(sp_artist *) sp_album_artist(sp_album *album);
+
+/**
+ * Return image ID representing the album's coverart.
+ *
+ * @param[in]   album      Album object
+ * @param[in]   size       The desired size of the image
+ *
+ * @return                 ID byte sequence that can be passed to sp_image_create()
+ *                         If the album has no image or the metadata for the album is not
+ *                         loaded yet, this function returns NULL.
+ *
+ * @see sp_image_create
+ */
+SP_LIBEXPORT(const byte *) sp_album_cover(sp_album *album, sp_image_size size);
+
+/**
+ * Return name of album
+ *
+ * @param[in]   album      Album object
+ *
+ * @return                 Name of album.
+ *                         Returned string is valid as long as the album object stays allocated
+ *                         and no longer than the next call to sp_session_process_events()
+ */
+SP_LIBEXPORT(const char *) sp_album_name(sp_album *album);
+
+/**
+ * Return release year of specified album
+ *
+ * @param[in]   album      Album object
+ *
+ * @return                 Release year
+ */
+SP_LIBEXPORT(int) sp_album_year(sp_album *album);
+
+
+/**
+ * Return type of specified album
+ *
+ * @param[in]   album      Album object
+ *
+ * @return                 sp_albumtype
+ */
+SP_LIBEXPORT(sp_albumtype) sp_album_type(sp_album *album);
+
+
+/**
+ * Increase the reference count of an album
+ *
+ * @param[in]   album       The album object
+ * @return                  One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_album_add_ref(sp_album *album);
+
+/**
+ * Decrease the reference count of an album
+ *
+ * @param[in]   album       The album object
+ * @return                  One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_album_release(sp_album *album);
+
+/** @} */
+
+
+
+/**
+ * @defgroup artist Artist subsystem
+ * @{
+ */
+
+/**
+ * Return name of artist
+ *
+ * @param[in]   artist     Artist object
+ *
+ * @return                 Name of artist.
+ *                         Returned string is valid as long as the artist object stays allocated
+ *                         and no longer than the next call to sp_session_process_events()
+ */
+SP_LIBEXPORT(const char *) sp_artist_name(sp_artist *artist);
+
+/**
+ * Check if the artist object is populated with data
+ *
+ * @param[in]   artist     An artist object
+ *
+ * @return                 True if metadata is present, false if not
+ *
+ */
+SP_LIBEXPORT(bool) sp_artist_is_loaded(sp_artist *artist);
+
+/**
+ * Return portrait for artist
+ *
+ * @param[in]   artist     The artist object
+ * @param[in]   size       The desired size of the image
+ *
+ * @return                 ID byte sequence that can be passed to sp_image_create()
+ *                         If the artist has no image or the metadata for the album is not
+ *                         loaded yet, this function returns NULL.
+ *
+ */
+SP_LIBEXPORT(const byte *) sp_artist_portrait(sp_artist *artist, sp_image_size size);
+
+/**
+ * Increase the reference count of a artist
+ *
+ * @param[in]   artist       The artist object
+ * @return                   One of the following errors, from ::sp_error
+ *                           SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_artist_add_ref(sp_artist *artist);
+
+/**
+ * Decrease the reference count of a artist
+ *
+ * @param[in]   artist       The artist object
+ * @return                   One of the following errors, from ::sp_error
+ *                           SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_artist_release(sp_artist *artist);
+
+/** @} */
+
+
+/**
+ * @defgroup albumbrowse Album browsing
+ *
+ * Browsing adds additional information to what an ::sp_album holds. It retrieves
+ * copyrights, reviews and tracks of the album.
+ *
+ * @{
+ */
+
+/**
+ * The type of a callback used in sp_albumbrowse_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 ::sp_artist of the
+ * album will also have been fully loaded.
+ *
+ * @param[in]   result          The same pointer returned by sp_albumbrowse_create()
+ * @param[in]   userdata        The opaque pointer given to sp_albumbrowse_create()
+ */
+typedef void SP_CALLCONV albumbrowse_complete_cb(sp_albumbrowse *result, void *userdata);
+
+/**
+ * Initiate a request for browsing an album
+ *
+ * The user is responsible for freeing the returned album browse using sp_albumbrowse_release(). This can be done in the callback.
+ *
+ * @param[in]   session         Session object
+ * @param[in]   album           Album to be browsed. The album metadata does not have to be loaded
+ * @param[in]   callback        Callback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
+ * @param[in]   userdata        Userdata passed to callback.
+ *
+ * @return                      Album browse object
+ *
+ * @see ::albumbrowse_complete_cb
+ */
+SP_LIBEXPORT(sp_albumbrowse *) sp_albumbrowse_create(sp_session *session, sp_album *album, albumbrowse_complete_cb *callback, void *userdata);
+
+/**
+ * Check if an album browse request is completed
+ *
+ * @param[in]   alb        Album browse object
+ *
+ * @return                 True if browsing is completed, false if not
+ */
+SP_LIBEXPORT(bool) sp_albumbrowse_is_loaded(sp_albumbrowse *alb);
+
+
+/**
+* Check if browsing returned an error code.
+*
+* @param[in]   alb        Album browse object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_IS_LOADING
+*                         SP_ERROR_OTHER_PERMANENT
+*                         SP_ERROR_OTHER_TRANSIENT
+*/
+SP_LIBEXPORT(sp_error) sp_albumbrowse_error(sp_albumbrowse *alb);
+
+/**
+ * Given an album browse object, return the pointer to its album object
+ *
+ * @param[in]   alb        Album browse object
+ *
+ * @return                 Album object
+ */
+SP_LIBEXPORT(sp_album *) sp_albumbrowse_album(sp_albumbrowse *alb);
+
+/**
+ * Given an album browse object, return the pointer to its artist object
+ *
+ * @param[in]   alb        Album browse object
+ *
+ * @return                 Artist object
+ */
+SP_LIBEXPORT(sp_artist *) sp_albumbrowse_artist(sp_albumbrowse *alb);
+
+/**
+ * Given an album browse object, return number of copyright strings
+ *
+ * @param[in]   alb        Album browse object
+ *
+ * @return                 Number of copyright strings available, 0 if unknown
+ */
+SP_LIBEXPORT(int) sp_albumbrowse_num_copyrights(sp_albumbrowse *alb);
+
+/**
+ * Given an album browse object, return one of its copyright strings
+ *
+ * @param[in]   alb           Album browse object
+ * @param[in]   index         The index for the copyright string. Should be in the interval [0, sp_albumbrowse_num_copyrights() - 1]
+ *
+ * @return                    Copyright string in UTF-8 format, or NULL if the index is invalid.
+ *                            Returned string is valid as long as the album object stays allocated
+ *                            and no longer than the next call to sp_session_process_events()
+ */
+SP_LIBEXPORT(const char *) sp_albumbrowse_copyright(sp_albumbrowse *alb, int index);
+
+/**
+ * Given an album browse object, return number of tracks
+ *
+ * @param[in]   alb         Album browse object
+ *
+ * @return                  Number of tracks on album
+ */
+SP_LIBEXPORT(int) sp_albumbrowse_num_tracks(sp_albumbrowse *alb);
+
+/**
+ * Given an album browse object, return a pointer to one of its tracks
+ *
+ * @param[in]   alb        Album browse object
+ * @param[in]   index      The index for the track. Should be in the interval [0, sp_albumbrowse_num_tracks() - 1]
+ *
+ * @return                 A track.
+ *
+ * @see track
+ */
+SP_LIBEXPORT(sp_track *) sp_albumbrowse_track(sp_albumbrowse *alb, int index);
+
+/**
+ * Given an album browse object, return its review
+ *
+ * @param[in]   alb        Album browse object
+ *
+ * @return                 Review string in UTF-8 format.
+ *                         Returned string is valid as long as the album object stays allocated
+ *                         and no longer than the next call to sp_session_process_events()
+ */
+SP_LIBEXPORT(const char *) sp_albumbrowse_review(sp_albumbrowse *alb);
+
+/**
+ * Return the time (in ms) that was spent waiting for the Spotify backend to serve the request
+ *
+ * @param[in] alb         Album browse object
+ *
+ * @return                -1 if the request was served from the local cache
+ *                        If the result is not yet loaded the return value is undefined
+ */
+SP_LIBEXPORT(int) sp_albumbrowse_backend_request_duration(sp_albumbrowse *alb);
+
+
+/**
+ * Increase the reference count of an album browse result
+ *
+ * @param[in]   alb       The album browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_albumbrowse_add_ref(sp_albumbrowse *alb);
+
+/**
+ * Decrease the reference count of an album browse result
+ *
+ * @param[in]   alb       The album browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_albumbrowse_release(sp_albumbrowse *alb);
+
+/** @} */
+
+
+/**
+ * @defgroup artistbrowse Artist browsing
+ *
+ * Artist browsing initiates the fetching of information for a certain artist.
+ *
+ * @note   There is currently no built-in functionality available for getting the albums belonging
+ *         to an artist. For now, just iterate over all tracks and note the album to build a list of all albums.
+ *         This feature will be added in a future version of the library.
+ *
+ * @{
+ */
+
+/**
+ * The type of a callback used in sp_artistbrowse_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 artist data.
+ *
+ * @param[in]   result          The same pointer returned by sp_artistbrowse_create()
+ * @param[in]   userdata        The opaque pointer given to sp_artistbrowse_create()
+ */
+typedef void SP_CALLCONV artistbrowse_complete_cb(sp_artistbrowse *result, void *userdata);
+
+/**
+ * Initiate a request for browsing an artist
+ *
+ * The user is responsible for freeing the returned artist browse using sp_artistbrowse_release(). This can be done in the callback.
+ *
+ * @param[in] session         Session object
+ * @param[in] artist          Artist to be browsed. The artist metadata does not have to be loaded
+ * @param[in] type            Type of data requested, see the sp_artistbrowse_type enum for details
+ * @param[in] callback        Callback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
+ * @param[in] userdata        Userdata passed to callback.
+ *
+ * @return                    Artist browse object
+ *
+ * @see ::artistbrowse_complete_cb
+ */
+SP_LIBEXPORT(sp_artistbrowse *) sp_artistbrowse_create(sp_session *session, sp_artist *artist, sp_artistbrowse_type type, artistbrowse_complete_cb *callback, void *userdata);
+
+/**
+ * Check if an artist browse request is completed
+ *
+ * @param[in]   arb        Artist browse object
+ *
+ * @return                 True if browsing is completed, false if not
+ */
+SP_LIBEXPORT(bool) sp_artistbrowse_is_loaded(sp_artistbrowse *arb);
+
+/**
+* Check if browsing returned an error code.
+*
+* @param[in]   arb        Artist browse object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_IS_LOADING
+*                         SP_ERROR_OTHER_PERMANENT
+*                         SP_ERROR_OTHER_TRANSIENT
+*/
+SP_LIBEXPORT(sp_error) sp_artistbrowse_error(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return a pointer to its artist object
+ *
+ * @param[in]   arb        Artist browse object
+ *
+ * @return                 Artist object
+ */
+SP_LIBEXPORT(sp_artist *) sp_artistbrowse_artist(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return number of portraits available
+ *
+ * @param[in]   arb        Artist browse object
+ *
+ * @return                 Number of portraits for given artist
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_num_portraits(sp_artistbrowse *arb);
+
+/**
+ * Return image ID representing a portrait of the artist
+ *
+ * @param[in] arb             Artist object
+ * @param[in] index           The index of the portrait. Should be in the interval [0, sp_artistbrowse_num_portraits() - 1]
+ *
+ * @return                    ID byte sequence that can be passed to sp_image_create()
+ *
+ * @see sp_image_create
+ */
+SP_LIBEXPORT(const byte *) sp_artistbrowse_portrait(sp_artistbrowse *arb, int index);
+
+/**
+ * Given an artist browse object, return number of tracks
+ *
+ * @param[in] arb             Artist browse object
+ *
+ * @return                    Number of tracks for given artist
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_num_tracks(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return one of its tracks
+ *
+ * @param[in] arb             Album browse object
+ * @param[in] index           The index for the track. Should be in the interval [0, sp_artistbrowse_num_tracks() - 1]
+ *
+ * @return                    A track object, or NULL if the index is out of range.
+ *
+ * @see track
+ */
+SP_LIBEXPORT(sp_track *) sp_artistbrowse_track(sp_artistbrowse *arb, int index);
+
+
+/**
+ * Given an artist browse object, return number of tophit tracks
+ * This is a set of tracks for the artist with highest popularity
+ *
+ * @param[in] arb             Artist browse object
+ *
+ * @return                    Number of tophit tracks for given artist
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_num_tophit_tracks(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return one of its tophit tracks
+ * This is a set of tracks for the artist with highest popularity
+ *
+ * @param[in] arb             Album browse object
+ * @param[in] index           The index for the track. Should be in the interval [0, sp_artistbrowse_num_tophit_tracks() - 1]
+ *
+ * @return                    A track object, or NULL if the index is out of range.
+ *
+ * @see track
+ */
+SP_LIBEXPORT(sp_track *) sp_artistbrowse_tophit_track(sp_artistbrowse *arb, int index);
+
+/**
+ * Given an artist browse object, return number of albums
+ *
+ * @param[in] arb             Artist browse object
+ *
+ * @return                    Number of albums for given artist
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_num_albums(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return one of its albums
+ *
+ * @param[in] arb             Album browse object
+ * @param[in] index           The index for the album. Should be in the interval [0, sp_artistbrowse_num_albums() - 1]
+ *
+ * @return                    A album object, or NULL if the index is out of range.
+ *
+ * @see album
+ */
+SP_LIBEXPORT(sp_album *) sp_artistbrowse_album(sp_artistbrowse *arb, int index);
+
+/**
+ * Given an artist browse object, return number of similar artists
+ *
+ * @param[in] arb             Artist browse object
+ *
+ * @return                    Number of similar artists for given artist
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_num_similar_artists(sp_artistbrowse *arb);
+
+/**
+ * Given an artist browse object, return a similar artist by index
+ *
+ * @param[in] arb             Album browse object
+ * @param[in] index           The index for the artist. Should be in the interval [0, sp_artistbrowse_num_similar_artists() - 1]
+ *
+ * @return                    A pointer to an artist object.
+ *
+ * @see artist
+ */
+SP_LIBEXPORT(sp_artist *) sp_artistbrowse_similar_artist(sp_artistbrowse *arb, int index);
+
+/**
+ * Given an artist browse object, return the artists biography
+ *
+ * @note This function must be called from the same thread that did sp_session_create()
+ * @param[in] arb             Artist browse object
+ *
+ * @return                    Biography string in UTF-8 format.
+ *                            Returned string is valid as long as the album object stays allocated
+ *                            and no longer than the next call to sp_session_process_events()
+ */
+SP_LIBEXPORT(const char *) sp_artistbrowse_biography(sp_artistbrowse *arb);
+
+/**
+ * Return the time (in ms) that was spent waiting for the Spotify backend to serve the request
+ *
+ * @param[in] arb         Artist browse object
+ *
+ * @return                -1 if the request was served from the local cache
+ *                        If the result is not yet loaded the return value is undefined
+ */
+SP_LIBEXPORT(int) sp_artistbrowse_backend_request_duration(sp_artistbrowse *arb);
+
+
+/**
+ * Increase the reference count of an artist browse result
+ *
+ * @param[in]   arb       The artist browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_artistbrowse_add_ref(sp_artistbrowse *arb);
+
+/**
+ * Decrease the reference count of an artist browse result
+ *
+ * @param[in]   arb       The artist browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_artistbrowse_release(sp_artistbrowse *arb);
+
+/** @} */
+
+
+
+/**
+ * @defgroup image Image handling
+ * @{
+ */
+
+/**
+ * Image format
+ */
+typedef enum {
+  SP_IMAGE_FORMAT_UNKNOWN = -1, ///< Unknown image format
+  SP_IMAGE_FORMAT_JPEG   = 0,   ///< JPEG image
+} sp_imageformat;
+
+/**
+ * The type of a callback used to notify the application that an image
+ * is done loading.
+ */
+typedef void SP_CALLCONV image_loaded_cb(sp_image *image, void *userdata);
+
+/**
+ * Create an image object
+ *
+ * @param[in]  session    Session
+ * @param[in]  image_id   Spotify image ID
+ *
+ * @return                Pointer to an image object. To free the object, use
+ *                        sp_image_release()
+ *
+ * @see sp_album_cover
+ * @see sp_artistbrowse_portrait
+ */
+SP_LIBEXPORT(sp_image *) sp_image_create(sp_session *session, const byte image_id[20]);
+
+/**
+ * Create an image object from a link
+ *
+ * @param[in]  session    Session
+ * @param[in]  l          Spotify link object. This must be of SP_LINKTYPE_IMAGE type
+ *
+ * @return                Pointer to an image object. To free the object, use
+ *                        sp_image_release()
+ *
+ * @see sp_image_create
+ */
+SP_LIBEXPORT(sp_image *) sp_image_create_from_link(sp_session *session, sp_link *l);
+
+/**
+ * Add a callback that will be invoked when the image is loaded
+ *
+ * If an image is loaded, and loading fails, the image will behave like an
+ * empty image.
+ *
+ * @param[in]  image      Image object
+ * @param[in]  callback   Callback that will be called when image has been
+ *                        fetched.
+ * @param[in]  userdata   Opaque pointer passed to \p callback
+ *
+ */
+SP_LIBEXPORT(sp_error) sp_image_add_load_callback(sp_image *image, image_loaded_cb *callback, void *userdata);
+
+/**
+ * Remove an image load callback previously added with sp_image_add_load_callback()
+ *
+ * @param[in]  image      Image object
+ * @param[in]  callback   Callback that will not be called when image has been
+ *                        fetched.
+ * @param[in]  userdata   Opaque pointer passed to \p callback
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_image_remove_load_callback(sp_image *image, image_loaded_cb *callback, void *userdata);
+
+/**
+ * Check if an image is loaded. Before the image is loaded, the rest of the
+ * methods will behave as if the image is empty.
+ *
+ * @param[in]  image      Image object
+ *
+ * @return                True if image is loaded, false otherwise
+ */
+SP_LIBEXPORT(bool) sp_image_is_loaded(sp_image *image);
+
+/**
+* Check if image retrieval returned an error code.
+*
+* @param[in]   image      Image object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_IS_LOADING
+*                         SP_ERROR_OTHER_PERMANENT
+*                         SP_ERROR_OTHER_TRANSIENT
+*/
+SP_LIBEXPORT(sp_error) sp_image_error(sp_image *image);
+
+/**
+ * Get image format
+ *
+ * @param[in]  image      Image object
+ *
+ * @return                Image format as described by sp_imageformat
+ */
+SP_LIBEXPORT(sp_imageformat) sp_image_format(sp_image *image);
+
+/**
+* Get image data
+*
+* @param[in]  image      Image object
+* @param[out] data_size  Size of raw image data
+*
+* @return                Pointer to raw image data
+*/
+
+SP_LIBEXPORT(const void *) sp_image_data(sp_image *image, size_t *data_size);
+
+/**
+ * Get image ID
+ *
+ * @param[in]  image      Image object
+ *
+ * @return                Image ID
+ */
+SP_LIBEXPORT(const byte *) sp_image_image_id(sp_image *image);
+
+
+/**
+ * Increase the reference count of an image
+ *
+ * @param[in]   image     The image object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_image_add_ref(sp_image *image);
+
+/**
+ * Decrease the reference count of an image
+ *
+ * @param[in]   image     The image object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_image_release(sp_image *image);
+
+/** @} */
+
+
+
+/**
+ * @defgroup search Search subsystem
+ * @{
+ */
+
+/**
+ * The type of a callback used in sp_search_create()
+ *
+ * When this callback is called, the sp_track_is_loaded(), sp_album_is_loaded(),
+ * and sp_artist_is_loaded() functions will return non-zero for the objects
+ * contained in the search result.
+ *
+ * @param[in]   result          The same pointer returned by sp_search_create()
+ * @param[in]   userdata        The opaque pointer given to sp_search_create()
+ */
+typedef void SP_CALLCONV search_complete_cb(sp_search *result, void *userdata);
+
+/**
+ * Create a search object from the given query
+ *
+ * @param[in]  session    Session
+ * @param[in]  query      Query search string, e.g. 'The Rolling Stones' or 'album:"The Black Album"'
+ * @param[in]  track_offset     The offset among the tracks of the result
+ * @param[in]  track_count      The number of tracks to ask for
+ * @param[in]  album_offset     The offset among the albums of the result
+ * @param[in]  album_count      The number of albums to ask for
+ * @param[in]  artist_offset    The offset among the artists of the result
+ * @param[in]  artist_count     The number of artists to ask for
+ * @param[in]  playlist_offset  The offset among the playlists of the result
+ * @param[in]  playlist_count   The number of playlists to ask for
+ * @param[in]  search_type      Type of search, can be used for suggest searches
+ * @param[in]  callback   Callback that will be called once the search operation is complete. Pass NULL if you are not interested in this event.
+ * @param[in]  userdata   Opaque pointer passed to \p callback
+ *
+ * @return                Pointer to a search object. To free the object, use sp_search_release()
+ */
+SP_LIBEXPORT(sp_search *) sp_search_create(sp_session *session, const char *query, int track_offset, int track_count, int album_offset, int album_count, int artist_offset, int artist_count, int playlist_offset, int playlist_count, sp_search_type search_type, search_complete_cb *callback, void *userdata);
+
+/**
+ * Get load status for the specified search. Before it is loaded, it will behave as an empty search result.
+ *
+ * @param[in]  search   Search object
+ *
+ * @return              True if search is loaded, otherwise false
+ */
+SP_LIBEXPORT(bool) sp_search_is_loaded(sp_search *search);
+
+/**
+* Check if search returned an error code.
+*
+* @param[in]   search     Search object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_IS_LOADING
+*                         SP_ERROR_OTHER_PERMANENT
+*                         SP_ERROR_OTHER_TRANSIENT
+*/
+SP_LIBEXPORT(sp_error) sp_search_error(sp_search *search);
+
+/**
+ * Get the number of tracks for the specified search
+ *
+ * @param[in]  search   Search object
+ *
+ * @return              The number of tracks for the specified search
+ */
+SP_LIBEXPORT(int) sp_search_num_tracks(sp_search *search);
+
+/**
+ * Return the track at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted track. Should be in the interval [0, sp_search_num_tracks() - 1]
+ *
+ * @return                The track at the given index in the given search object
+ */
+SP_LIBEXPORT(sp_track *) sp_search_track(sp_search *search, int index);
+
+/**
+ * Get the number of albums for the specified search
+ *
+ * @param[in]  search   Search object
+ *
+ * @return              The number of albums for the specified search
+ */
+SP_LIBEXPORT(int) sp_search_num_albums(sp_search *search);
+
+/**
+ * Return the album at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted album. Should be in the interval [0, sp_search_num_albums() - 1]
+ *
+ * @return                The album at the given index in the given search object
+ */
+SP_LIBEXPORT(sp_album *) sp_search_album(sp_search *search, int index);
+
+/**
+ * Get the number of playlists for the specified search
+ *
+ * @param[in]  search   Search object
+ *
+ * @return              The number of playlists for the specified search
+ */
+SP_LIBEXPORT(int) sp_search_num_playlists(sp_search *search);
+
+/**
+ * Load the playlist at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted playlist. Should be in the interval [0, sp_search_num_playlists() - 1]
+ *
+ * @return                A playlist object. This reference is owned by the caller and should be released with sp_playlist_release()
+ */
+SP_LIBEXPORT(sp_playlist *) sp_search_playlist(sp_search *search, int index);
+
+/**
+ * Return the playlist at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted playlist. Should be in the interval [0, sp_search_num_playlists() - 1]
+ *
+ * @return                The playlist name at the given index in the given search object
+ */
+SP_LIBEXPORT(const char *) sp_search_playlist_name(sp_search *search, int index);
+
+/**
+ * Return the uri of a playlist at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted playlist. Should be in the interval [0, sp_search_num_playlists() - 1]
+ *
+ * @return                The playlist uri at the given index in the given search object
+ */
+SP_LIBEXPORT(const char *) sp_search_playlist_uri(sp_search *search, int index);
+
+/**
+ * Return the image_uri of a playlist at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted playlist. Should be in the interval [0, sp_search_num_playlists() - 1]
+ *
+ * @return                The playlist image_uri at the given index in the given search object
+ */
+SP_LIBEXPORT(const char *) sp_search_playlist_image_uri(sp_search *search, int index);
+
+/**
+ * Get the number of artists for the specified search
+ *
+ * @param[in]  search   Search object
+ *
+ * @return              The number of artists for the specified search
+ */
+SP_LIBEXPORT(int) sp_search_num_artists(sp_search *search);
+
+/**
+ * Return the artist at the given index in the given search object
+ *
+ * @param[in]  search     Search object
+ * @param[in]  index      Index of the wanted artist. Should be in the interval [0, sp_search_num_artists() - 1]
+ *
+ * @return                The artist at the given index in the given search object
+ */
+SP_LIBEXPORT(sp_artist *) sp_search_artist(sp_search *search, int index);
+
+/**
+ * Return the search query for the given search object
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The search query for the given search object
+ */
+SP_LIBEXPORT(const char *) sp_search_query(sp_search *search);
+
+/**
+ * Return the "Did you mean" query for the given search object
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The "Did you mean" query for the given search object, or the empty string if no such info is available
+ */
+SP_LIBEXPORT(const char *) sp_search_did_you_mean(sp_search *search);
+
+/**
+ * Return the total number of tracks for the search query - regardless of the interval requested at creation.
+ * If this value is larger than the interval specified at creation of the search object, more search results are available.
+ * To fetch these, create a new search object with a new interval.
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The total number of tracks matching the original query
+ */
+SP_LIBEXPORT(int) sp_search_total_tracks(sp_search *search);
+
+/**
+ * Return the total number of albums for the search query - regardless of the interval requested at creation.
+ * If this value is larger than the interval specified at creation of the search object, more search results are available.
+ * To fetch these, create a new search object with a new interval.
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The total number of albums matching the original query
+ */
+SP_LIBEXPORT(int) sp_search_total_albums(sp_search *search);
+
+/**
+ * Return the total number of artists for the search query - regardless of the interval requested at creation.
+ * If this value is larger than the interval specified at creation of the search object, more search results are available.
+ * To fetch these, create a new search object with a new interval.
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The total number of artists matching the original query
+ */
+SP_LIBEXPORT(int) sp_search_total_artists(sp_search *search);
+
+/**
+ * Return the total number of playlists for the search query - regardless of the interval requested at creation.
+ * If this value is larger than the interval specified at creation of the search object, more search results are available.
+ * To fetch these, create a new search object with a new interval.
+ *
+ * @param[in]  search     Search object
+ *
+ * @return                The total number of playlists matching the original query
+ */
+SP_LIBEXPORT(int) sp_search_total_playlists(sp_search *search);
+
+/**
+ * Increase the reference count of a search result
+ *
+ * @param[in]   search    The search result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_search_add_ref(sp_search *search);
+
+/**
+ * Decrease the reference count of a search result
+ *
+ * @param[in]   search    The search result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_search_release(sp_search *search);
+
+/** @} */
+
+
+
+
+/**
+ * @defgroup playlist Playlist subsystem
+ *
+ * The playlist subsystem handles playlists and playlist containers (list of playlists).
+ *
+ * The playlist container functions are always valid, but your playlists are not
+ * guaranteed to be loaded until the sp_session_callbacks#logged_in callback has
+ * been issued.
+ *
+ * @{
+ */
+
+/**
+ * Playlist callbacks
+ *
+ * Used to get notifications when playlists are updated.
+ * If some callbacks should not be of interest, set them to NULL.
+ */
+typedef struct sp_playlist_callbacks {
+
+  /**
+   * Called when one or more tracks have been added to a playlist
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  tracks     Array of pointers to track objects
+   * @param[in]  num_tracks Number of entries in \p tracks
+   * @param[in]  position   Position in the playlist for the first track.
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *tracks_added)(sp_playlist *pl, sp_track * const *tracks, int num_tracks, int position, void *userdata);
+
+  /**
+   * Called when one or more tracks have been removed from a playlist
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  tracks     Array of positions representing the tracks that were removed
+   * @param[in]  num_tracks Number of entries in \p tracks
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *tracks_removed)(sp_playlist *pl, const int *tracks, int num_tracks, void *userdata);
+
+  /**
+   * Called when one or more tracks have been moved within a playlist
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  tracks     Array of positions representing the tracks that were moved
+   * @param[in]  num_tracks Number of entries in \p tracks
+   * @param[in]  position   New position in the playlist for the first track.
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *tracks_moved)(sp_playlist *pl, const int *tracks, int num_tracks, int new_position, void *userdata);
+
+  /**
+   * Called when a playlist has been renamed. sp_playlist_name() can be used to find out the new name
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_renamed)(sp_playlist *pl, void *userdata);
+
+  /**
+   * Called when state changed for a playlist.
+   *
+   * There are three states that trigger this callback:
+   * - Collaboration for this playlist has been turned on or off
+   * - The playlist started having pending changes, or all pending changes have now been committed
+   * - The playlist started loading, or finished loading
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   * @sa sp_playlist_is_collaborative
+   * @sa sp_playlist_has_pending_changes
+   * @sa sp_playlist_is_loaded
+   */
+  void (SP_CALLCONV *playlist_state_changed)(sp_playlist *pl, void *userdata);
+
+  /**
+   * Called when a playlist is updating or is done updating
+   *
+   * This is called before and after a series of changes are applied to the
+   * playlist. It allows e.g. the user interface to defer updating until the
+   * entire operation is complete.
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  done       True iff the update is completed
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_update_in_progress)(sp_playlist *pl, bool done, void *userdata);
+
+  /**
+   * Called when metadata for one or more tracks in a playlist has been updated.
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_metadata_updated)(sp_playlist *pl, void *userdata);
+
+  /**
+   * Called when create time and/or creator for a playlist entry changes
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  position   Position in playlist
+   * @param[in]  user       User object
+   * @param[in]  time       When entry was created, seconds since the unix epoch.
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *track_created_changed)(sp_playlist *pl, int position, sp_user *user, int when, void *userdata);
+
+  /**
+   * Called when seen attribute for a playlist entry changes.
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  position   Position in playlist
+   * @param[in]  seen       Set if entry it marked as seen
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *track_seen_changed)(sp_playlist *pl, int position, bool seen, void *userdata);
+
+  /**
+   * Called when playlist description has changed
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  desc       New description
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *description_changed)(sp_playlist *pl, const char *desc, void *userdata);
+
+
+  /**
+   * Called when playlist image has changed
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  image      New image
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *image_changed)(sp_playlist *pl, const byte *image, void *userdata);
+
+
+  /**
+   * Called when message attribute for a playlist entry changes.
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  position   Position in playlist
+   * @param[in]  message    UTF-8 encoded message
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *track_message_changed)(sp_playlist *pl, int position, const char *message, void *userdata);
+
+
+  /**
+   * Called when playlist subscribers changes (count or list of names)
+   *
+   * @param[in]  pl         Playlist object
+   * @param[in]  userdata   Userdata passed to sp_playlist_add_callbacks()
+   */
+  void (SP_CALLCONV *subscribers_changed)(sp_playlist *pl, void *userdata);
+
+} sp_playlist_callbacks;
+
+
+/**
+ * Get load status for the specified playlist. If it's false, you have to wait until
+ * playlist_state_changed happens, and check again if is_loaded has changed
+ *
+ * @param[in]  playlist   Playlist object
+ *
+ * @return                True if playlist is loaded, otherwise false
+ */
+SP_LIBEXPORT(bool) sp_playlist_is_loaded(sp_playlist *playlist);
+
+/**
+ * Register interest in the given playlist
+ *
+ * Here is a snippet from \c jukebox.c:
+ * @dontinclude jukebox.c
+ * @skipline sp_playlist_add_callbacks
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  callbacks  Callbacks, see #sp_playlist_callbacks
+ * @param[in]  userdata   Userdata to be passed to callbacks
+ * @sa sp_playlist_remove_callbacks
+ *
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_add_callbacks(sp_playlist *playlist, sp_playlist_callbacks *callbacks, void *userdata);
+
+/**
+ * Unregister interest in the given playlist
+ *
+ * The combination of (\p callbacks, \p userdata) is used to find the entry to be removed
+ *
+ * Here is a snippet from \c jukebox.c:
+ * @dontinclude jukebox.c
+ * @skipline sp_playlist_remove_callbacks
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  callbacks  Callbacks, see #sp_playlist_callbacks
+ * @param[in]  userdata   Userdata to be passed to callbacks
+ * @sa sp_playlist_add_callbacks
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ *
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_remove_callbacks(sp_playlist *playlist, sp_playlist_callbacks *callbacks, void *userdata);
+
+/**
+ * Return number of tracks in the given playlist
+ *
+ * @param[in]  playlist   Playlist object
+ *
+ * @return                The number of tracks in the playlist
+ */
+SP_LIBEXPORT(int) sp_playlist_num_tracks(sp_playlist *playlist);
+
+/**
+ * Return the track at the given index in a playlist
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ *
+ * @return                The track at the given index
+ */
+SP_LIBEXPORT(sp_track *) sp_playlist_track(sp_playlist *playlist, int index);
+
+/**
+ * Return when the given index was added to the playlist
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ *
+ * @return                Time, Seconds since unix epoch.
+ */
+SP_LIBEXPORT(int) sp_playlist_track_create_time(sp_playlist *playlist, int index);
+
+/**
+ * Return user that added the given index in the playlist
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ *
+ * @return                User object
+ */
+SP_LIBEXPORT(sp_user *) sp_playlist_track_creator(sp_playlist *playlist, int index);
+
+/**
+ * Return if a playlist entry is marked as seen or not
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ *
+ * @return                Seen state
+ */
+SP_LIBEXPORT(bool) sp_playlist_track_seen(sp_playlist *playlist, int index);
+
+/**
+ * Set seen status of a playlist entry
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ * @param[in]  seen       Seen status to be set
+ *
+ * @return     error     One of the following errors, from ::sp_error
+ *                       SP_ERROR_OK
+ *                       SP_ERROR_INDEX_OUT_OF_RANGE
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_track_set_seen(sp_playlist *playlist, int index, bool seen);
+
+/**
+ * Return a message attached to a playlist item. Typically used on inbox.
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  index      Index into playlist container. Should be in the interval [0, sp_playlist_num_tracks() - 1]
+ *
+ * @return                UTF-8 encoded message, or NULL if no message is present
+ */
+SP_LIBEXPORT(const char *) sp_playlist_track_message(sp_playlist *playlist, int index);
+
+/**
+ * Return name of given playlist
+ *
+ * @param[in]  playlist   Playlist object
+ *
+ * @return                The name of the given playlist
+ */
+SP_LIBEXPORT(const char *) sp_playlist_name(sp_playlist *playlist);
+
+/**
+ * Rename the given playlist
+ * The name must not consist of only spaces and it must be shorter than 256 characters.
+ *
+ * @param[in]  playlist   Playlist object
+ * @param[in]  new_name   New name for playlist
+ *
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ *                        SP_ERROR_INVALID_INDATA
+ *                        SP_ERROR_PERMISSION_DENIED
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_rename(sp_playlist *playlist, const char *new_name);
+
+/**
+ * Return a pointer to the user for the given playlist
+ *
+ * @param[in]  playlist   Playlist object
+ *
+ * @return                User object
+ */
+SP_LIBEXPORT(sp_user *) sp_playlist_owner(sp_playlist *playlist);
+
+/**
+ * Return collaborative status for a playlist.
+ *
+ * A playlist in collaborative state can be modifed by all users, not only the user owning the list
+ *
+ * @param[in]  playlist   Playlist object
+ *
+ * @return                true if playlist is collaborative, otherwise false
+ */
+SP_LIBEXPORT(bool) sp_playlist_is_collaborative(sp_playlist *playlist);
+
+/**
+ * Set collaborative status for a playlist.
+ *
+ * A playlist in collaborative state can be modified by all users, not only the user owning the list
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[in]  collaborative  True or false
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_set_collaborative(sp_playlist *playlist, bool collaborative);
+
+/**
+ * Set autolinking state for a playlist.
+ *
+ * If a playlist is autolinked, unplayable tracks will be made playable
+ * by linking them to other Spotify tracks, where possible.
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[in]  link           True or false
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_set_autolink_tracks(sp_playlist *playlist, bool link);
+
+
+/**
+ * Get description for a playlist
+ *
+ * @param[in]  playlist       Playlist object
+ *
+ * @return                    Playlist description or NULL if unset
+ *
+ */
+SP_LIBEXPORT(const char *) sp_playlist_get_description(sp_playlist *playlist);
+
+
+/**
+ * Get description for a playlist
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[out] image          20 byte image id
+
+ * @return                    TRUE if playlist has an image, FALSE if not
+ *
+ */
+SP_LIBEXPORT(bool) sp_playlist_get_image(sp_playlist *playlist, byte image[20]);
+
+
+/**
+ * Check if a playlist has pending changes
+ *
+ * Pending changes are local changes that have not yet been acknowledged by the server.
+ *
+ * @param[in]  playlist       Playlist object
+ *
+ * @return                    A flag representing if there are pending changes or not
+ */
+SP_LIBEXPORT(bool) sp_playlist_has_pending_changes(sp_playlist *playlist);
+
+/**
+ * Add tracks to a playlist
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[in]  tracks         Array of pointer to tracks.
+ * @param[in]  num_tracks     Length of \p tracks array
+ * @param[in]  position       Start position in playlist where to insert the tracks
+ * @param[in]  session        Your session object
+ *
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ *                        SP_ERROR_INVALID_INDATA - position is > current playlist length
+ *                        SP_ERROR_PERMISSION_DENIED
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_add_tracks(sp_playlist *playlist, sp_track *const*tracks, int num_tracks, int position, sp_session *session);
+
+/**
+ * Remove tracks from a playlist
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[in]  tracks         Array of pointer to track indices.
+ *                            A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata,
+ *                            whereas [0, 1, 1] is invalid.
+ * @param[in]  num_tracks     Length of \p tracks array
+ *
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ *                            SP_ERROR_PERMISSION_DENIED
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_remove_tracks(sp_playlist *playlist, const int *tracks, int num_tracks);
+
+/**
+ * Move tracks in playlist
+ *
+ * @param[in]  playlist       Playlist object
+ * @param[in]  tracks         Array of pointer to track indices to be moved.
+ *                            A certain track index should be present at most once, e.g. [0, 1, 2] is valid indata,
+ *                            whereas [0, 1, 1] is invalid.
+ * @param[in]  num_tracks     Length of \p tracks array
+ * @param[in]  new_position   New position for tracks
+ *
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ *                            SP_ERROR_INVALID_INDATA - position is > current playlist length
+ *                            SP_ERROR_PERMISSION_DENIED
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_reorder_tracks(sp_playlist *playlist, const int *tracks, int num_tracks, int new_position);
+
+
+/**
+ * Return number of subscribers for a given playlist
+ *
+ * @param[in]  playlist       Playlist object
+ *
+ * @return     Number of subscribers
+ *
+ */
+SP_LIBEXPORT(unsigned int) sp_playlist_num_subscribers(sp_playlist *playlist);
+
+/**
+ * Return subscribers for a playlist
+ *
+ * @param[in]  playlist       Playlist object
+ *
+ * @return     sp_subscribers struct with array of canonical usernames.
+ *             This object should be free'd using sp_playlist_subscribers_free()
+ *
+ * @note       The count returned for this function may be less than those
+ *             returned by sp_playlist_num_subscribers(). Spotify does not
+ *             track each user subscribed to a playlist for playlist with
+ *             many (>500) subscribers.
+ */
+SP_LIBEXPORT(sp_subscribers *) sp_playlist_subscribers(sp_playlist *playlist);
+
+/**
+ * Free object returned from sp_playlist_subscribers()
+ *
+ * @param[in] subscribers   Subscribers object
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_subscribers_free(sp_subscribers *subscribers);
+
+/**
+ * Ask library to update the subscription count for a playlist
+ *
+ * When the subscription info has been fetched from the Spotify backend
+ * the playlist subscribers_changed() callback will be invoked.
+ * In that callback use sp_playlist_num_subscribers() and/or
+ * sp_playlist_subscribers() to get information about the subscribers.
+ * You can call those two functions anytime you want but the information
+ * might not be up to date in such cases
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_update_subscribers(sp_session *session, sp_playlist *playlist);
+
+/**
+ * Return whether a playlist is loaded in RAM (as opposed to only
+ * stored on disk)
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ *
+ * @return True iff playlist is in RAM, False otherwise
+ *
+ * @note       When a playlist is no longer in RAM it will appear empty.
+ *             However, libspotify will retain information about the
+ *             list metadata  (owner, title, picture, etc) in RAM.
+ *             There is one caveat tough: If libspotify has never seen the
+ *             playlist before this metadata will also be unset.
+ *             In order for libspotify to get the metadata the playlist
+ *             needs to be loaded at least once.
+ *             In order words, if libspotify starts with an empty playlist
+ *             cache and the application has set 'initially_unload_playlists'
+ *             config parameter to True all playlists will be empty.
+ *             It will not be possible to generate URI's to the playlists
+ *             nor extract playlist title until the application calls
+ *             sp_playlist_set_in_ram(..., true). So an application
+ *             that needs to stay within a low memory profile would need to
+ *             cycle thru all new playlists in order to extract metadata.
+ *
+ *             The easiest way to detect this case is when
+ *             sp_playlist_is_in_ram() returns false and
+ *             sp_link_create_from_playlist() returns NULL
+ */
+SP_LIBEXPORT(bool) sp_playlist_is_in_ram(sp_session *session, sp_playlist *playlist);
+
+/**
+ * Return whether a playlist is loaded in RAM (as opposed to only
+ * stored on disk)
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ * @param[in]  in_ram         Controls whether or not to keep the list in RAM
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_set_in_ram(sp_session *session, sp_playlist *playlist, bool in_ram);
+
+/**
+ * Load an already existing playlist without adding it to a playlistcontainer.
+ *
+ * @param[in]  session        Session object
+ * @param[in]  link           Link object referring to a playlist
+ *
+ * @return     A playlist. The reference is owned by the caller and should be released with sp_playlist_release()
+ *
+ */
+SP_LIBEXPORT(sp_playlist *) sp_playlist_create(sp_session *session, sp_link *link);
+
+/**
+ * Mark a playlist to be synchronized for offline playback.
+ * The playlist must be in the users playlistcontainer
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ * @param[in]  offline        True iff playlist should be offline, false otherwise
+ * @return                    One of the following errors, from ::sp_error
+ *                            SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_set_offline_mode(sp_session *session, sp_playlist *playlist, bool offline);
+
+/**
+ * Get offline status for a playlist
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ *
+ * @return sp_playlist_offline_status
+ *
+ * @see When in SP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING mode the
+ *      sp_playlist_get_offline_download_completed() method can be used to query
+ *      progress of the download
+ */
+SP_LIBEXPORT(sp_playlist_offline_status) sp_playlist_get_offline_status(sp_session *session, sp_playlist *playlist);
+
+/**
+ * Get download progress for an offline playlist
+ *
+ * @param[in]  session        Session object
+ * @param[in]  playlist       Playlist object
+ *
+ * @return Value from 0 - 100 that indicates amount of playlist that is downloaded
+ * or 0 if the playlist is not in the SP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING mode.
+ *
+ * @see sp_playlist_offline_status()
+ */
+SP_LIBEXPORT(int) sp_playlist_get_offline_download_completed(sp_session *session, sp_playlist *playlist);
+
+/**
+ * Increase the reference count of a playlist
+ *
+ * @param[in]   playlist       The playlist object
+ * @return                     One of the following errors, from ::sp_error
+ *                             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_add_ref(sp_playlist *playlist);
+
+/**
+ * Decrease the reference count of a playlist
+ *
+ * @param[in]   playlist       The playlist object
+ * @return                     One of the following errors, from ::sp_error
+ *                             SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlist_release(sp_playlist *playlist);
+
+
+/**
+ * Playlist container callbacks.
+ * If some callbacks should not be of interest, set them to NULL.
+ *
+ * @see sp_playlistcontainer_add_callbacks
+ * @see sp_playlistcontainer_remove_callbacks
+ */
+typedef struct sp_playlistcontainer_callbacks {
+  /**
+   * Called when a new playlist has been added to the playlist container.
+   *
+   * @param[in]  pc         Playlist container
+   * @param[in]  playlist   Playlist object.
+   * @param[in]  position   Position in list
+   * @param[in]  userdata   Userdata as set in sp_playlistcontainer_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_added)(sp_playlistcontainer *pc, sp_playlist *playlist, int position, void *userdata);
+
+
+  /**
+   * Called when a new playlist has been removed from playlist container
+   *
+   * @param[in]  pc         Playlist container
+   * @param[in]  playlist   Playlist object.
+   * @param[in]  position   Position in list
+   * @param[in]  userdata   Userdata as set in sp_playlistcontainer_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_removed)(sp_playlistcontainer *pc, sp_playlist *playlist, int position, void *userdata);
+
+
+  /**
+   * Called when a playlist has been moved in the playlist container
+   *
+   * @param[in]  pc         Playlist container
+   * @param[in]  playlist   Playlist object.
+   * @param[in]  position   Previous position in playlist container list
+   * @param[in]  new_position   New position in playlist container list
+   * @param[in]  userdata   Userdata as set in sp_playlistcontainer_add_callbacks()
+   */
+  void (SP_CALLCONV *playlist_moved)(sp_playlistcontainer *pc, sp_playlist *playlist, int position, int new_position, void *userdata);
+
+  /**
+   * Called when the playlist container is loaded
+   *
+   * @param[in]  pc         Playlist container
+   * @param[in]  userdata   Userdata as set in sp_playlistcontainer_add_callbacks()
+   */
+  void (SP_CALLCONV *container_loaded)(sp_playlistcontainer *pc, void *userdata);
+} sp_playlistcontainer_callbacks;
+
+
+/**
+ * Register interest in changes to a playlist container
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  callbacks Callbacks, see sp_playlistcontainer_callbacks
+ * @param[in]  userdata  Opaque value passed to callbacks.
+ *
+ * @note Every sp_playlistcontainer_add_callbacks() needs to be paired with a corresponding
+ *       sp_playlistcontainer_remove_callbacks() that is invoked before releasing the
+ *       last reference you own for the container. In other words, you must make sure
+ *       to have removed all the callbacks before the container gets destroyed.
+ *
+ * @sa sp_session_playlistcontainer()
+ * @sa sp_playlistcontainer_remove_callbacks
+ * @return              One of the following errors, from ::sp_error
+ *                      SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_add_callbacks(sp_playlistcontainer *pc, sp_playlistcontainer_callbacks *callbacks, void *userdata);
+
+
+/**
+ * Unregister interest in changes to a playlist container
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  callbacks Callbacks, see sp_playlistcontainer_callbacks
+ * @param[in]  userdata  Opaque value passed to callbacks.
+ *
+ * @sa sp_session_playlistcontainer()
+ * @sa sp_playlistcontainer_add_callbacks
+ * @return              One of the following errors, from ::sp_error
+ *                      SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_remove_callbacks(sp_playlistcontainer *pc, sp_playlistcontainer_callbacks *callbacks, void *userdata);
+
+/**
+ * Return the number of playlists in the given playlist container
+ *
+ * @param[in]  pc        Playlist container
+ *
+ * @return               Number of playlists, -1 if undefined
+ *
+ * @sa sp_session_playlistcontainer()
+ */
+SP_LIBEXPORT(int) sp_playlistcontainer_num_playlists(sp_playlistcontainer *pc);
+
+/**
+ * Return true if the playlistcontainer is fully loaded
+ *
+ * @param[in]  pc        Playlist container
+ *
+ * @return               True if container is loaded
+ *
+ * @note The container_loaded callback will be invoked when this flips to true
+ */
+SP_LIBEXPORT(bool) sp_playlistcontainer_is_loaded(sp_playlistcontainer *pc);
+
+/**
+ * Return a pointer to the playlist at a specific index
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  index     Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]
+ *
+ * @return               The playlist object
+ *
+ * @sa sp_session_playlistcontainer()
+ */
+SP_LIBEXPORT(sp_playlist *) sp_playlistcontainer_playlist(sp_playlistcontainer *pc, int index);
+
+/**
+ * Return the type of the playlist at a @a index
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  index     Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]
+ *
+ * @return               Type of the playlist, @see sp_playlist_type
+ *
+ * @sa sp_session_playlistcontainer()
+ */
+SP_LIBEXPORT(sp_playlist_type) sp_playlistcontainer_playlist_type(sp_playlistcontainer *pc, int index);
+
+/**
+ * Return the folder name at @a index
+ *
+ * @param[in]  pc           Playlist container
+ * @param[in]  index        Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1].
+ *                          Index should point at a start-folder entry, otherwise the empty string is written to buffer.
+ * @param[in]  buffer       Pointer to char[] where to store folder name
+ * @param[in]  buffer_size  Size of array
+ *
+ * @return                  One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ *                          SP_ERROR_INDEX_OUT_OF_RANGE
+ *
+ * @sa sp_session_playlistcontainer()
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_playlist_folder_name(sp_playlistcontainer *pc, int index, char *buffer, int buffer_size);
+
+/**
+ * Return the folder id at @a index
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  index     Index in playlist container. Should be in the interval [0, sp_playlistcontainer_num_playlists() - 1]
+ *
+ * @return               The group ID of the folder. Returns 0 on index out of range, pc being NULL or indexed item not being a folder
+ *
+ * @sa sp_session_playlistcontainer()
+ */
+SP_LIBEXPORT(sp_uint64) sp_playlistcontainer_playlist_folder_id(sp_playlistcontainer *pc, int index);
+
+/**
+ * Add an empty playlist at the end of the playlist container.
+ * The name must not consist of only spaces and it must be shorter than 256 characters.
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  name      Name of new playlist
+ *
+ * @return               Pointer to the new playlist. Can be NULL if the operation fails.
+ */
+SP_LIBEXPORT(sp_playlist *) sp_playlistcontainer_add_new_playlist(sp_playlistcontainer *pc, const char *name);
+
+/**
+ * Add an existing playlist at the end of the given playlist container
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  link      Link object pointing to a playlist
+ *
+ * @return               Pointer to the new playlist. Will be NULL if the playlist already exists.
+ */
+SP_LIBEXPORT(sp_playlist *) sp_playlistcontainer_add_playlist(sp_playlistcontainer *pc, sp_link *link);
+
+/**
+ * Remove playlist at index from the given playlist container
+ *
+ * @param[in]  pc        Playlist container
+ * @param[in]  index     Index of playlist to be removed
+ *
+ * @return     error     One of the following errors, from ::sp_error
+ *                       SP_ERROR_OK
+ *                       SP_ERROR_INDEX_OUT_OF_RANGE
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_remove_playlist(sp_playlistcontainer *pc, int index);
+
+/**
+ * Move a playlist in the playlist container
+ *
+ * @param[in]  pc           Playlist container
+ * @param[in]  index        Index of playlist to be moved
+ * @param[in]  new_position New position for the playlist
+ * @param[in]  dry_run      Do not execute the move, only check if it possible
+
+ * @return     error        One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ *                          SP_ERROR_INDEX_OUT_OF_RANGE
+ *                          SP_ERROR_INVALID_INDATA - If trying to move a folder into itself
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_move_playlist(sp_playlistcontainer *pc, int index, int new_position, bool dry_run);
+
+
+/**
+ * Add a playlist folder
+ *
+ * @param[in]  pc           Playlist container
+ * @param[in]  index        Position of SP_PLAYLIST_TYPE_START_FOLDER entry
+ * @param[in]  name         Name of group
+
+ * @return     error        One of the following errors, from ::sp_error
+ *                          SP_ERROR_OK
+ *                          SP_ERROR_INDEX_OUT_OF_RANGE
+ *
+ * @note This operation will actually create two playlists. One of
+ * type SP_PLAYLIST_TYPE_START_FOLDER and immediately following a
+ * SP_PLAYLIST_TYPE_END_FOLDER one.
+ *
+ * To remove a playlist folder both of these must be deleted or the list
+ * will be left in an inconsistant state.
+ *
+ * There is no way to rename a playlist folder. Instead you need to remove
+ * the folder and recreate it again.
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_add_folder(sp_playlistcontainer *pc, int index, const char *name);
+
+
+/**
+ * Return a pointer to the user object of the owner.
+ *
+ * @param[in]  pc   Playlist container.
+ * @return          The user object or NULL if unknown or none.
+ */
+SP_LIBEXPORT(sp_user *) sp_playlistcontainer_owner(sp_playlistcontainer *pc);
+
+
+/**
+ * Increase reference count on playlistconatiner object
+ *
+ * @param[in]  pc   Playlist container.
+ * @return          One of the following errors, from ::sp_error
+ *                  SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_add_ref(sp_playlistcontainer *pc);
+
+/**
+ * Release reference count on playlistconatiner object
+ *
+ * @param[in]  pc   Playlist container.
+ * @return          One of the following errors, from ::sp_error
+ *                  SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_playlistcontainer_release(sp_playlistcontainer *pc);
+
+/**
+ * Get the number of new tracks in a playlist since the corresponding
+ * function sp_playlistcontainer_clear_unseen_tracks() was called. The
+ * function always returns the number of new tracks, and fills the
+ * \p tracks array with the new tracks, but not more than specified in
+ * \p num_tracks. The function will return a negative value on failure.
+ *
+ * @param[in]  pc         Playlist container.
+ * @param[in]  playlist   Playlist object.
+ * @param[out] tracks     Array of pointer to new tracks (maybe NULL)
+ * @param[in]  num_tracks Size of tracks array
+ * @return     Returns the number of unseen tracks
+ */
+SP_LIBEXPORT(int) sp_playlistcontainer_get_unseen_tracks(sp_playlistcontainer *pc, sp_playlist *playlist, sp_track **tracks, int num_tracks);
+
+/**
+ * Clears a playlist from unseen tracks, so that next call to sp_playlistcontainer_get_unseen_tracks() will return 0 until a new track is added to the \p playslist.
+ *
+ * @param[in]  pc       Playlist container.
+ * @param[in]  playlist   Playlist object.
+ * @return     Returns 0 on success and -1 on failure.
+ */
+SP_LIBEXPORT(int) sp_playlistcontainer_clear_unseen_tracks(sp_playlistcontainer *pc, sp_playlist *playlist);
+
+/** @} */
+
+
+/**
+ * @defgroup user User handling
+ * @{
+ */
+
+
+/**
+ * User relation type
+ */
+typedef enum sp_relation_type {
+  SP_RELATION_TYPE_UNKNOWN = 0,          ///< Not yet known
+  SP_RELATION_TYPE_NONE = 1,             ///< No relation
+  SP_RELATION_TYPE_UNIDIRECTIONAL = 2,   ///< The currently logged in user is following this uer
+  SP_RELATION_TYPE_BIDIRECTIONAL = 3,    ///< Bidirectional friendship established
+} sp_relation_type;
+
+
+
+/**
+ * Get a pointer to a string representing the user's canonical username.
+ *
+ * @param[in]   user         The Spotify user whose canonical username you would like a string representation of
+ *
+ * @return                   A string representing the canonical username.
+ */
+SP_LIBEXPORT(const char *) sp_user_canonical_name(sp_user *user);
+
+/**
+ * Get a pointer to a string representing the user's displayable username.
+ * If there is no difference between the canonical username and the display name,
+ * or if the library does not know about the display name yet, the canonical username will
+ * be returned.
+ *
+ * @param[in]   user         The Spotify user whose displayable username you would like a string representation of
+ *
+ * @return                   A string
+ */
+SP_LIBEXPORT(const char *) sp_user_display_name(sp_user *user);
+
+/**
+ * Get load status for a user object. Before it is loaded, only the user's canonical username
+ * is known.
+ *
+ * @param[in]   user         Spotify user object
+ *
+ * @return                   True if user object is loaded, otherwise false
+ */
+SP_LIBEXPORT(bool) sp_user_is_loaded(sp_user *user);
+
+
+/**
+ * Increase the reference count of an user
+ *
+ * @param[in]   user       The user object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_user_add_ref(sp_user *user);
+
+/**
+ * Decrease the reference count of an user
+ *
+ * @param[in]   user       The user object
+ * @return                 One of the following errors, from ::sp_error
+ *                         SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_user_release(sp_user *user);
+
+/** @} */
+
+
+/**
+ * @defgroup toplist Toplist handling
+ * @{
+ */
+
+/**
+ * Toplist types
+ */
+typedef enum {
+  SP_TOPLIST_TYPE_ARTISTS = 0, ///< Top artists
+  SP_TOPLIST_TYPE_ALBUMS  = 1, ///< Top albums
+  SP_TOPLIST_TYPE_TRACKS  = 2, ///< Top tracks
+} sp_toplisttype;
+
+
+/**
+ * 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
+ */
+#define SP_TOPLIST_REGION(a, b) ((a) << 8 | (b))
+
+/**
+ * Special toplist regions
+ */
+typedef enum {
+  SP_TOPLIST_REGION_EVERYWHERE = 0, ///< Global toplist
+  SP_TOPLIST_REGION_USER = 1,       ///< Toplist for a given user
+} sp_toplistregion;
+
+
+/**
+ * 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.
+ *
+ * @param[in]   result          The same pointer returned by sp_toplistbrowse_create()
+ * @param[in]   userdata        The opaque pointer given to sp_toplistbrowse_create()
+ */
+typedef void SP_CALLCONV toplistbrowse_complete_cb(sp_toplistbrowse *result, 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.
+ *
+ * @param[in]   session         Session object
+ * @param[in]   type            Type of toplist to be browsed. see the sp_toplisttype enum for possible values
+ * @param[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'
+ * @param[in]   username        If region is SP_TOPLIST_REGION_USER this specifies which user to get toplists for. NULL means the logged in user.
+ * @param[in]   callback        Callback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
+ * @param[in]   userdata        Userdata passed to callback.
+ *
+ * @return                      Toplist browse object
+ *
+ * @see ::toplistbrowse_complete_cb
+ */
+SP_LIBEXPORT(sp_toplistbrowse *) sp_toplistbrowse_create(sp_session *session, sp_toplisttype type, sp_toplistregion region, const char *username, toplistbrowse_complete_cb *callback, void *userdata);
+
+
+/**
+ * Check if an toplist browse request is completed
+ *
+ * @param[in]   tlb        Toplist browse object
+ *
+ * @return                 True if browsing is completed, false if not
+ */
+SP_LIBEXPORT(bool) sp_toplistbrowse_is_loaded(sp_toplistbrowse *tlb);
+
+/**
+* Check if browsing returned an error code.
+*
+* @param[in]   tlb        Toplist browse object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_IS_LOADING
+*                         SP_ERROR_OTHER_PERMANENT
+*                         SP_ERROR_OTHER_TRANSIENT
+*/
+SP_LIBEXPORT(sp_error) sp_toplistbrowse_error(sp_toplistbrowse *tlb);
+
+
+
+/**
+ * Increase the reference count of an toplist browse result
+ *
+ * @param[in]   tlb       The toplist browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_toplistbrowse_add_ref(sp_toplistbrowse *tlb);
+
+/**
+ * Decrease the reference count of an toplist browse result
+ *
+ * @param[in]   tlb       The toplist browse result object
+ * @return                One of the following errors, from ::sp_error
+ *                        SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_toplistbrowse_release(sp_toplistbrowse *tlb);
+
+/**
+ * Given an toplist browse object, return number of artists
+ *
+ * @param[in]   tlb         Toplist browse object
+ *
+ * @return                  Number of artists on toplist
+ */
+SP_LIBEXPORT(int) sp_toplistbrowse_num_artists(sp_toplistbrowse *tlb);
+
+/**
+ * Return the artist at the given index in the given toplist browse object
+ *
+ * @param[in]  tlb        Toplist object
+ * @param[in]  index      Index of the wanted artist. Should be in the interval [0, sp_toplistbrowse_num_artists() - 1]
+ *
+ * @return                The artist at the given index in the given toplist browse object
+ */
+SP_LIBEXPORT(sp_artist *) sp_toplistbrowse_artist(sp_toplistbrowse *tlb, int index);
+
+
+/**
+ * Given an toplist browse object, return number of albums
+ *
+ * @param[in]   tlb         Toplist browse object
+ *
+ * @return                  Number of albums on toplist
+ */
+SP_LIBEXPORT(int) sp_toplistbrowse_num_albums(sp_toplistbrowse *tlb);
+
+
+/**
+ * Return the album at the given index in the given toplist browse object
+ *
+ * @param[in]  tlb        Toplist object
+ * @param[in]  index      Index of the wanted album. Should be in the interval [0, sp_toplistbrowse_num_albums() - 1]
+ *
+ * @return                The album at the given index in the given toplist browse object
+ */
+SP_LIBEXPORT(sp_album *) sp_toplistbrowse_album(sp_toplistbrowse *tlb, int index);
+
+
+/**
+ * Given an toplist browse object, return number of tracks
+ *
+ * @param[in]   tlb         Toplist browse object
+ *
+ * @return                  Number of tracks on toplist
+ */
+SP_LIBEXPORT(int) sp_toplistbrowse_num_tracks(sp_toplistbrowse *tlb);
+
+
+/**
+ * Return the track at the given index in the given toplist browse object
+ *
+ * @param[in]  tlb        Toplist object
+ * @param[in]  index      Index of the wanted track. Should be in the interval [0, sp_toplistbrowse_num_tracks() - 1]
+ *
+ * @return                The track at the given index in the given toplist browse object
+ */
+SP_LIBEXPORT(sp_track *) sp_toplistbrowse_track(sp_toplistbrowse *tlb, int index);
+
+/**
+ * Return the time (in ms) that was spent waiting for the Spotify backend to serve the request
+ *
+ * @param[in]  tlb        Toplist object
+ *
+ * @return                -1 if the request was served from the local cache
+ *                        If the result is not yet loaded the return value is undefined
+ */
+SP_LIBEXPORT(int) sp_toplistbrowse_backend_request_duration(sp_toplistbrowse *tlb);
+
+
+/** @} */
+
+/**
+ * @defgroup inbox Inbox subsystem
+ * @{
+ */
+
+/**
+ * The type of a callback used in sp_inbox_post()
+ *
+ * When this callback is called, the sp_track_is_loaded(), sp_album_is_loaded(),
+ * and sp_artist_is_loaded() functions will return non-zero for the objects
+ * contained in the search result.
+ *
+ * @param[in]   result          The same pointer returned by sp_search_create()
+ * @param[in]   userdata        The opaque pointer given to sp_search_create()
+ */
+typedef void SP_CALLCONV inboxpost_complete_cb(sp_inbox *result, void *userdata);
+
+/**
+ * Add to inbox
+ *
+ * @param[in]  session    Session object
+ * @param[in]  user       Canonical username of recipient
+ * @param[in]  tracks     Array of tracks to post
+ * @param[in]  num_tracks Number of tracks in \p tracks
+ * @param[in]  message    Message to attach to tracks. UTF-8
+ * @param[in]  callback   Callback to be invoked when the request has completed
+ * @param[in]  userdata   Userdata passed to callback
+ *
+ * @return                sp_inbox object if the request has been sent, NULL if request failed to initialize
+ */
+SP_LIBEXPORT(sp_inbox *) sp_inbox_post_tracks(sp_session *session, const char *user, sp_track * const *tracks, int num_tracks, const char *message, inboxpost_complete_cb *callback, void *userdata);
+
+
+/**
+* Check if inbox operation returned an error code.
+*
+* @param[in]   inbox      Inbox object
+*
+* @return                 One of the following errors, from ::sp_error
+*                         SP_ERROR_OK
+*                         SP_ERROR_OTHER_TRANSIENT
+*                         SP_ERROR_PERMISSION_DENIED
+*                         SP_ERROR_INVALID_INDATA
+*                         SP_ERROR_INBOX_IS_FULL
+*                         SP_ERROR_NO_SUCH_USER
+*                         SP_ERROR_OTHER_PERMANENT
+*/
+SP_LIBEXPORT(sp_error) sp_inbox_error(sp_inbox *inbox);
+
+/**
+ * Increase the reference count of a inbox result
+ *
+ * @param[in]   inbox    The inbox result object
+ * @return               One of the following errors, from ::sp_error
+ *                       SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_inbox_add_ref(sp_inbox *inbox);
+
+/**
+ * Decrease the reference count of a inbox result
+ *
+ * @param[in]   inbox    The inbox result object
+ * @return               One of the following errors, from ::sp_error
+ *                       SP_ERROR_OK
+ */
+SP_LIBEXPORT(sp_error) sp_inbox_release(sp_inbox *inbox);
+
+/** @} */
+
+/**
+ * Return the libspotify build ID
+ *
+ * This might be useful to have available for display somewhere in your
+ * user interface.
+ */
+SP_LIBEXPORT(const char *) sp_build_id(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* PUBLIC_API_H */
+/**
+ * @example browse.c
+ *
+ * The browse.c example shows how you can use the album, artist, and browse functions.
+ * The example also include some rudimentary playlist browsing.
+ * It is part of the spshell program
+ */
+/**
+ * @example search.c
+ *
+ * The search.c example shows how you can use search functions.
+ * It is part of the spshell program
+ */
+/**
+ * @example toplist.c
+ *
+ * The toplist.c example shows how you can use toplist functions.
+ * It is part of the spshell program
+ */
+/**
+ * @example jukebox.c
+ *
+ * The jukebox.c example shows how you can use playback and playlist functions.
+ */