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.
#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.
typedef enum sp_artistbrowse_type sp_artistbrowse_type |
Controls the type of data that will be included in artist browse queries
typedef struct sp_audio_buffer_stats sp_audio_buffer_stats |
Buffer stats used by get_audio_buffer_stats callback
typedef struct sp_audioformat sp_audioformat |
Audio format descriptor
typedef enum sp_bitrate sp_bitrate |
Bitrate definitions for music streaming
typedef enum sp_connection_rules sp_connection_rules |
Connection rules, bitwise OR of flags
The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC
typedef enum sp_connection_type sp_connection_type |
Current connection type set using sp_session_set_connection_type()
typedef enum sp_connectionstate sp_connectionstate |
Describes the current state of the connection
typedef enum sp_image_size sp_image_size |
Image size
typedef struct sp_offline_sync_status sp_offline_sync_status |
Offline sync status
typedef enum sp_playlist_offline_status sp_playlist_offline_status |
Playlist offline status
typedef enum sp_playlist_type sp_playlist_type |
Playlist types
typedef enum sp_sampletype sp_sampletype |
Sample type descriptor
typedef enum sp_search_type sp_search_type |
Search types
typedef struct sp_session_callbacks sp_session_callbacks |
Session callbacks
Registered when you create a session. If some callbacks should not be of interest, set them to NULL.
typedef struct sp_session_config sp_session_config |
Session config
typedef struct sp_subscribers sp_subscribers |
List of subscribers returned by sp_playlist_subscribers()
typedef enum sp_availability sp_track_availability |
Track availability
typedef enum sp_track_offline_status sp_track_offline_status |
Track offline status
enum sp_artistbrowse_type |
Controls the type of data that will be included in artist browse queries
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 |
enum sp_availability |
Track availability
enum sp_bitrate |
enum sp_connection_rules |
Connection rules, bitwise OR of flags
The default is SP_CONNECTION_RULE_NETWORK | SP_CONNECTION_RULE_ALLOW_SYNC
enum sp_connection_type |
Current connection type set using sp_session_set_connection_type()
enum sp_connectionstate |
Describes the current state of the connection
enum sp_image_size |
Playlist offline status
enum sp_playlist_type |
enum sp_sampletype |
enum sp_search_type |
Search types
Track offline status
int sp_offline_num_playlists | ( | sp_session * | session | ) |
Return number of playlisys that is marked for offline synchronization
[in] | session | Session object |
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.
[in] | session | Session object |
[out] | status | Status object that will be filled with info |
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
[in] | session | Session object |
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
[in] | session | Session object |
sp_connectionstate sp_session_connectionstate | ( | sp_session * | session | ) |
The connection state of the specified session.
[in] | session | Your session object |
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", sp_error_message(error)); return 2; }
[in] | config | The configuration to use for the session |
[out] | sess | If successful, a new session - otherwise NULL |
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.
[in] | session | Your session object |
sp_error sp_session_forget_me | ( | sp_session * | session | ) |
Remove stored credentials in libspotify. If no credentials are currently stored, nothing will happen.
[in] | session | Your session object |
bool sp_session_get_volume_normalization | ( | sp_session * | session | ) |
Return status of volume normalization
[in] | session | Session object |
sp_playlist* sp_session_inbox_create | ( | sp_session * | session | ) |
Returns an inbox playlist for the currently logged in user
[in] | session | Session object |
bool sp_session_is_private_session | ( | sp_session * | session | ) |
Return True if private session is enabled
[in] | session | Session object |
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.
[in] | session | Session object |
[in] | provider | The scrobbling provider referred to |
[out] | state | The output variable receiving the sp_scrobbling_state state |
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.
[in] | session | Session object |
[in] | provider | The scrobbling provider referred to |
[out] | out | True iff scrobbling is possible |
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); }
[in] | session | Your session object |
[in] | username | The username to log in |
[in] | password | The password for the specified username |
[in] | remember_me | If set, the username / password will be remembered by libspotify |
[in] | blob | If you have received a blob in the credentials_blob_updated you can pas this here instead of password |
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.
[in] | session | Your session object |
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.
[in] | session | Your session object |
[in] | track | The track to be loaded |
sp_error sp_session_player_play | ( | sp_session * | session, | |
bool | play | |||
) |
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.
[in] | session | Your session object |
[in] | track | The track to be prefetched |
sp_error sp_session_player_seek | ( | sp_session * | session, | |
int | offset | |||
) |
Seek to position in the currently loaded track
[in] | session | Your session object |
[in] | offset | Track position, in milliseconds. |
sp_error sp_session_player_unload | ( | sp_session * | session | ) |
sp_playlistcontainer* sp_session_playlistcontainer | ( | sp_session * | session | ) |
Returns the playlist container for the currently logged in user.
[in] | session | Your session object |
sp_error sp_session_preferred_bitrate | ( | sp_session * | session, | |
sp_bitrate | bitrate | |||
) |
Set preferred bitrate for music streaming
[in] | session | Session object |
[in] | bitrate | Preferred bitrate, see sp_bitrate for possible values |
sp_error sp_session_preferred_offline_bitrate | ( | sp_session * | session, | |
sp_bitrate | bitrate, | |||
bool | allow_resync | |||
) |
Set preferred bitrate for offline sync
[in] | session | Session object |
[in] | bitrate | Preferred bitrate, see sp_bitrate for possible values |
[in] | allow_resync | Set to true if libspotify should resynchronize already synchronized tracks. Usually you should set this to false. |
sp_error sp_session_process_events | ( | sp_session * | session, | |
int * | next_timeout | |||
) |
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.
[in] | session | Your session object. |
[in] | canonical_username | The canonical username, or NULL. |
sp_error sp_session_release | ( | sp_session * | sess | ) |
Release the session. This will clean up all data and connections associated with the session
[in] | sess | Session object returned from sp_session_create() |
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.
[in] | session | Your session object |
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()
[in] | session | Your session object |
[out] | buffer | The buffer to hold the username |
[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 |
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.
[in] | session | Your session object |
[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) |
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
[in] | session | Session object |
[in] | rules | Connection rules |
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
[in] | session | Session object |
[in] | type | Connection type |
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.
[in] | session | Session object |
[in] | enabled | True iff private session should be enabled |
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.
[in] | session | Session object |
[in] | provider | The scrobbling provider referred to |
[in] | state | The state to set the provider to |
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.
[in] | session | Session object |
[in] | provider | The scrobbling provider referred to |
[in] | username | The user name |
[in] | password | The password |
sp_error sp_session_set_volume_normalization | ( | sp_session * | session, | |
bool | on | |||
) |
Set volume normalization
[in] | session | Session object |
[in] | on | True iff volume normalization should be enabled |
sp_playlist* sp_session_starred_create | ( | sp_session * | session | ) |
Returns the starred list for the current user
[in] | session | Session object |
sp_playlist* sp_session_starred_for_user_create | ( | sp_session * | session, | |
const char * | canonical_username | |||
) |
Returns the starred list for a user
[in] | session | Session object |
[in] | canonical_username | Canonical username |
sp_user* sp_session_user | ( | sp_session * | session | ) |
Fetches the currently logged in user
[in] | session | Your session object |
int sp_session_user_country | ( | sp_session * | session | ) |
Get currently logged in users country updated the offline_status_updated() callback will be invoked.
[in] | session | Session object |
const char* sp_session_user_name | ( | sp_session * | session | ) |
Get a pointer to a string representing the user's login username.
[in] | session | Your session object |
void* sp_session_userdata | ( | sp_session * | session | ) |
The userdata associated with the session
[in] | session | Your session object |