libspotify
Data Structures | Macros | Typedefs | Enumerations | Functions
Session handling

Data Structures

struct  sp_audioformat
 
struct  sp_audio_buffer_stats
 
struct  sp_subscribers
 
struct  sp_offline_sync_status
 
struct  sp_session_callbacks
 
struct  sp_session_config
 

Macros

#define SPOTIFY_API_VERSION   12
 

Typedefs

typedef enum sp_connectionstate sp_connectionstate
 
typedef enum sp_sampletype sp_sampletype
 
typedef struct sp_audioformat sp_audioformat
 
typedef enum sp_bitrate sp_bitrate
 
typedef enum sp_playlist_type sp_playlist_type
 
typedef enum sp_search_type sp_search_type
 
typedef enum
sp_playlist_offline_status 
sp_playlist_offline_status
 
typedef enum sp_availability sp_track_availability
 
typedef enum
sp_track_offline_status 
sp_track_offline_status
 
typedef enum sp_image_size sp_image_size
 
typedef struct
sp_audio_buffer_stats 
sp_audio_buffer_stats
 
typedef struct sp_subscribers sp_subscribers
 
typedef enum sp_connection_type sp_connection_type
 
typedef enum sp_connection_rules sp_connection_rules
 
typedef enum sp_artistbrowse_type sp_artistbrowse_type
 
typedef struct
sp_offline_sync_status 
sp_offline_sync_status
 
typedef struct sp_session_callbacks sp_session_callbacks
 
typedef struct sp_session_config sp_session_config
 

Enumerations

enum  sp_connectionstate {
  SP_CONNECTION_STATE_LOGGED_OUT = 0,
  SP_CONNECTION_STATE_LOGGED_IN = 1,
  SP_CONNECTION_STATE_DISCONNECTED = 2,
  SP_CONNECTION_STATE_UNDEFINED = 3,
  SP_CONNECTION_STATE_OFFLINE = 4
}
 
enum  sp_sampletype { SP_SAMPLETYPE_INT16_NATIVE_ENDIAN = 0 }
 
enum  sp_bitrate {
  SP_BITRATE_160k = 0,
  SP_BITRATE_320k = 1,
  SP_BITRATE_96k = 2
}
 
enum  sp_playlist_type {
  SP_PLAYLIST_TYPE_PLAYLIST = 0,
  SP_PLAYLIST_TYPE_START_FOLDER = 1,
  SP_PLAYLIST_TYPE_END_FOLDER = 2,
  SP_PLAYLIST_TYPE_PLACEHOLDER = 3
}
 
enum  sp_search_type
 
enum  sp_playlist_offline_status {
  SP_PLAYLIST_OFFLINE_STATUS_NO = 0,
  SP_PLAYLIST_OFFLINE_STATUS_YES = 1,
  SP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING = 2,
  SP_PLAYLIST_OFFLINE_STATUS_WAITING = 3
}
 
enum  sp_availability {
  SP_TRACK_AVAILABILITY_UNAVAILABLE = 0,
  SP_TRACK_AVAILABILITY_AVAILABLE = 1,
  SP_TRACK_AVAILABILITY_NOT_STREAMABLE = 2,
  SP_TRACK_AVAILABILITY_BANNED_BY_ARTIST = 3
}
 
enum  sp_track_offline_status {
  SP_TRACK_OFFLINE_NO = 0,
  SP_TRACK_OFFLINE_WAITING = 1,
  SP_TRACK_OFFLINE_DOWNLOADING = 2,
  SP_TRACK_OFFLINE_DONE = 3,
  SP_TRACK_OFFLINE_ERROR = 4,
  SP_TRACK_OFFLINE_DONE_EXPIRED = 5,
  SP_TRACK_OFFLINE_LIMIT_EXCEEDED = 6,
  SP_TRACK_OFFLINE_DONE_RESYNC = 7
}
 
