hallon 0.8.0 → 0.9.0

data/lib/hallon/playlist_container.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+module Hallon
+  class PlaylistContainer < Base
+    class Folder
+    end
+
+    include Observable
+
+    # Wrap an existing PlaylistContainer pointer in an object.
+    #
+    # @param [Spotify::Pointer] pointer
+    def initialize(pointer)
+      @pointer = to_pointer(pointer, :playlistcontainer)
+    end
+
+    # @return [Boolean] true if the container is loaded
+    def loaded?
+      Spotify.playlistcontainer_is_loaded(pointer)
+    end
+
+    # @return [User, nil] owner of the container (nil if unknown or no owner)
+    def owner
+      owner = Spotify.playlistcontainer_owner!(pointer)
+      User.new(owner) unless owner.null?
+    end
+  end
+end

data/lib/hallon/search.rb

@@ -12,23 +12,36 @@ module Hallon
       Spotify.enum_type(:radio_genre).symbols
     end
 
+    # @return [Hash] default search parameters
+    def self.defaults
+      @defaults ||= {
+        :tracks  => 25,
+        :albums  => 25,
+        :artists => 25,
+        :tracks_offset  => 0,
+        :albums_offset  => 0,
+        :artists_offset => 0
+      }
+    end
+
     # @param [Range<Integer>] range (from_year..to_year)
     # @param [Symbol, …] genres
     # @return [Search] radio search in given period and genres
     def self.radio(range, *genres)
       from_year, to_year = range.begin, range.end
       genres = genres.reduce(0) do |mask, genre|
-        mask | (Spotify.enum_value(genre) || 0)
+        mask | Spotify.enum_value!(genre, "genre")
       end
 
       search = allocate
       search.instance_eval do
         @callback = proc { search.trigger(:load) }
-        pointer   = Spotify.radio_search_create(session.pointer, from_year, to_year, genres, @callback, nil)
-        @pointer  = Spotify::Pointer.new(pointer, :search, false)
+        @pointer   = Spotify.radio_search_create!(session.pointer, from_year, to_year, genres, @callback, nil)
 
-        self
+        raise FFI::NullPointerError, "radio search failed" if @pointer.null?
       end
+
+      search
     end
 
     # Construct a new search with given query.
@@ -43,86 +56,80 @@ module Hallon
     # @option options [#to_i] :artists_offset (0) offset of artists in search result
     # @see http://developer.spotify.com/en/libspotify/docs/group__search.html#gacf0b5e902e27d46ef8b1f40e332766df
     def initialize(query, options = {})
-      o = {
-        :tracks  => 25,
-        :albums  => 25,
-        :artists => 25,
-        :tracks_offset  => 0,
-        :albums_offset  => 0,
-        :artists_offset => 0
-      }.merge(options)
-
+      o = Search.defaults.merge(options)
       @callback = proc { trigger(:load) }
-      pointer   = Spotify.search_create(session.pointer, query, o[:tracks_offset].to_i, o[:tracks].to_i, o[:albums_offset].to_i, o[:albums].to_i, o[:artists_offset].to_i, o[:artists].to_i, @callback, nil)
-      @pointer  = Spotify::Pointer.new(pointer, :search, false)
+      @pointer = Spotify.search_create!(session.pointer, query, o[:tracks_offset].to_i, o[:tracks].to_i, o[:albums_offset].to_i, o[:albums].to_i, o[:artists_offset].to_i, o[:artists].to_i, @callback, nil)
+
+      raise FFI::NullPointerError, "search for “#{query}” failed" if @pointer.null?
     end
 
-    # @return [Boolean] true if the search has been fully loaded
+    # @return [Boolean] true if the search has been fully loaded.
     def loaded?
-      Spotify.search_is_loaded(@pointer)
+      Spotify.search_is_loaded(pointer)
     end
 
-    # @return [Symbol] error status
-    def error
-      Spotify.search_error(@pointer)
+    # @see Error.explain
+    # @return [Symbol] search error status.
+    def status
+      Spotify.search_error(pointer)
     end
 
-    # @return [String] search query this search was created with
+    # @return [String] search query this search was created with.
     def query
-      Spotify.search_query(@pointer)
+      Spotify.search_query(pointer)
     end
 
