Data Structures | Defines | 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

Defines

#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_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.


Define 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.


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] session Session 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] session Session object
[out] status Status 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] session Session 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] session Session object
Returns:
Number of tracks
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 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;
    }

Parameters:
[in] config The configuration to use for the session
[out] sess If 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] session Your 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] session Your 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] session Session 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] session Session 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] session Session 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] session Session object
[in] provider The scrobbling provider referred to
[out] state The 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] session Session object
[in] provider The scrobbling provider referred to
[out] out True 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] 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
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] session Your 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] session Your session object
[in] track The 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] session Your session object
[in] play If 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] session Your session object
[in] track The 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] session Your session object
[in] offset Track 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] session Your 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] session Your 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] session Session object
[in] bitrate Preferred 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] 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.
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] session Your session object
[out] next_timeout Stores 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] session Your session object.
[in] canonical_username The 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] sess Session 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] session Your 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] 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
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] 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)
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] session Session object
[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 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] session Session object
[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 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] session Session object
[in] enabled True 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] session Session object
[in] provider The scrobbling provider referred to
[in] state The 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] session Session object
[in] provider The scrobbling provider referred to
[in] username The user name
[in] password The 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] session Session object
[in] on True iff volume normalization should be enabled
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] session Session 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] session Session object
[in] canonical_username Canonical 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] session Your 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] session Session 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] session Your session object
Returns:
A string representing the login username.
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

Generated on Wed Jun 13 2012 14:22:40.
Copyright © 2006–2012 Spotify Ltd