enum  sp_image_size {
  SP_IMAGE_SIZE_NORMAL = 0,
  SP_IMAGE_SIZE_SMALL = 1,
  SP_IMAGE_SIZE_LARGE = 2
}
 
enum  sp_connection_type {
  SP_CONNECTION_TYPE_UNKNOWN = 0,
  SP_CONNECTION_TYPE_NONE = 1,
  SP_CONNECTION_TYPE_MOBILE = 2,
  SP_CONNECTION_TYPE_MOBILE_ROAMING = 3,
  SP_CONNECTION_TYPE_WIFI = 4,
  SP_CONNECTION_TYPE_WIRED = 5
}
 
enum  sp_connection_rules {
  SP_CONNECTION_RULE_NETWORK = 0x1,
  SP_CONNECTION_RULE_NETWORK_IF_ROAMING = 0x2,
  SP_CONNECTION_RULE_ALLOW_SYNC_OVER_MOBILE = 0x4,
  SP_CONNECTION_RULE_ALLOW_SYNC_OVER_WIFI = 0x8
}
 
enum  sp_artistbrowse_type {
  SP_ARTISTBROWSE_FULL,
  SP_ARTISTBROWSE_NO_TRACKS,
  SP_ARTISTBROWSE_NO_ALBUMS
}
 

Functions

sp_error sp_session_create (const sp_session_config *config, sp_session **sess)
 
sp_error sp_session_release (sp_session *sess)
 
sp_error sp_session_login (sp_session *session, const char *username, const char *password, bool remember_me, const char *blob)
 
sp_error sp_session_relogin (sp_session *session)
 
int sp_session_remembered_user (sp_session *session, char *buffer, size_t buffer_size)
 
const char * sp_session_user_name (sp_session *session)
 
sp_error sp_session_forget_me (sp_session *session)
 
sp_usersp_session_user (sp_session *session)
 
sp_error sp_session_logout (sp_session *session)
 
sp_error sp_session_signup_perform_action (sp_session *session, sp_signup_action action, void *user_data)
 
int sp_session_signup_get_unaccepted_licenses (sp_session *session, const char **licenses, int num_licenses)
 
sp_error sp_session_flush_caches (sp_session *session)
 
sp_connectionstate sp_session_connectionstate (sp_session *session)
 
void * sp_session_userdata (sp_session *session)
 
sp_error sp_session_set_cache_size (sp_session *session, size_t size)
 
sp_error sp_session_process_events (sp_session *session, int *next_timeout)
 
sp_error sp_session_player_load (sp_session *session, sp_track *track)
 
sp_error sp_session_player_seek (sp_session *session, int offset)
 
sp_error sp_session_player_play (sp_session *session, bool play)
 
sp_error sp_session_player_unload (sp_session *session)
 
sp_error sp_session_player_prefetch (sp_session *session, sp_track *track)
 
sp_playlistcontainersp_session_playlistcontainer (sp_session *session)
 
sp_playlistsp_session_inbox_create (sp_session *session)
 
sp_playlistsp_session_starred_create (sp_session *session)
 
sp_playlistsp_session_starred_for_user_create (sp_session *session, const char *canonical_username)
 
sp_playlistcontainersp_session_publishedcontainer_for_user_create (sp_session *session, const char *canonical_username)
 
sp_error sp_session_preferred_bitrate (sp_session *session, sp_bitrate bitrate)
 
sp_error sp_session_preferred_offline_bitrate (sp_session *session, sp_bitrate bitrate, bool allow_resync)
 
bool sp_session_get_volume_normalization (sp_session *session)
 
sp_error sp_session_set_volume_normalization (sp_session *session, bool on)
 
sp_error sp_session_set_private_session (sp_session *session, bool enabled)
 
bool sp_session_is_private_session (sp_session *session)
 
sp_error sp_session_set_scrobbling (sp_session *session, sp_social_provider provider, sp_scrobbling_state state)
 
sp_error sp_session_is_scrobbling (sp_session *session, sp_social_provider provider, sp_scrobbling_state *state)
 
sp_error sp_session_is_scrobbling_possible (sp_session *session, sp_social_provider provider, bool *out)
 
sp_error sp_session_set_social_credentials (sp_session *session, sp_social_provider provider, const char *username, const char *password)
 
sp_error sp_session_set_connection_type (sp_session *session, sp_connection_type type)
 
sp_error sp_session_set_connection_rules (sp_session *session, sp_connection_rules rules)
 
int sp_offline_tracks_to_sync (sp_session *session)
 
int sp_offline_num_playlists (sp_session *session)
 
bool sp_offline_sync_get_status (sp_session *session, sp_offline_sync_status *status)
 
int sp_offline_time_left (sp_session *session)
 
int sp_session_user_country (sp_session *session)
 

Detailed Description

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.

Macro Definition Documentation

#define SPOTIFY_API_VERSION   12

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.

Examples:
jukebox.c.

Typedef Documentation

Controls the type of data that will be included in artist browse queries

Buffer stats used by get_audio_buffer_stats callback

Audio format descriptor

typedef enum sp_bitrate sp_bitrate

Bitrate definitions for music streaming

Connection rules, bitwise OR of flags

The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC

Current connection type set using sp_session_set_connection_type()

Describes the current state of the connection

Image size

Offline sync status

Playlist offline status

Playlist types

Sample type descriptor

Search types

Session callbacks

Registered when you create a session. If some callbacks should not be of interest, set them to NULL.

Session config

List of subscribers returned by sp_playlist_subscribers()

Track availability

Track offline status

Enumeration Type Documentation

Controls the type of data that will be included in artist browse queries

Enumerator
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

Track availability

Enumerator
SP_TRACK_AVAILABILITY_UNAVAILABLE 

Track is not available.

SP_TRACK_AVAILABILITY_AVAILABLE 

Track is available and can be played.

SP_TRACK_AVAILABILITY_NOT_STREAMABLE 

Track can not be streamed using this account.

SP_TRACK_AVAILABILITY_BANNED_BY_ARTIST 

Track not available on artist's reqeust.

enum sp_bitrate

Bitrate definitions for music streaming

Enumerator
SP_BITRATE_160k 

Bitrate 160kbps.

SP_BITRATE_320k 

Bitrate 320kbps.

SP_BITRATE_96k 

Bitrate 96kbps.

Connection rules, bitwise OR of flags

The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC

Enumerator
SP_CONNECTION_RULE_NETWORK 

Allow network traffic. When not set libspotify will force itself into offline mode.

SP_CONNECTION_RULE_NETWORK_IF_ROAMING 

Allow network traffic even if roaming.

SP_CONNECTION_RULE_ALLOW_SYNC_OVER_MOBILE 

Set to allow syncing of offline content over mobile connections.

SP_CONNECTION_RULE_ALLOW_SYNC_OVER_WIFI 

Set to allow syncing of offline content over WiFi.

Current connection type set using sp_session_set_connection_type()

Enumerator
SP_CONNECTION_TYPE_UNKNOWN 

Connection type unknown (Default)

SP_CONNECTION_TYPE_NONE 

No connection.

SP_CONNECTION_TYPE_MOBILE 

Mobile data (EDGE, 3G, etc)

SP_CONNECTION_TYPE_MOBILE_ROAMING 

Roamed mobile data (EDGE, 3G, etc)

SP_CONNECTION_TYPE_WIFI 

Wireless connection.

SP_CONNECTION_TYPE_WIRED 

Ethernet cable, etc.

Describes the current state of the connection

Enumerator
SP_CONNECTION_STATE_LOGGED_OUT 

User not yet logged in.

SP_CONNECTION_STATE_LOGGED_IN 

Logged in against a Spotify access point.

