libspotify
Data Fields
sp_session_callbacks Struct Reference

#include <api.h>

Data Fields

void(* logged_in )(sp_session *session, sp_error error)
 
void(* logged_out )(sp_session *session)
 
void(* metadata_updated )(sp_session *session)
 
void(* connection_error )(sp_session *session, sp_error error)
 
void(* message_to_user )(sp_session *session, const char *message)
 
void(* notify_main_thread )(sp_session *session)
 
int(* music_delivery )(sp_session *session, const sp_audioformat *format, const void *frames, int num_frames)
 
void(* play_token_lost )(sp_session *session)
 
void(* log_message )(sp_session *session, const char *data)
 
void(* end_of_track )(sp_session *session)
 
void(* streaming_error )(sp_session *session, sp_error error)
 
void(* userinfo_updated )(sp_session *session)
 
void(* start_playback )(sp_session *session)
 
void(* stop_playback )(sp_session *session)
 
void(* get_audio_buffer_stats )(sp_session *session, sp_audio_buffer_stats *stats)
 
void(* offline_status_updated )(sp_session *session)
 
void(* offline_error )(sp_session *session, sp_error error)
 
void(* credentials_blob_updated )(sp_session *session, const char *blob)
 
void(* connectionstate_updated )(sp_session *session)
 
void(* scrobble_error )(sp_session *session, sp_error error)
 
void(* private_session_mode_changed )(sp_session *session, bool is_private)
 

Detailed Description

Session callbacks

Registered when you create a session. If some callbacks should not be of interest, set them to NULL.

Examples:
jukebox.c.

Field Documentation

void( * sp_session_callbacks::connection_error)(sp_session *session, sp_error error)

Called when there is a connection error, and the library has problems reconnecting to the Spotify service. Could be called multiple times (as long as the problem is present)

Parameters
[in]sessionSession
[in]errorOne of the following errors, from sp_error SP_ERROR_OK SP_ERROR_CLIENT_TOO_OLD SP_ERROR_UNABLE_TO_CONTACT_SERVER SP_ERROR_BAD_USERNAME_OR_PASSWORD SP_ERROR_USER_BANNED SP_ERROR_USER_NEEDS_PREMIUM SP_ERROR_OTHER_TRANSIENT SP_ERROR_OTHER_PERMANENT
void( * sp_session_callbacks::connectionstate_updated)(sp_session *session)

Called when the connection state has updated - such as when logging in, going offline, etc.

Parameters
[in]sessionSession
void( * sp_session_callbacks::credentials_blob_updated)(sp_session *session, const char *blob)

Called when storable credentials have been updated, usually called when we have connected to the AP.

Parameters
[in]sessionSession
[in]blobBlob is a null-terminated string which contains an encrypted token that can be stored safely on disk instead of storing plaintext passwords.
void( * sp_session_callbacks::end_of_track)(sp_session *session)

End of track. Called when the currently played track has reached its end.

Note
This function is invoked from the main thread
Parameters
[in]sessionSession
void( * sp_session_callbacks::get_audio_buffer_stats)(sp_session *session, sp_audio_buffer_stats *stats)

Called to query application about its audio buffer

Note
This function is called from an internal session thread - you need to have proper synchronization!
This function must never block.
Parameters
[in]sessionSession
[out]statsStats struct to be filled by application
void( * sp_session_callbacks::log_message)(sp_session *session, const char *data)

Logging callback.

Parameters
[in]sessionSession
[in]dataLog data
void( * sp_session_callbacks::logged_in)(sp_session *session, sp_error error)

Called when login has been processed and was successful

Parameters
[in]sessionSession
[in]errorOne of the following errors, from sp_error SP_ERROR_OK SP_ERROR_CLIENT_TOO_OLD SP_ERROR_UNABLE_TO_CONTACT_SERVER SP_ERROR_BAD_USERNAME_OR_PASSWORD SP_ERROR_USER_BANNED SP_ERROR_USER_NEEDS_PREMIUM SP_ERROR_OTHER_TRANSIENT SP_ERROR_OTHER_PERMANENT
Examples:
jukebox.c.
void( * sp_session_callbacks::logged_out)(sp_session *session)

Called when logout has been processed. Either called explicitly if you initialize a logout operation, or implicitly if there is a permanent connection error