-    # @return [String] “did you mean?” suggestion for current search
+    # @return [String] “did you mean?” suggestion for current search.
     def did_you_mean
-      Spotify.search_did_you_mean(@pointer)
+      Spotify.search_did_you_mean(pointer)
     end
 
-    # @return [Enumerator<Track>] enumerate over all tracks in the search result
+    # @return [Enumerator<Track>] list of all tracks in the search result.
     def tracks
-      size = Spotify.search_num_tracks(@pointer)
+      size = Spotify.search_num_tracks(pointer)
       Enumerator.new(size) do |i|
-        track = Spotify.search_track(@pointer, i)
-        Track.new(track) unless track.null?
+        track = Spotify.search_track!(pointer, i)
+        Track.new(track)
       end
     end
 
-    # @return [Integer] total tracks available for this search query
+    # @return [Integer] total tracks available for this search query.
     def total_tracks
-      Spotify.search_total_tracks(@pointer)
+      Spotify.search_total_tracks(pointer)
     end
 
-    # @return [Enumerator<Album>] enumerate over all albums in the search result
+    # @return [Enumerator<Album>] list of all albums in the search result.
     def albums
-      size  = Spotify.search_num_albums(@pointer)
+      size  = Spotify.search_num_albums(pointer)
       Enumerator.new(size) do |i|
-        album = Spotify.search_album(@pointer, i)
-        Album.new(album) unless album.null?
+        album = Spotify.search_album!(pointer, i)
+        Album.new(album)
       end
     end
 
-    # @return [Integer] total tracks available for this search query
+    # @return [Integer] total tracks available for this search query.
     def total_albums
-      Spotify.search_total_albums(@pointer)
+      Spotify.search_total_albums(pointer)
     end
 
-    # @return [Enumerator<Artist>] enumerate over all artists in the search result
+    # @return [Enumerator<Artist>] list of all artists in the search result.
     def artists
-      size = Spotify.search_num_artists(@pointer)
+      size = Spotify.search_num_artists(pointer)
       Enumerator.new(size) do |i|
-        artist = Spotify.search_artist(@pointer, i)
-        Artist.new(artist) unless artist.null?
+        artist = Spotify.search_artist!(pointer, i)
+        Artist.new(artist)
       end
     end
 
-    # @return [Integer] total tracks available for this search query
+    # @return [Integer] total tracks available for this search query.
     def total_artists
-      Spotify.search_total_artists(@pointer)
+      Spotify.search_total_artists(pointer)
     end
 
-    # @return [Link] link for this search query
+    # @return [Link] link for this search query.
     def to_link
-      pointer = Spotify.link_create_from_search(@pointer)
-      Link.new(pointer) unless pointer.null?
+      link = Spotify.link_create_from_search!(pointer)
+      Link.new(link) unless link.null?
     end
   end
 end

data/lib/hallon/session.rb

@@ -37,30 +37,38 @@ module Hallon
     # instance at a later time, you can use {instance}.
     #
     # @see Session.instance
-    # @see Session#initialize
     #
     # @param (see Session#initialize)
+    # @option (see Session#initialize)
+    # @yield (see Session#initialize)
+    # @raise (see Session#initialize)
+    # @see (see Session#initialize)
     # @return [Session]
-    def Session.initialize(*args, &block)
+    def Session.initialize(appkey, options = {}, &block)
       raise "Session has already been initialized" if @__instance__
-      @__instance__ = new(*args, &block)
+      @__instance__ = new(appkey, options, &block)
     end
 
     # Returns the previously initialized Session.
     #
-    # @see Session.instance
+    # @see Session.initialize
     #
     # @return [Session]
     def Session.instance
       @__instance__ or raise "Session has not been initialized"
     end
 
+    # @return [Boolean] true if a Session instance exists.
+    def Session.instance?
+      !! @__instance__
+    end
+
     # @return [Array<Symbol>] list of available connection types.
     def self.connection_types
       Spotify.enum_type(:connection_type).symbols
     end
 
-    # @return [Array<Symbol>] list of available connection rules
+    # @return [Array<Symbol>] list of available connection rules.
     def self.connection_rules
       Spotify.enum_type(:connection_rules).symbols
     end
@@ -69,13 +77,15 @@ module Hallon
     #
     # @param [#to_s] appkey
     # @param [Hash] options
