Class: Hallon::Session
Overview
The Session is fundamental for all communication with Spotify. Pretty much all API calls require you to have established a session with Spotify before using them.
Instance Attribute Summary collapse
-
#cache_size ⇒ Integer
The current session cache size (in megabytes).
-
#options ⇒ Hash
readonly
The options Hallon used at #initialize.
Attributes inherited from Base
Class Method Summary collapse
-
.connection_rules ⇒ Array<Symbol>
List of available connection rules.
-
.connection_types ⇒ Array<Symbol>
List of available connection types.
-
.initialize(appkey, options = {}) { ... } ⇒ Session
Initializes the Spotify session.
-
.instance ⇒ Session
Returns the previously initialized Session.
-
.instance? ⇒ Boolean
True if a Session instance exists.
Instance Method Summary collapse
-
#connection_rules=(connection_rules) ⇒ Object
Set the connection rules for this session.
-
#connection_type=(connection_type) ⇒ Object
Set the connection type for this session.
-
#container ⇒ PlaylistContainer?
PlaylistContainer for the currently logged in session.
-
#country ⇒ String
Currently logged in user’s country.
-
#disconnected? ⇒ Boolean
True if session has been disconnected.
-
#flush_caches ⇒ Session
Flushes the Session cache to disk.
-
#forget_me! ⇒ self
Remove stored login credentials in libspotify.
-
#inbox ⇒ Playlist?
Currently logged in user’s inbox playlist.
-
#initialize(appkey, options = {}) { ... } ⇒ Session
constructor
Create a new Spotify session.
-
#logged_in? ⇒ Boolean
True if logged in.
-
#logged_out? ⇒ Boolean
True if logged out.
-
#login(username, password, remember_me = false) ⇒ Session
Log into Spotify using the given credentials.
-
#login!(username, password, remember_me = false) ⇒ Session
Log in to Spotify using the given credentials.
-
#logout ⇒ self
Logs out of Spotify.
-
#logout! ⇒ Session
Log out the current user.
-
#offline? ⇒ Boolean
True if offline.
-
#offline_bitrate=(bitrate) ⇒ Object
Set preferred offline bitrate.
-
#offline_playlists_count ⇒ Integer
Number of playlists marked for offline sync.
-
#offline_sync_status ⇒ Hash
Offline synchronization status.
-
#offline_time_left ⇒ Integer
Remaining time left you can stay offline before needing to relogin.
-
#offline_tracks_to_sync ⇒ Integer
Number of offline tracks left to sync for offline mode.
-
#private=(is_private) ⇒ Object
(also: #britney_spears_mode=)
Set private session.
-
#private? ⇒ Boolean
(also: #britney_spears_mode?)
True if the session is currently set to private.
-
#process_events ⇒ Fixnum
Process pending Spotify events (might fire callbacks).
-
#relogin ⇒ Object
Login the remembered user (see #login).
-
#relogin! ⇒ Session
Log in the remembered user.
-
#remembered_user ⇒ String?
Username of the user stored in libspotify-remembered credentials.
-
#star(*tracks) ⇒ Session
Star the given tracks.
-
#starred ⇒ Playlist?
Currently logged in user’s starred playlist.
-
#status ⇒ Symbol
Current connection status.
-
#tracks_starred(tracks, starred) ⇒ Object
private
Set starred status of given tracks.
-
#unstar(*tracks) ⇒ Session
Unstar the given tracks.
-
#user ⇒ User
The User currently logged in.
-
#username ⇒ String?
Username of the currently logged in user.
-
#wait_until_logged_in ⇒ Object
private
Waits until we’re either logged in or a failure occurs.
Methods included from Observable::Session
connection_error_callback, connectionstate_updated_callback, credentials_blob_updated_callback, end_of_track_callback, extended, get_audio_buffer_stats_callback, initialize_callbacks, log_message_callback, logged_in_callback, logged_out_callback, message_to_user_callback, metadata_updated_callback, music_delivery_callback, notify_main_thread_callback, offline_error_callback, offline_status_updated_callback, play_token_lost_callback, private_session_mode_changed_callback, scrobble_error_callback, start_playback_callback, stop_playback_callback, streaming_error_callback, userinfo_updated_callback
Methods inherited from Base
#==, from, from_link, #is_linkable?, #session, to_link, #to_pointer, #to_s
Constructor Details
#initialize(appkey, options = {}) { ... } ⇒ Session
Create a new Spotify session.
97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 |
# File 'lib/hallon/session.rb', line 97 def initialize(appkey, = {}, &block) if [:proxy] proxy_uri = URI([:proxy]) [:proxy_username] ||= proxy_uri.user [:proxy_password] ||= proxy_uri.password proxy_uri.user = proxy_uri.password = nil [:proxy] = proxy_uri.to_s end @options = { :user_agent => "Hallon", :settings_location => "tmp/hallon/", :cache_location => "tmp/hallon/", :load_playlists => true, :compress_playlists => true, :cache_playlist_metadata => true, :device_id => nil, :proxy => nil, :proxy_username => nil, :proxy_password => nil, :tracefile => nil, }.merge() if @options[:user_agent].bytesize > 255 raise ArgumentError, "User-agent must be less than 256 bytes long" end # Default cache size is 0 (automatic) @cache_size = 0 subscribe_for_callbacks do |callbacks| # not overridable @options[:api_version] = Hallon::API_VERSION @options[:initially_unload_playlists] = ! @options.delete(:load_playlists) @options[:dont_save_metadata_for_playlists] = ! @options.delete(:cache_playlist_metadata) config = Spotify::SessionConfig.new(@options.merge(application_key: appkey, callbacks: callbacks)) instance_eval(&block) if block_given? # You pass a pointer to the session pointer to libspotify >:) FFI::MemoryPointer.new(:pointer) do |p| Error::maybe_raise Spotify.session_create(config, p) @pointer = Spotify::Session.new(p.read_pointer) end end end |
Instance Attribute Details
#cache_size ⇒ Integer
This is not provided by libspotify, and the value is only valid as long as the cache size is only adjusted through #cache_size= and not the Spotify FFI interface.
The current session cache size (in megabytes).
26 27 28 |
# File 'lib/hallon/session.rb', line 26 def cache_size @cache_size end |
#options ⇒ Hash (readonly)
The options Hallon used at #initialize.
17 18 19 |
# File 'lib/hallon/session.rb', line 17 def @options end |
Class Method Details
.connection_rules ⇒ Array<Symbol>
Returns list of available connection rules.
73 74 75 |
# File 'lib/hallon/session.rb', line 73 def self.connection_rules Spotify.enum_type(:connection_rules).symbols end |
.connection_types ⇒ Array<Symbol>
Returns list of available connection types.
68 69 70 |
# File 'lib/hallon/session.rb', line 68 def self.connection_types Spotify.enum_type(:connection_type).symbols end |
.initialize(appkey, options = {}) { ... } ⇒ Session
Initializes the Spotify session. If you need to access the instance at a later time, you can use instance.
48 49 50 51 |
# File 'lib/hallon/session.rb', line 48 def Session.initialize(appkey, = {}, &block) raise "Session has already been initialized" if defined?(@__instance__) @__instance__ = new(appkey, , &block) end |
.instance ⇒ Session
Returns the previously initialized Session.
58 59 60 |
# File 'lib/hallon/session.rb', line 58 def Session.instance @__instance__ or raise NoSessionError, "Session has not been initialized" end |
.instance? ⇒ Boolean
Returns true if a Session instance exists.
63 64 65 |
# File 'lib/hallon/session.rb', line 63 def Session.instance? !! @__instance__ end |
Instance Method Details
#connection_rules=(connection_rules) ⇒ Object
Set the connection rules for this session.
348 349 350 351 352 353 354 |
# File 'lib/hallon/session.rb', line 348 def connection_rules=(connection_rules) rules = Array(connection_rules).reduce(0) do |mask, rule| mask | Spotify.enum_value!(rule, "connection rule") end Spotify.session_set_connection_rules(pointer, rules) end |
#connection_type=(connection_type) ⇒ Object
Set the connection type for this session.
361 362 363 |
# File 'lib/hallon/session.rb', line 361 def connection_type=(connection_type) Spotify.session_set_connection_type(pointer, connection_type) end |
#container ⇒ PlaylistContainer?
returns nil if the session is not logged in.
PlaylistContainer for the currently logged in session.
158 159 160 161 |
# File 'lib/hallon/session.rb', line 158 def container container = Spotify.session_playlistcontainer(pointer) PlaylistContainer.from(container) end |
#country ⇒ String
Returns currently logged in user’s country.
304 305 306 307 308 |
# File 'lib/hallon/session.rb', line 304 def country coded = Spotify.session_user_country(pointer) country = ((coded >> 8) & 0xFF).chr country << (coded & 0xFF).chr end |
#disconnected? ⇒ Boolean
Returns true if session has been disconnected.
446 447 448 |
# File 'lib/hallon/session.rb', line 446 def disconnected? status == :disconnected end |
#flush_caches ⇒ Session
libspotify does this automatically periodically, under normal circumstances this method should not need to be used.
Flushes the Session cache to disk.
150 151 152 |
# File 'lib/hallon/session.rb', line 150 def flush_caches Spotify.session_flush_caches(pointer) end |
#forget_me! ⇒ self
If no credentials are stored nothing’ll happen.
Remove stored login credentials in libspotify.
258 259 260 |
# File 'lib/hallon/session.rb', line 258 def forget_me! tap { Spotify.session_forget_me(pointer) } end |
#inbox ⇒ Playlist?
Returns nil when no user is logged in.
Returns currently logged in user’s inbox playlist.
427 428 429 430 |
# File 'lib/hallon/session.rb', line 427 def inbox playlist = Spotify.session_inbox_create(pointer) Playlist.from(playlist) end |
#logged_in? ⇒ Boolean
Returns true if logged in.
434 435 436 |
# File 'lib/hallon/session.rb', line 434 def logged_in? status == :logged_in end |
#logged_out? ⇒ Boolean
Returns true if logged out.
440 441 442 |
# File 'lib/hallon/session.rb', line 440 def logged_out? status == :logged_out end |
#login(username, password, remember_me = false) ⇒ Session
it also supports logging in via a credentials blob, if you pass a Hallon::Blob(blob_string) as the password instead of the real password
Log into Spotify using the given credentials.
188 189 190 191 192 193 194 195 |
# File 'lib/hallon/session.rb', line 188 def login(username, password, remember_me = false) if username.empty? or password.empty? raise ArgumentError, "username and password may not be blank" end password, blob = blob, password if password.is_a?(Blob) tap { Spotify.session_login(pointer, username, password, remember_me, blob) } end |
#login!(username, password, remember_me = false) ⇒ Session
This function will not return until you’ve either logged in successfully, or until an error is raised.
Log in to Spotify using the given credentials.
213 214 215 216 |
# File 'lib/hallon/session.rb', line 213 def login!(username, password, remember_me = false) login(username, password, remember_me) tap { wait_until_logged_in } end |
#logout ⇒ self
Logs out of Spotify. Does nothing if not logged in.
265 266 267 |
# File 'lib/hallon/session.rb', line 265 def logout tap { Spotify.session_logout(pointer) if logged_in? } end |
#logout! ⇒ Session
This method will not return until you’ve logged out successfully.
Log out the current user.
234 235 236 237 |
# File 'lib/hallon/session.rb', line 234 def logout! logout tap { wait_for(:logged_out) { logged_out? } } end |
#offline? ⇒ Boolean
Returns true if offline.
452 453 454 |
# File 'lib/hallon/session.rb', line 452 def offline? status == :offline end |
#offline_bitrate=(bitrate) ⇒ Object
under normal circumstances, ArgumentError is the error that will be raised on an invalid bitrate. However, if Hallon fails the type checking (for whatever reason), libspotify will itself return an error as well.
Set preferred offline bitrate.
413 414 415 416 |
# File 'lib/hallon/session.rb', line 413 def offline_bitrate=(bitrate) bitrate, resync = Array(bitrate) Spotify.try(:session_preferred_offline_bitrate, pointer, bitrate, !! resync) end |
#offline_playlists_count ⇒ Integer
Returns number of playlists marked for offline sync.
386 387 388 |
# File 'lib/hallon/session.rb', line 386 def offline_playlists_count Spotify.offline_num_playlists(pointer) end |
#offline_sync_status ⇒ Hash
Offline synchronization status.
376 377 378 379 380 381 382 383 |
# File 'lib/hallon/session.rb', line 376 def offline_sync_status struct = Spotify::OfflineSyncStatus.new if Spotify.offline_sync_get_status(pointer, struct) struct.to_h else {} end end |
#offline_time_left ⇒ Integer
Remaining time left you can stay offline before needing to relogin.
368 369 370 |
# File 'lib/hallon/session.rb', line 368 def offline_time_left Spotify.offline_time_left(pointer) end |
#offline_tracks_to_sync ⇒ Integer
Returns number of offline tracks left to sync for offline mode.
391 392 393 |
# File 'lib/hallon/session.rb', line 391 def offline_tracks_to_sync Spotify.offline_tracks_to_sync(pointer) end |
#private=(is_private) ⇒ Object Also known as: britney_spears_mode=
mode is reverted to normal after some time without user activity, see official libspotify documentation for details.
Set private session.
291 292 293 |
# File 'lib/hallon/session.rb', line 291 def private=(is_private) Spotify.session_set_private_session(pointer, !! is_private) end |
#private? ⇒ Boolean Also known as: britney_spears_mode?
Returns true if the session is currently set to private.
281 282 283 |
# File 'lib/hallon/session.rb', line 281 def private? Spotify.session_is_private_session(pointer) end |
#process_events ⇒ Fixnum
Process pending Spotify events (might fire callbacks).
166 167 168 169 170 171 |
# File 'lib/hallon/session.rb', line 166 def process_events FFI::MemoryPointer.new(:int) do |p| Spotify.session_process_events(pointer, p) return p.read_int end end |
#relogin ⇒ Object
Login the remembered user (see #login).
201 202 203 |
# File 'lib/hallon/session.rb', line 201 def relogin Spotify.try(:session_relogin, pointer) end |
#relogin! ⇒ Session
This method will not return until you’ve either logged in successfully or until an error is raised.
Log in the remembered user.
225 226 227 228 |
# File 'lib/hallon/session.rb', line 225 def relogin! relogin tap { wait_until_logged_in } end |
#remembered_user ⇒ String?
Returns username of the user stored in libspotify-remembered credentials.
246 247 248 249 250 251 252 |
# File 'lib/hallon/session.rb', line 246 def remembered_user bufflen = Spotify.session_remembered_user(pointer, nil, 0) FFI::Buffer.alloc_out(bufflen + 1) do |b| Spotify.session_remembered_user(pointer, b, b.size) return b.get_string(0) end if bufflen > 0 end |
#star(*tracks) ⇒ Session
this method might raise a Spotify::Error, however when this might occur is not documented in libspotify (and I have yet to find any way to trigger it myself). it’s entirely possible that this method never returns an error, but we can’t know for sure.
Star the given tracks.
321 322 323 |
# File 'lib/hallon/session.rb', line 321 def star(*tracks) tap { tracks_starred(tracks, true) } end |
#starred ⇒ Playlist?
Returns nil when no user is logged in.
Returns currently logged in user’s starred playlist.
420 421 422 423 |
# File 'lib/hallon/session.rb', line 420 def starred playlist = Spotify.session_starred_create(pointer) Playlist.from(playlist) end |
#status ⇒ Symbol
Returns current connection status.
276 277 278 |
# File 'lib/hallon/session.rb', line 276 def status Spotify.session_connectionstate(pointer) end |
#tracks_starred(tracks, starred) ⇒ Object (private)
Set starred status of given tracks.
462 463 464 465 466 467 |
# File 'lib/hallon/session.rb', line 462 def tracks_starred(tracks, starred) FFI::MemoryPointer.new(:pointer, tracks.size) do |ptr| ptr.write_array_of_pointer tracks.map(&:pointer) Spotify.try(:track_set_starred, pointer, ptr, tracks.size, starred) end end |
#unstar(*tracks) ⇒ Session
this method might raise a Spotify::Error, however when this might occur is not documented in libspotify (and I have yet to find any way to trigger it myself). it’s entirely possible that this method never returns an error, but we can’t know for sure.
Unstar the given tracks.
339 340 341 |
# File 'lib/hallon/session.rb', line 339 def unstar(*tracks) tap { tracks_starred(tracks, false) } end |
#user ⇒ User
Returns the User currently logged in.
270 271 272 273 |
# File 'lib/hallon/session.rb', line 270 def user user = Spotify.session_user(pointer) User.from(user) end |
#username ⇒ String?
Returns username of the currently logged in user.
240 241 242 243 |
# File 'lib/hallon/session.rb', line 240 def username username = Spotify.session_user_name(pointer) username unless username.nil? or username.empty? end |
#wait_until_logged_in ⇒ Object (private)
475 476 477 478 479 480 |
# File 'lib/hallon/session.rb', line 475 def wait_until_logged_in wait_for(:logged_in, :connection_error) do |event, error| Error.maybe_raise(error) session.logged_in? end end |