Session handling


Data Structures
struct	sp_audioformat
struct	sp_audio_buffer_stats
struct	sp_session_callbacks
struct	sp_session_config
Defines
#define	SPOTIFY_API_VERSION 6
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 }
enum	sp_sampletype { SP_SAMPLETYPE_INT16_NATIVE_ENDIAN = 0 }
enum	sp_bitrate
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 }
Functions
sp_error	sp_session_create (const sp_session_config config, sp_session *sess)
void	sp_session_release (sp_session *sess)
sp_error	sp_session_login (sp_session session, const char username, const char *password)
sp_user *	sp_session_user (sp_session *session)
sp_error	sp_session_logout (sp_session *session)
sp_connectionstate	sp_session_connectionstate (sp_session *session)
void *	sp_session_userdata (sp_session *session)
void	sp_session_set_cache_size (sp_session *session, size_t size)
void	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)
void	sp_session_player_unload (sp_session *session)
sp_error	sp_session_player_prefetch (sp_session session, sp_track track)
sp_playlistcontainer *	sp_session_playlistcontainer (sp_session *session)
sp_playlist *	sp_session_inbox_create (sp_session *session)
sp_playlist *	sp_session_starred_create (sp_session *session)
sp_playlist *	sp_session_starred_for_user_create (sp_session session, const char username)
sp_playlistcontainer *	sp_session_publishedcontainer_for_user (sp_session session, const char canonical_username)
void	sp_session_publishedcontainer_for_user_release (sp_session session, const char canonical_username)
void	sp_session_preferred_bitrate (sp_session *session, sp_bitrate bitrate)
int	sp_session_num_friends (sp_session *session)
sp_user *	sp_session_friend (sp_session *session, int index)

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.

Define Documentation

#define SPOTIFY_API_VERSION 6

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.

Enumeration Type Documentation

enum sp_bitrate

Bitrate definitions for music streaming

enum sp_connectionstate

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.

enum sp_playlist_type

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.

enum sp_sampletype

Sample type descriptor

Enumerator:

SP_SAMPLETYPE_INT16_NATIVE_ENDIAN

16-bit signed integer samples

Function Documentation

sp_connectionstate sp_session_connectionstate ( sp_session * session )

The connection state of the specified session.

Parameters:

[in] session Your 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

Here is a snippet from spshell.c:

Parameters:

`[in]`	config	The configuration to use for the session
`[out]`	sess	If successful, a new session - otherwise NULL

Returns:: Error code sp_error

sp_user* sp_session_friend	(	sp_session *	session,
		int	index
	)

Retrun the given user from the currently logged in users list of friends

Parameters:

`[in]`	session	Session object
`[in]`	index	Index in list

Returns:: A user. The object is owned by the session so the caller should not release it.

sp_playlist* sp_session_inbox_create ( sp_session * session )

Returns an inbox playlist for the currently logged in user

Parameters:

[in] session Session object

Returns:: A playlist.

Note:: You need to release the playlist when you are done with it.

See also:: sp_playlist_release()

sp_error sp_session_login	(	sp_session *	session,
		const char *	username,
		const char *	password
	)

Logs in the specified username/password combo. This initiates the download in the background. A callback is called when login is complete

Here is a snippet from spshell.c:

Parameters:

`[in]`	session	Your session object
`[in]`	username	The username to log in
`[in]`	password	The password for the specified username

Returns:: Result of the operation

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] session Your session object

Returns:: Result of the operation

int sp_session_num_friends ( sp_session * session )

Return number of friends in the currently logged in users friends list.

Parameters:

[in] session Session object

Returns:: Number of users in friends. Each user can be extracted using the sp_session_friend() method The number of users in the list will not be updated nor change order between calls to sp_session_process_events()

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]`	session	Your session object
`[in]`	track	The track to be loaded

Returns:: The result of the operation - see the sp_error enum for possible values

sp_error sp_session_player_play	(	sp_session *	session,
		bool	play
	)

Play or pause the currently loaded track

Parameters:

`[in]`	session	Your session object
`[in]`	play	If set to true, playback will occur. If set to false, the playback will be paused.

Returns:: The result of the operation - see the sp_error enum for possible values

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]`	session	Your session object
`[in]`	track	The track to be prefetched

Returns:: The result of the operation - see the sp_error enum for possible values

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]`	session	Your session object
`[in]`	offset	Track position, in milliseconds.

Returns:: The result of the operation - see the sp_error enum for possible values

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.

Parameters:

[in] session Your session object

sp_playlistcontainer* sp_session_playlistcontainer ( sp_session * session )

Returns the playlist container for the currently logged in user.

Parameters:

[in] session Your session object

Returns:: Playlist container object, NULL if not logged in

void sp_session_preferred_bitrate	(	sp_session *	session,
		sp_bitrate	bitrate
	)

Set preferred bitrate for music streaming

Parameters:

`[in]`	session	Session object
`[in]`	bitrate	Preferred bitrate, see sp_bitrate for possible values

void sp_session_process_events	(	sp_session *	session,
		int *	next_timeout
	)

Make the specified session process any pending events

Parameters:

`[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	(	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.

The container can be released when you're done with it, using sp_session_publishedcontainer_fo_user_release(), or it will be released when calling sp_session_logout().

Subsequent requests for a published container will return the same object, unless it has been released previously.

Parameters:

`[in]`	session	Your session object.
`[in]`	username	The canonical username, or NULL.

Returns:: Playlist container object, NULL if not logged in or not found.

void sp_session_publishedcontainer_for_user_release	(	sp_session *	session,
		const char *	canonical_username
	)

Releases the playlistcontainer for canonical_username.

Parameters:

[in] canonical_username Canonical username

void sp_session_release ( sp_session * sess )

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

Parameters:

[in] sess Session object returned from sp_session_create()

void sp_session_set_cache_size	(	sp_session *	session,
		size_t	size
	)

Set maximum cache size.

Parameters:

`[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_playlist* sp_session_starred_create ( sp_session * session )

Returns the starred list for the current user

Parameters:

[in] session Session object

Returns:: A playlist.

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 *	username
	)

Returns the starred list for a user

Parameters:

`[in]`	session	Session object
`[in]`	canonical_username	Canonical username

Returns:: A playlist.

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] session Your session object

Returns:: The logged in user (or NULL if not logged in)

void* sp_session_userdata ( sp_session * session )

The userdata associated with the session

Parameters:

[in] session Your session object

Returns:: The userdata that was passed in on session creation

Session handling

Data Structures

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation