Session handling


Data Structures

struct  sp_audioformat
struct  sp_session_callbacks
struct  sp_session_config

Defines

#define SPOTIFY_API_VERSION   1

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 }

Functions

sp_error sp_session_init (const sp_session_config *config, sp_session **sess)
sp_error sp_session_login (sp_session *session, const char *username, const char *password)
sp_usersp_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_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_playlistcontainersp_session_playlistcontainer (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   1

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_init().

If an (upgraded) library is no longer compatible with this version the error SP_ERROR_BAD_API_VERSION will be returned from sp_session_init(). Future versions of the library will provide you with some kind of mechanism to request an updated version of the library.

Examples:
jukebox.c, and session.c.


Enumeration Type Documentation

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.

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_init ( 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

In the future, this will be renamed to sp_session_create() and will have a corresponding sp_session_release() function.

Here is a snippet from session.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 = "tmp";

    // The path of the directory to store the settings. This must be specified.
    // Please read the documentation on preferred values.
    config.settings_location = "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 = "spotify-session-example";

    // Register the callbacks.
    config.callbacks = &g_callbacks;

    error = sp_session_init(&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:
Error code sp_error
Examples:
jukebox.c, and session.c.

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

    error = sp_session_login(session, argv[1], argv[2]);

    if (SP_ERROR_OK != error) {
        fprintf(stderr, "failed to login: %s\n",
                        sp_error_message(error));
        return 3;
    }

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
Examples:
jukebox.c, and session.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.

Here is a snippet from session_ready.c:

    sp_error error = sp_session_logout(session);

    if (SP_ERROR_OK != error) {
        fprintf(stderr, "failed to log out from Spotify: %s\n",
                        sp_error_message(error));
        g_exit_code = 5;
        return;
    }

Parameters:
[in] session Your session object
Returns:
Result of the operation
Examples:
browse.c, link.c, search.c, session_ready.c, and track.c.

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
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:
The result of the operation - see the sp_error enum for possible values
Examples:
jukebox.c.

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

void sp_session_process_events ( sp_session session,
int *  next_timeout 
)

Make the specified session process any pending events

Here is a snippet from session.c:

static void loop(sp_session *session)
{
    sigset_t sigset;

    sigemptyset(&sigset);
    sigaddset(&sigset, SIGIO);

    while (g_exit_code < 0) {
        int timeout = -1;

        pthread_sigmask(SIG_BLOCK, &sigset, NULL);
        sp_session_process_events(session, &timeout);
        pthread_sigmask(SIG_UNBLOCK, &sigset, NULL);
        usleep(timeout * 1000);
    }
}

Parameters:
[in] session Your session object
[out] next_timeout Stores the time (in milliseconds) until you should call this function again
Examples:
jukebox.c, and session.c.

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)
Examples:
session.c.

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 Tue Apr 7 15:21:55 2009.
Copyright © 2006–2009 Spotify Ltd