Parameters
[in]sessionSession
void( * sp_session_callbacks::message_to_user)(sp_session *session, const char *message)

Called when the access point wants to display a message to the user

In the desktop client, these are shown in a blueish toolbar just below the search box.

Parameters
[in]sessionSession
[in]messageString in UTF-8 format.
void( * sp_session_callbacks::metadata_updated)(sp_session *session)

Called whenever metadata has been updated

If you have metadata cached outside of libspotify, you should purge your caches and fetch new versions.

Parameters
[in]sessionSession
int( * sp_session_callbacks::music_delivery)(sp_session *session, const sp_audioformat *format, const void *frames, int num_frames)

Called when there is decompressed audio data available.

Parameters
[in]sessionSession
[in]formatAudio format descriptor sp_audioformat
[in]framesPoints to raw PCM data as described by format
[in]num_framesNumber of available samples in frames. If this is 0, a discontinuity has occurred (such as after a seek). The application should flush its audio fifos, etc.
Returns
Number of frames consumed. This value can be used to rate limit the output from the library if your output buffers are saturated. The library will retry delivery in about 100ms.
Note
This function is called from an internal session thread - you need to have proper synchronization!
This function must never block. If your output buffers are full you must return 0 to signal that the library should retry delivery in a short while.
void( * sp_session_callbacks::notify_main_thread)(sp_session *session)

Called when processing needs to take place on the main thread.

You need to call sp_session_process_events() in the main thread to get libspotify to do more work. Failure to do so may cause request timeouts, or a lost connection.

Parameters
[in]sessionSession
Note
This function is called from an internal session thread - you need to have proper synchronization!
void( * sp_session_callbacks::offline_error)(sp_session *session, sp_error error)

Called when offline synchronization status is updated

Parameters
[in]sessionSession
[in]errorOffline error. Will be SP_ERROR_OK if the offline synchronization error state has cleared
void( * sp_session_callbacks::offline_status_updated)(sp_session *session)

Called when offline synchronization status is updated

Parameters
[in]sessionSession
void( * sp_session_callbacks::play_token_lost)(sp_session *session)

Music has been paused because an account only allows music to be played from one location simultaneously.

Note
When this callback is invoked the application should behave just as if the user pressed the pause button. The application should also display a message to the user indicating the playback has been paused because another application is playing using the same account.
IT MUST NOT automatically resume playback but must instead wait for the user to press play.
Parameters
[in]sessionSession
void( * sp_session_callbacks::private_session_mode_changed)(sp_session *session, bool is_private)

Called when there is a change in the private session mode

Parameters
[in]sessionSession
[in]isPrivateTrue if in private session, false otherwhise
void( * sp_session_callbacks::scrobble_error)(sp_session *session, sp_error error)

Called when there is a scrobble error event

Parameters
[in]sessionSession
[in]errorScrobble error. Currently SP_ERROR_LASTFM_AUTH_ERROR.
void( * sp_session_callbacks::start_playback)(sp_session *session)

Called when audio playback should start

Note
For this to work correctly the application must also implement get_audio_buffer_stats()
This function is called from an internal session thread - you need to have proper synchronization!
This function must never block.
Parameters
[in]sessionSession
void( * sp_session_callbacks::stop_playback)(sp_session *session)

Called when audio playback should stop

Note
For this to work correctly the application must also implement get_audio_buffer_stats()
This function is called from an internal session thread - you need to have proper synchronization!
This function must never block.
Parameters
[in]sessionSession
void( * sp_session_callbacks::streaming_error)(sp_session *session, sp_error error)

Streaming error. Called when streaming cannot start or continue.

Note
This function is invoked from the main thread
Parameters
[in]sessionSession
[in]errorOne of the following errors, from sp_error SP_ERROR_NO_STREAM_AVAILABLE SP_ERROR_OTHER_TRANSIENT SP_ERROR_OTHER_PERMANENT
void( * sp_session_callbacks::userinfo_updated)(sp_session *session)

Called after user info (anything related to sp_user objects) have been updated.

Parameters
[in]sessionSession

The documentation for this struct was generated from the following file:

Generated on Tue Jun 4 2013 15:11:47.
Copyright © 2006–2013 Spotify Ltd