SP_CONNECTION_STATE_DISCONNECTED 

Was logged in, but has now been disconnected.

SP_CONNECTION_STATE_UNDEFINED 

The connection state is undefined.

SP_CONNECTION_STATE_OFFLINE 

Logged in in offline mode.

Image size

Enumerator
SP_IMAGE_SIZE_NORMAL 

Normal image size.

SP_IMAGE_SIZE_SMALL 

Small image size.

SP_IMAGE_SIZE_LARGE 

Large image size.

Playlist offline status

Enumerator
SP_PLAYLIST_OFFLINE_STATUS_NO 

Playlist is not offline enabled.

SP_PLAYLIST_OFFLINE_STATUS_YES 

Playlist is synchronized to local storage.

SP_PLAYLIST_OFFLINE_STATUS_DOWNLOADING 

This playlist is currently downloading. Only one playlist can be in this state any given time.

SP_PLAYLIST_OFFLINE_STATUS_WAITING 

Playlist is queued for download.

Playlist types

Enumerator
SP_PLAYLIST_TYPE_PLAYLIST 

A normal playlist.

SP_PLAYLIST_TYPE_START_FOLDER 

Marks a folder starting point,.

SP_PLAYLIST_TYPE_END_FOLDER 

and ending point.

SP_PLAYLIST_TYPE_PLACEHOLDER 

Unknown entry.

Sample type descriptor

Enumerator
SP_SAMPLETYPE_INT16_NATIVE_ENDIAN 

16-bit signed integer samples

Search types

Track offline status

Enumerator
SP_TRACK_OFFLINE_NO 

Not marked for offline.

SP_TRACK_OFFLINE_WAITING 

Waiting for download.

SP_TRACK_OFFLINE_DOWNLOADING 

Currently downloading.

SP_TRACK_OFFLINE_DONE 

Downloaded OK and can be played.

SP_TRACK_OFFLINE_ERROR 

Error during download.

SP_TRACK_OFFLINE_DONE_EXPIRED 

Downloaded OK but not playable due to expiery.

SP_TRACK_OFFLINE_LIMIT_EXCEEDED 

Waiting because device have reached max number of allowed tracks.

SP_TRACK_OFFLINE_DONE_RESYNC 

Downloaded OK and available but scheduled for re-download.

Function Documentation

int sp_offline_num_playlists ( sp_session session)

Return number of playlisys that is marked for offline synchronization

Parameters
[in]sessionSession object
Returns
Number of playlists
bool sp_offline_sync_get_status ( sp_session session,
sp_offline_sync_status status 
)

Return offline synchronization status. When the internal status is updated the offline_status_updated() callback will be invoked.

Parameters
[in]sessionSession object
[out]statusStatus object that will be filled with info
Returns
false if no synching is in progress (in which case the contents of status is undefined)
int sp_offline_time_left ( sp_session session)

Return remaining time (in seconds) until the offline key store expires and the user is required to relogin

Parameters
[in]sessionSession object
Returns
Seconds until expiration
int sp_offline_tracks_to_sync ( sp_session session)

Get total number of tracks that needs download before everything from all playlists that is marked for offline is fully synchronized

Parameters
[in]sessionSession object
Returns
Number of tracks
sp_connectionstate sp_session_connectionstate ( sp_session session)

The connection state of the specified session.

Parameters
[in]sessionYour session object
Returns
The connection state - see the sp_connectionstate enum for possible values
sp_error sp_session_create ( const sp_session_config config,
sp_session **  sess 
)

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 spshell.c:

