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 10 |
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 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 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 |
| 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 |
Bitrate definitions for music streaming
| 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
Playlist offline status
| enum sp_playlist_type |
| enum sp_sampletype |
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";
// Register the callbacks.
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 |
| void 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 |
| void sp_session_login | ( | sp_session * | session, | |
| const char * | username, | |||
| const char * | password, | |||
| bool | remember_me | |||
| ) |
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); }
| [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 |
| void 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 |
| void sp_session_player_play | ( | sp_session * | session, | |
| bool | play | |||
| ) |
Play or pause the currently loaded track
| [in] | session | Your session object |
| [in] | play | If set to true, playback will occur. If set to false, the playback will be paused. |
| 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 |
| void 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. |
| void 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.
| [in] | session | Your session object |
| sp_playlistcontainer* sp_session_playlistcontainer | ( | sp_session * | session | ) |
Returns the playlist container for the currently logged in user.
| [in] | session | Your session object |
| void 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 |
| void 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. |
| void sp_session_process_events | ( | sp_session * | session, | |
| int * | next_timeout | |||
| ) |
Make the specified session process any pending events
| [in] | session | Your session object |
| [out] | next_timeout | Stores the time (in milliseconds) until you should call this function again |
| 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. |
| void 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. | void 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) |
| void 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 |
| void 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 |
| void 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 |
| void* sp_session_userdata | ( | sp_session * | session | ) |
The userdata associated with the session
| [in] | session | Your session object |