-    # @option options [String] :user_agent ("Hallon") User-Agent to use (length < 256)
+    # @option options [String] :user_agent ("Hallon") User-Agent to use (length < `256`)
     # @option options [String] :settings_path ("tmp") where to save settings and user-specific cache
-    # @option options [String] :cache_path ("") where to save cache files (set to "" to disable)
+    # @option options [String] :cache_path ("") where to save cache files (`""` to disable)
+    # @option options [String] :tracefile (nil) path to libspotify API tracefile (`nil` to disable)
+    # @option options [String] :device_id (nil) device ID for offline synchronization (`nil` to disable)
     # @option options [Bool]   :load_playlists (true) load playlists into RAM on startup
     # @option options [Bool]   :compress_playlists (true) compress local copies of playlists
     # @option options [Bool]   :cache_playlist_metadata (true) cache metadata for playlists locally
-    # @yield allows you to define handlers for events (see {Hallon::Base#on})
+    # @yield allows you to define handlers for events (see {Observable#on})
     # @raise [ArgumentError] if `options[:user_agent]` is more than 256 characters long
     # @raise [Hallon::Error] if `sp_session_create` fails
     # @see http://developer.spotify.com/en/libspotify/docs/structsp__session__config.html
@@ -86,7 +96,9 @@ module Hallon
         :cache_path => "",
         :load_playlists => true,
         :compress_playlists => true,
-        :cache_playlist_metadata => true
+        :cache_playlist_metadata => true,
+        :device_id => nil,
+        :tracefile => nil,
       }.merge(options)
 
       if @options[:user_agent].bytesize > 255
@@ -94,7 +106,7 @@ module Hallon
       end
 
       # Set configuration, as well as callbacks
-      config  = Spotify::SessionConfig.new
+      config = Spotify::SessionConfig.new
       config[:api_version]   = Hallon::API_VERSION
       config.application_key = appkey
       @options.each { |(key, value)| config.send(:"#{key}=", value) }
@@ -112,12 +124,21 @@ module Hallon
       end
     end
 
+    # PlaylistContainer for the currently logged in session.
+    #
+    # @note returns nil if the session is not logged in.
+    # @return [PlaylistContainer, nil]
+    def container
+      container = Spotify.session_playlistcontainer!(pointer)
+      PlaylistContainer.new(container) unless container.null?
+    end
+
     # Process pending Spotify events (might fire callbacks).
     #
-    # @return [Fixnum] minimum time until it should be called again
+    # @return [Fixnum] time (in milliseconds) until it should be called again
     def process_events
       FFI::MemoryPointer.new(:int) do |p|
-        Spotify.session_process_events(@pointer, p)
+        Spotify.session_process_events(pointer, p)
         return p.read_int
       end
     end
@@ -138,8 +159,8 @@ module Hallon
 
         loop do
           begin
-            process_events
-            params = Timeout::timeout(0.25) { channel.pop }
+            timeout = [process_events.fdiv(1000), 5].min # scope to five seconds
+            params = Timeout::timeout(timeout) { channel.pop }
             redo if params == :notify
           rescue Timeout::Error
             params = :timeout
@@ -158,25 +179,57 @@ module Hallon
     # @param [String] username
     # @param [String] password
     # @param [Boolean] remember_me have libspotify remember credentials for {#relogin}
-    # @return [self]
+    # @return [Session]
+    # @see login!
     def login(username, password, remember_me = false)
-      tap { Spotify.session_login(@pointer, username, password, @remembered = remember_me) }
+      tap { Spotify.session_login(pointer, username, password, remember_me) }
     end
 
     # Login the remembered user (see {#login}).
     #
     # @raise [Hallon::Error] if no credentials are stored in libspotify
+    # @see #relogin!
     def relogin
-      Error.maybe_raise Spotify.session_relogin(@pointer)
+      Error.maybe_raise Spotify.session_relogin(pointer)
     end
 
-    # Username of the user stored in libspotify-remembered credentials.
+    # Log in to Spotify using the given credentials.
     #
-    # @return [String]
+    # @note This function will not return until you’ve either logged in successfully,
+    #       or until an error is raised.
+    # @param (see #login)
+    # @return [Session]
+    # @raise [Error] if failed to log in
+    # @see #login
+    def login!(username, password, remember_me = false)
+      login(username, password, remember_me)
+      tap { wait_until_logged_in }
+    end
+
+    # Log in the remembered user.
+    #
+    # @note This method will not return until you’ve either logged in successfully
+    #       or until an error is raised.
+    # @return [Session]
+    # @raise [Error] if failed to log in
+    # @see #relogin
+    def relogin!
+      tap { relogin; wait_until_logged_in }
+    end
+
+    # Log out the current user.
+    #
+    # @note This method will not return until you’ve logged out successfully.
+    # @return [Session]
+    def logout!
+      tap { logout; wait_for(:logged_out) { logged_out? } }
+    end
+
+    # @return [String] username of the user stored in libspotify-remembered credentials.
     def remembered_user
-      bufflen = Spotify.session_remembered_user(@pointer, nil, 0)
+      bufflen = Spotify.session_remembered_user(pointer, nil, 0)
       FFI::Buffer.alloc_out(bufflen + 1) do |b|
-        Spotify.session_remembered_user(@pointer, b, b.size)
+        Spotify.session_remembered_user(pointer, b, b.size)
         return b.get_string(0)
       end if bufflen > 0
     end
@@ -186,35 +239,25 @@ module Hallon
     # @note If no credentials are stored nothing’ll happen.
     # @return [self]
     def forget_me!
-      tap { Spotify.session_forget_me(@pointer) }
+      tap { Spotify.session_forget_me(pointer) }
     end
 
     # Logs out of Spotify. Does nothing if not logged in.
     #
     # @return [self]
     def logout
-      tap { Spotify.session_logout(@pointer) if logged_in? }
+      tap { Spotify.session_logout(pointer) if logged_in? }
     end
 
-    # Retrieve the currently logged in {User}.
-    #
-    # @return [User]
+    # @return [User] the User currently logged in.
     def user
-      User.new Spotify.session_user(@pointer)
-    end
-
-    # Retrieve the relation type between logged in {User} and `user`.
-    #
-    # @return [Symbol] :unknown, :none, :unidirectional or :bidirectional
-    def relation_type?(user)
-      Spotify.user_relation_type(@pointer, user.pointer)
+      user = Spotify.session_user!(pointer)
+      User.new(user) unless user.null?
     end
 
-    # Retrieve current connection status.
-    #
-    # @return [Symbol]
+    # @return [Symbol] current connection status.
     def status
-      Spotify.session_connectionstate(@pointer)
+      Spotify.session_connectionstate(pointer)
     end
 
     # Set session cache size in megabytes.
@@ -222,12 +265,12 @@ module Hallon
     # @param [Integer]
     # @return [Integer]
     def cache_size=(size)
-      Spotify.session_set_cache_size(@pointer, @cache_size = size)
+      Spotify.session_set_cache_size(pointer, @cache_size = size)
     end
 
-    # @return [String] Currently logged in users’ country.
+    # @return [String] currently logged in users’ country.
     def country
-      coded = Spotify.session_user_country(@pointer)
+      coded = Spotify.session_user_country(pointer)
       country = ((coded >> 8) & 0xFF).chr
       country << (coded & 0xFF).chr
     end
@@ -256,35 +299,16 @@ module Hallon
       tap { tracks_starred(tracks, false) }
     end
 
-    # @note This will be 0 if not logged in.
-    # @note As of current writing, I am unsure if there’s a good way to find out
-    #       when this enumerator will be populated. No callbacks or other status
-    #       field can tell you when the current sessions’ friends are available.
-    # @return [Enumerator<User>] friends of currently logged in user
-    def friends
-      size = if logged_in?
-        # segfaults unless logged in
-        Spotify.session_num_friends(@pointer)
-      else
-        0
-      end
-
-      Enumerator.new(size) do |i|
-        friend = Spotify.session_friend(@pointer, i)
-        User.new(friend)
-      end
-    end
-
     # Set the connection rules for this session.
     #
     # @param [Symbol, …] connection_rules
     # @see Session.connection_rules
     def connection_rules=(connection_rules)
       rules = Array(connection_rules).reduce(0) do |mask, rule|
-        mask | (Spotify.enum_value(rule) || 0)
+        mask | Spotify.enum_value!(rule, "connection rule")
       end
 