config.api_version = SPOTIFY_API_VERSION;
// The path of the directory to store the cache. This must be specified.
// Please read the documentation on preferred values.
config.cache_location = selftest ? "" : "tmp";
// The path of the directory to store the settings.
// This must be specified.
// Please read the documentation on preferred values.
config.settings_location = selftest ? "" : "tmp";
// The key of the application. They are generated by Spotify,
// and are specific to each application using libspotify.
config.application_key = g_appkey;
config.application_key_size = g_appkey_size;
// This identifies the application using some
// free-text string [1, 255] characters.
config.user_agent = "spshell";
//ifdef SP_WITH_CURL
#ifdef SP_WITH_CURL
config.ca_certs_filename = "../cacerts.pem";
#endif
//endif
// Register the callbacks.
callbacks.logged_in = logged_in;
callbacks.logged_out = logged_out;
callbacks.metadata_updated = metadata_updated;
callbacks.connection_error = connection_error;
callbacks.notify_main_thread = notify_main_thread;
#if WITH_TEST_COMMAND
callbacks.music_delivery = music_delivery;
callbacks.play_token_lost = play_token_lost;
callbacks.end_of_track = end_of_track;
#endif
callbacks.log_message = log_message;
callbacks.offline_status_updated = offline_status_updated;
callbacks.credentials_blob_updated = credentials_blob_updated;
//ifdef SP_LIBSPOTIFY_WITH_SCROBBLING
#ifdef SP_LIBSPOTIFY_WITH_SCROBBLING
callbacks.scrobble_error = scrobble_error;
callbacks.private_session_mode_changed = private_session_mode_changed;
#endif
//endif
config.callbacks = &callbacks;
error = sp_session_create(&config, &session);
if (SP_ERROR_OK != error) {
fprintf(stderr, "failed to create session: %s\n",
return 2;
}

Parameters
[in]configThe configuration to use for the session
[out]sessIf successful, a new session - otherwise NULL
Returns
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
Examples:
jukebox.c.
sp_error sp_session_flush_caches ( 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.

Parameters
[in]sessionYour session object
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_forget_me ( sp_session session)

Remove stored credentials in libspotify. If no credentials are currently stored, nothing will happen.

Parameters
[in]sessionYour session object
Returns
One of the following errors, from sp_error SP_ERROR_OK
bool sp_session_get_volume_normalization ( sp_session session)

Return status of volume normalization

Parameters
[in]sessionSession object
Returns
true iff volume normalization is enabled
sp_playlist* sp_session_inbox_create ( sp_session session)

Returns an inbox playlist for the currently logged in user

Parameters
[in]sessionSession object
Returns
A playlist or NULL if no user is logged in
Note
You need to release the playlist when you are done with it.
See Also
sp_playlist_release()
bool sp_session_is_private_session ( sp_session session)

Return True if private session is enabled

Parameters
[in]sessionSession object
Returns
True if private session is enabled
sp_error sp_session_is_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.

Parameters
[in]sessionSession object
[in]providerThe scrobbling provider referred to
[out]stateThe output variable receiving the sp_scrobbling_state state
Returns
error code
sp_error sp_session_is_scrobbling_possible ( sp_session session,
sp_social_provider  provider,
bool *  out 
)

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.

Parameters
[in]sessionSession object
[in]providerThe scrobbling provider referred to
[out]outTrue iff scrobbling is possible
Returns
error code
sp_error sp_session_login ( sp_session session,
const char *  username,
const char *  password,
bool  remember_me,
const char *  blob 
)

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 spshell.c:

sp_session_login(session, username, password, 1, blob);
}

Parameters
[in]sessionYour session object
[in]usernameThe username to log in
[in]passwordThe password for the specified username
[in]remember_meIf set, the username / password will be remembered by libspotify
[in]blobIf you have received a blob in the #credentials_blob_updated you can pas this here instead of password
Returns
One of the following errors, from sp_error SP_ERROR_OK
Examples:
jukebox.c.
sp_error sp_session_logout ( 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.

Parameters
[in]sessionYour session object
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_player_load ( sp_session session,
sp_track track 
)

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.

Parameters
[in]sessionYour session object
[in]trackThe track to be loaded
Returns
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_MISSING_CALLBACK SP_ERROR_TRACK_NOT_PLAYABLE
Examples:
jukebox.c.
sp_error sp_session_player_play ( sp_session session,
bool  play 
)

Play or pause the currently loaded track

Parameters
[in]sessionYour session object
[in]playIf set to true, playback will occur. If set to false, the playback will be paused.
Returns
One of the following errors, from sp_error SP_ERROR_OK
Examples:
jukebox.c.
sp_error sp_session_player_prefetch ( sp_session session,
sp_track track 
)

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.

Parameters
[in]sessionYour session object
[in]trackThe track to be prefetched
Returns
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_error sp_session_player_seek ( sp_session session,
int  offset 
)

Seek to position in the currently loaded track

Parameters
[in]sessionYour session object
[in]offsetTrack position, in milliseconds.
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_player_unload ( sp_session session)

Stops the currently playing track

This frees some resources held by libspotify to identify the currently playing track.

Parameters
[in]sessionYour session object
Returns
One of the following errors, from sp_error SP_ERROR_OK
Examples:
jukebox.c.
sp_playlistcontainer* sp_session_playlistcontainer ( sp_session session)

Returns the playlist container for the currently logged in user.

Parameters
[in]sessionYour session object
Returns
Playlist container object, NULL if not logged in
Examples:
jukebox.c.
sp_error sp_session_preferred_bitrate ( sp_session session,
sp_bitrate  bitrate 
)

Set preferred bitrate for music streaming

Parameters
[in]sessionSession object
[in]bitratePreferred bitrate, see sp_bitrate for possible values
Returns
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_INVALID_ARGUMENT
sp_error sp_session_preferred_offline_bitrate ( sp_session session,
sp_bitrate  bitrate,
bool  allow_resync 
)

Set preferred bitrate for offline sync

Parameters
[in]sessionSession object
[in]bitratePreferred bitrate, see sp_bitrate for possible values
[in]allow_resyncSet to true if libspotify should resynchronize already synchronized tracks. Usually you should set this to false.
Returns
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_INVALID_ARGUMENT
sp_error sp_session_process_events ( sp_session session,
int *  next_timeout 
)

Make the specified session process any pending events

Parameters
[in]sessionYour session object
[out]next_timeoutStores the time (in milliseconds) until you should call this function again
Returns
One of the following errors, from sp_error SP_ERROR_OK
Examples:
jukebox.c.
sp_playlistcontainer* sp_session_publishedcontainer_for_user_create ( sp_session session,
const char *  canonical_username 
)

Return the published container for a given canonical_username, or the currently logged in user if 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.

Parameters
[in]sessionYour session object.
[in]canonical_usernameThe canonical username, or NULL.
Returns
Playlist container object, NULL if not logged in.
sp_error sp_session_release ( sp_session sess)

Release the session. This will clean up all data and connections associated with the session

Parameters
[in]sessSession object returned from sp_session_create()
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_relogin ( sp_session session)

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.

Parameters
[in]sessionYour session object
Returns
One of the following errors, from sp_error SP_ERROR_OK SP_ERROR_NO_CREDENTIALS
int sp_session_remembered_user ( sp_session session,
char *  buffer,
size_t  buffer_size 
)

Get username of the user that will be logged in via sp_session_relogin()

Parameters
[in]sessionYour session object
[out]bufferThe buffer to hold the username
[in]buffer_sizeThe max size of the buffer that will hold the username. The resulting string is guaranteed to always be null terminated if buffer_size > 0
Returns
The number of characters in the username. If value is greater or equal than buffer_size, output was truncated. If returned value is -1 no credentials are stored in libspotify.
sp_error sp_session_set_cache_size ( sp_session session,
size_t  size 
)

Set maximum cache size.

Parameters
[in]sessionYour session object
[in]sizeMaximum cache size in megabytes. Setting it to 0 (the default) will let libspotify automatically resize the cache (10% of disk free space)
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_set_connection_rules ( sp_session session,
sp_connection_rules  rules 
)

Set rules for how libspotify connects to Spotify servers and synchronizes offline content

Parameters
[in]sessionSession object
[in]rulesConnection 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 Also
sp_connection_rules
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_set_connection_type ( sp_session session,
sp_connection_type  type 
)

Set to true if the connection is currently routed over a roamed connectivity

Parameters
[in]sessionSession object
[in]typeConnection 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 Also
sp_connection_type
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_set_private_session ( sp_session session,
bool  enabled 
)

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.

Parameters
[in]sessionSession object
[in]enabledTrue iff private session should be enabled
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_set_scrobbling ( sp_session session,
sp_social_provider  provider,
sp_scrobbling_state  state 
)

Set if scrobbling is enabled. This api allows setting local overrides of the global scrobbling settings. Changing the global settings are currently not supported.

Parameters
[in]sessionSession object
[in]providerThe scrobbling provider referred to
[in]stateThe state to set the provider to
Returns
error code
See Also
sp_social_provider
sp_scrobbling_state
sp_error sp_session_set_social_credentials ( sp_session session,
sp_social_provider  provider,
const char *  username,
const char *  password 
)

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.

Parameters
[in]sessionSession object
[in]providerThe scrobbling provider referred to
[in]usernameThe user name
[in]passwordThe password
Returns
error code
See Also
sp_session_set_scrobbling
sp_session_callbacks::scrobble_error
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_error sp_session_set_volume_normalization ( sp_session session,
bool  on 
)

Set volume normalization

Parameters
[in]sessionSession object
[in]onTrue iff volume normalization should be enabled
Returns
One of the following errors, from sp_error SP_ERROR_OK
int sp_session_signup_get_unaccepted_licenses ( sp_session session,
const char **  licenses,
int  num_licenses 
)

Get required licenses.

Use to prompt the user to accept any unsigned licenses.

Parameters
[in]sessionYour session object.
[out]licensesPointer to an array of char * to fill with licenses. May be NULL.
[in]num_licensesThe size of your licenses array.
Returns
The number of licenses available.
sp_error sp_session_signup_perform_action ( sp_session session,
sp_signup_action  action,
void *  user_data 
)

Perform a signup action.

Use to signify that the user has performed a step in account signup.

Parameters
[in]sessionYour session object.
[in]actionThe action to perform.
[in]user_dataThe data associated with the action.
Returns
One of the following errors, from sp_error SP_ERROR_OK
sp_playlist* sp_session_starred_create ( sp_session session)

Returns the starred list for the current user

Parameters
[in]sessionSession object
Returns
A playlist or NULL if no user is logged in
Note
You need to release the playlist when you are done with it.
See Also
sp_playlist_release()
sp_playlist* sp_session_starred_for_user_create ( sp_session session,
const char *  canonical_username 
)

Returns the starred list for a user

Parameters
[in]sessionSession object
[in]canonical_usernameCanonical username
Returns
A playlist or NULL if no user is logged in
Note
You need to release the playlist when you are done with it.
See Also
sp_playlist_release()
sp_user* sp_session_user ( sp_session session)

Fetches the currently logged in user

Parameters
[in]sessionYour session object
Returns
The logged in user (or NULL if not logged in)
int sp_session_user_country ( sp_session session)

Get currently logged in users country updated the offline_status_updated() callback will be invoked.

Parameters
[in]sessionSession object
Returns
Country encoded in an integer 'SE' = 'S' << 8 | 'E'
const char* sp_session_user_name ( sp_session session)

Get a pointer to a string representing the user's login username.

Parameters
[in]sessionYour session object
Returns
A string representing the login username.
void* sp_session_userdata ( sp_session session)

The userdata associated with the session

Parameters
[in]sessionYour session object
Returns
The userdata that was passed in on session creation

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