-      Spotify.session_set_connection_rules(@pointer, rules)
+      Spotify.session_set_connection_rules(pointer, rules)
     end
 
     # Set the connection type for this session.
@@ -292,14 +316,14 @@ module Hallon
     # @param [Symbol] connection_type
     # @see Session.connection_types
     def connection_type=(connection_type)
-      Spotify.session_set_connection_type(@pointer, connection_type)
+      Spotify.session_set_connection_type(pointer, connection_type)
     end
 
     # Remaining time left you can stay offline before needing to relogin.
     #
     # @return [Integer] offline time left in seconds
     def offline_time_left
-      Spotify.offline_time_left(@pointer)
+      Spotify.offline_time_left(pointer)
     end
 
     # Offline synchronization status.
@@ -308,23 +332,19 @@ module Hallon
     # @see http://developer.spotify.com/en/libspotify/docs/structsp__offline__sync__status.html
     def offline_sync_status
       struct = Spotify::OfflineSyncStatus.new
-      if Spotify.offline_sync_get_status(@pointer, struct.pointer)
+      if Spotify.offline_sync_get_status(pointer, struct.pointer)
         Hash[struct.members.zip(struct.values)]
       end
     end
 
-    # Number of playlists marked for offline sync.
-    #
-    # @return [Integer]
+    # @return [Integer] number of playlists marked for offline sync.
     def offline_playlists_count
-      Spotify.offline_num_playlists(@pointer)
+      Spotify.offline_num_playlists(pointer)
     end
 
-    # Number of offline tracks left to sync for offline mode.
-    #
-    # @return [Integer]
+    # @return [Integer] number of offline tracks left to sync for offline mode.
     def offline_tracks_to_sync
-      Spotify.offline_tracks_to_sync(@pointer)
+      Spotify.offline_tracks_to_sync(pointer)
     end
 
     # Set preferred offline bitrate.
@@ -337,36 +357,48 @@ module Hallon
     # @see Player.bitrates
     def offline_bitrate=(bitrate)
       bitrate, resync = Array(bitrate)
-      Spotify.session_preferred_offline_bitrate(@pointer, bitrate, !! resync)
+      Spotify.session_preferred_offline_bitrate(pointer, bitrate, !! resync)
+    end
+
+    # @note Returns nil when no user is logged in.
+    # @return [Playlist, nil] currently logged in user’s starred playlist.
+    def starred
+      playlist = Spotify.session_starred_create!(pointer)
+      Playlist.new(playlist) unless playlist.null?
+    end
+
+    # @note Returns nil when no user is logged in.
+    # @return [Playlist, nil] currently logged in user’s inbox playlist.
+    def inbox
+      playlist = Spotify.session_inbox_create!(pointer)
+      Playlist.new(playlist) unless playlist.null?
     end
 
-    # True if currently logged in.
     # @see #status
+    # @return [Boolean] true if logged in.
     def logged_in?
       status == :logged_in
     end
 
-    # True if logged out.
     # @see #status
+    # @return [Boolean] true if logged out.
     def logged_out?
       status == :logged_out
     end
 
-    # True if session has been disconnected.
     # @see #status
+    # @return [Boolean] true if session has been disconnected.
     def disconnected?
       status == :disconnected
     end
 
-    # True if offline.
     # @see #status
+    # @return [Boolean] true if offline.
     def offline?
       status == :offline
     end
 
-    # String representation of the Session.
-    #
-    # @return [String]
+    # @return [String] string representation of the Session.
     def to_s
       "<#{self.class.name}:0x#{object_id.to_s(16)} status=#{status} @options=#{options.inspect}>"
     end
@@ -382,5 +414,21 @@ module Hallon
           Spotify.track_set_starred(pointer, ptr, tracks.size, starred)
         end
       end
+
+      # Waits until we’re either logged in or a failure occurs.
+      #
+      # @note You must call {#login} or {#relogin} before you call this method, or
+      #       it will hang forever!
+      # @see login!
+      # @see relogin!
+      def wait_until_logged_in
+        # if the user does not have premium, libspotify will still fire logged_in as :ok,
+        # but a few moments later it fires connection_error; waiting for both and checking
+        # for errors on both hopefully circumvents this!
+        wait_for(:logged_in, :connection_error) do |_, error|
+          Error.maybe_raise(error)
+          session.logged_in?
+        end
+      end
   end
 end