spotify 12.5.3 → 12.6.0

data/lib/spotify/api/toplist_browse.rb

@@ -1,17 +1,88 @@
 module Spotify
   class API
     # @!group ToplistBrowse
+
+    # Initiate a request for browsing a toplist.
+    #
+    # @example
+    #   callback = proc { |toplist_browse| puts "Toplist query finished!" }
+    #   toplist_browse = Spotify.toplistbrowse_create(session, :tracks, :everywhere, nil, callback, nil)
+    #
+    # @example for sweden
+    #   callback = proc { |toplist_browse| puts "Toplist query finished!" }
+    #   toplist_browse = Spotify.toplistbrowse_create(session, :tracks, Spotify::CountryCode.to_native("SE", nil), nil, callback, nil)
+    #
+    # @note it is *very* important that the callback is not garbage collected before it is called!
+    # @param [Session] session
+    # @param [Symbol] type one of :artists, :albums, :tracks
+    # @param [Symbol] region :everywhere, :user, or a CountryCode
+    # @param [String, nil] username if region is :user this is the user to get toplists for, use nil for currently logged in user
+    # @param [Proc<ToplistBrowse, FFI::Pointer>] callback
+    # @param [FFI::Pointer] userdata
+    # @method toplistbrowse_create(session, type, region, username, callback, userdata)
     attach_function :toplistbrowse_create, [ Session, :toplisttype, :toplistregion, UTF8String, :toplistbrowse_complete_cb, :userdata ], ToplistBrowse
+
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Boolean] true if toplist request has finished loading
+    # @method toplistbrowse_is_loaded(toplist_browse)
     attach_function :toplistbrowse_is_loaded, [ ToplistBrowse ], :bool
-    attach_function :toplistbrowse_error, [ ToplistBrowse ], :error
+
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Symbol] error code
+    # @method toplistbrowse_error(toplist_browse)
+    attach_function :toplistbrowse_error, [ ToplistBrowse ], APIError
+
+    # @see #toplistbrowse_is_loaded
+    # @note if the toplist is not loaded, the function always return 0.
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Integer] number of artists in the toplist result
+    # @method toplistbrowse_num_artists(toplist_browse)
     attach_function :toplistbrowse_num_artists, [ ToplistBrowse ], :int
+
+    # @see #toplistbrowse_num_artists
+    # @note if index is out of range, the function always return nil.
+    # @param [ToplistBrowse] toplist_browse
+    # @param [Integer] index number between 0...{#toplistbrowse_num_artists}
+    # @return [Artist, nil] artist at index
+    # @method toplistbrowse_artist(toplist_browse, :int)
     attach_function :toplistbrowse_artist, [ ToplistBrowse, :int ], Artist
+
+    # @see #toplistbrowse_is_loaded
+    # @note if the toplist is not loaded, the function always return 0.
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Integer] number of albums in the toplist result
+    # @method toplistbrowse_num_albums(toplist_browse)
     attach_function :toplistbrowse_num_albums, [ ToplistBrowse ], :int
+
+    # @see #toplistbrowse_num_albums
+    # @note if index is out of range, the function always return nil.
+    # @param [ToplistBrowse] toplist_browse
+    # @param [Integer] index number between 0...{#toplistbrowse_num_albums}
+    # @return [Album, nil] album at index
+    # @method toplistbrowse_album(toplist_browse, index)
     attach_function :toplistbrowse_album, [ ToplistBrowse, :int ], Album
+
+    # @see #toplistbrowse_is_loaded
+    # @note if the toplist is not loaded, the function always return 0.
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Integer] number of tracks in the toplist result
+    # @method toplistbrowse_num_tracks(toplist_browse)
     attach_function :toplistbrowse_num_tracks, [ ToplistBrowse ], :int
+
+    # @see #toplistbrowse_num_tracks
+    # @note if index is out of range, the function always return nil.
+    # @param [ToplistBrowse] toplist_browse
+    # @param [Integer] index number between 0...{#toplistbrowse_num_tracks}
+    # @return [Track, nil] track at index
+    # @method toplistbrowse_track(toplist_browse, index)
     attach_function :toplistbrowse_track, [ ToplistBrowse, :int ], Track
+
+    # @param [ToplistBrowse] toplist_browse
+    # @return [Integer] the time in ms that was spent waiting for Spotify backend to serve request, or -1 if served from cache
+    # @method toplistbrowse_backend_request_duration(toplist_browse)
     attach_function :toplistbrowse_backend_request_duration, [ ToplistBrowse ], :int
-    attach_function :toplistbrowse_add_ref, [ ToplistBrowse ], :error
-    attach_function :toplistbrowse_release, [ ToplistBrowse ], :error
+
+    attach_function :toplistbrowse_add_ref, [ ToplistBrowse ], APIError
+    attach_function :toplistbrowse_release, [ ToplistBrowse ], APIError
   end
 end

data/lib/spotify/api/track.rb

@@ -1,26 +1,156 @@
 module Spotify
   class API
     # @!group Track
+
+    # @param [Track] track
+    # @return [Boolean] true if track has finished loading
+    # @method track_is_loaded(track)
     attach_function :track_is_loaded, [ Track ], :bool
-    attach_function :track_error, [ Track ], :error
+
+    # @param [Track] track
+    # @return [Symbol] error code
+    # @method track_error(track)
+    attach_function :track_error, [ Track ], APIError
+
+    # @see #track_is_loaded
+    # @note if the track is not loaded, the function always return :unavailable.
+    # @param [Session] session
+    # @param [Track] track
+    # @return [Symbol] track availability, one of :unavailable, :available, :not_streamable, :banned_by_artist
+    # @method track_get_availability(session, track)
     attach_function :track_get_availability, [ Session, Track ], :track_availability
+
+    # @note if the track is not loaded, the function always return false.
+    # @param [Session] session
+    # @param [Track] track
+    # @return [Boolean] true if the track is a local track
+    # @method track_is_local(session, track)
     attach_function :track_is_local, [ Session, Track ], :bool
+
+    # @note if the track is not loaded, the function always return false.
+    # @param [Session] session
+    # @param [Track] track
+    # @return [Boolean] true if the track is automatically linked to another playable version of the track
+    # @method track_is_autolinked(session, track)
     attach_function :track_is_autolinked, [ Session, Track ], :bool
+
+    # @note if the track is not loaded, the function always return false.
+    # @param [Session] session
+    # @param [Track] track
+    # @return [Boolean] true if the track is starred by the current user
+    # @method track_is_starred(session, track)
     attach_function :track_is_starred, [ Session, Track ], :bool
-    attach_function :track_set_starred, [ Session, :array, :int, :bool ], :error
+
+    # Star or unstar a list of tracks.
+    #
+    # @example
+    #   Spotify.track_set_starred(session, [track_a, track_b], true) => :ok
+    #
+    # @param [Session] session
+    # @param [Array<Track>] tracks
+    # @param [Boolean] starred true if tracks should be starred, false if unstarred
+    # @return [Symbol] error code
+    # @method track_set_starred(session, tracks, starred)
+    attach_function :track_set_starred, [ Session, :array, :int, :bool ], APIError do |session, tracks, starred|
+      tracks = Array(tracks)
+
+      with_buffer(Spotify::Track, size: tracks.length) do |tracks_buffer|
+        tracks_buffer.write_array_of_pointer(tracks)
+        sp_track_set_starred(session, tracks_buffer, tracks.length, starred)
+      end
+    end
+
+    # @note if the track is not loaded, the function always return 0.
+    # @param [Track] track
+    # @return [Integer] number of artists performing the track
+    # @method track_num_artists(track)
     attach_function :track_num_artists, [ Track ], :int
+
+    # @see #track_num_artists
+    # @note if index is out of range, the function always return nil.
+    # @param [Track] track
+    # @param [Integer] index number between 0...{#track_num_artists}
+    # @return [Artist, nil] artist at index
+    # @method track_artist(track, index)
     attach_function :track_artist, [ Track, :int ], Artist
+
+    # @note if the track is not loaded, the function always return nil.
+    # @param [Track] track
+    # @return [Album, nil] album of the track
+    # @method track_album(track)
     attach_function :track_album, [ Track ], Album
+
+    # @note if the track is not loaded, the function always return an empty string.
+    # @param [Track] track
+    # @return [String] track name
+    # @method track_name(track)
     attach_function :track_name, [ Track ], UTF8String
+
+    # @note if the track is not loaded, the function always return 0.
+    # @param [Track] track
+    # @return [Integer] duration of the track in milliseconds
+    # @method track_duration(track)
     attach_function :track_duration, [ Track ], :int
+
+    # @note if the track is not loaded, the function always return 0.
+    # @param [Track] track
+    # @return [Integer] popularity of the track, 0..100
+    # @method track_popularity(track)
     attach_function :track_popularity, [ Track ], :int
+
+    # @note The function only returns valid data for tracks appearing in an ArtistBrowse or AlbumBrowse result.
+    # @note if the disc is not available, the function always return 0.
+    # @param [Track] track
+    # @return [Integer] disc number for the track, 1..(total number of discs on album)
+    # @method track_disc(track)
     attach_function :track_disc, [ Track ], :int
+
+    # @note The function only returns valid data for tracks appearing in an ArtistBrowse or AlbumBrowse result.
+    # @note if the disc is not available, the function always return 0.
+    # @param [Track] track
+    # @return [Integer] position of track on it's disc, starts at 1
+    # @method track_index(track)
     attach_function :track_index, [ Track ], :int
+
+    # Placeholder tracks are a way to store non-track items in a playlist.
+    #
+    # This is used when sending playlists to users, for example.
+    #
+    # @see #link_create_from_track
+    # @note the track does not need to be loaded for this function to return a correct value.
+    # @note use {#link_create_from_track} to get a link to the wrapped item.
+    # @param [Track] track
+    # @return [Boolean] true if track is a placeholder
+    # @method track_is_placeholder(track)
     attach_function :track_is_placeholder, [ Track ], :bool
+
+    # @note If the track has been autolinked, the returned track will not be the same track.
+    # @param [Session] session
+    # @param [Track] track
+    # @return [Track] the actual track that will be played if track is scheduled for playback
+    # @method track_get_playable(session, track)
     attach_function :track_get_playable,  [ Session, Track ], Track
+
+    # @param [Track] track
+    # @return [Symbol] offline status of track, one of :no, :waiting, :downloading, :done, :error, :done_expired, :limit_exceeded, :done_resync
+    # @method track_offline_get_status(track)
     attach_function :track_offline_get_status, [ Track ], :track_offline_status
+
+    # Create a local Track reference, whatever that means.
+    #
+    # @example
+    #   track = Spotify.localtrack_create("Indianer", "The Best Of Indianer", "Armonia", 343_000)
+    #   # track spotify URI is: spotify:local:Indianer:Armonia:The+Best+Of+Indianer:34
+    #
+    # @param [String] artist
+    # @param [String] title
+    # @param [String] album
+    # @param [Integer] duration in milliseconds, or -1 if not available
+    # @return [Track]
+    # @method localtrack_create(artist, title, album, duration)
     attach_function :localtrack_create, [ UTF8String, UTF8String, UTF8String, :int ], Track
-    attach_function :track_add_ref, [ Track ], :error
-    attach_function :track_release, [ Track ], :error
+
+    attach_function :track_add_ref, [ Track ], APIError
+    attach_function :track_release, [ Track ], APIError
   end
 end

data/lib/spotify/api/user.rb

@@ -1,10 +1,26 @@
 module Spotify
   class API
     # @!group User
+
+    # @param [User] user
+    # @return [String] canonical username of user, the one used by Spotify in just about all places
+    # @method user_canonical_name(user)
     attach_function :user_canonical_name, [ User ], UTF8String
+
+    # @note #user_is_loaded can return true even if libspotify does not know the display name yet.
+    # @note if libspotify does not have a display name, the function will return the canonical name of the user.
+    # @param [User] user
+    # @return [String] display name of user
+    # @method user_display_name(user)
     attach_function :user_display_name, [ User ], UTF8String
+
+    # @note the function may return true, even if display name is not yet known, make sure to {#session_process_events}!
+    # @param [Track] track
+    # @return [Boolean] true if user has finished loading
+    # @method user_is_loaded(user)
     attach_function :user_is_loaded, [ User ], :bool
-    attach_function :user_add_ref, [ User ], :error
-    attach_function :user_release, [ User ], :error
+
+    attach_function :user_add_ref, [ User ], APIError
+    attach_function :user_release, [ User ], APIError
   end
 end

data/lib/spotify/api_helpers.rb

@@ -0,0 +1,47 @@
+module Spotify
+  # Some methods used in the implementation that makes the C calls
+  # less insane to make.
+  #
+  # @private
+  module APIHelpers
+    module_function
+
+    # Allocate some memory and yield it to the given block.
+    #
+    # @param type
+    # @param [Hash] options
+    # @option options [Integer] :size (1)
+    # @option options [Boolean] :clear (false)
+    def with_buffer(type, options = {})
+      size = options.fetch(:size, 1)
+      clear = options.fetch(:clear, false)
+
+      if size > 0
+        FFI::MemoryPointer.new(type, size, clear) do |buffer|
+          return yield buffer, buffer.size
+        end
+      end
+    end
+
+    # Allocate some memory, specifically for a string, and yield it to the given block.
+    #
+    # @param [Integer] length
+    # @param [Hash] options
+    # @option options [Boolean] :clear (false)
+    def with_string_buffer(length, *args)
+      if length > 0
+        with_buffer(:char, size: length + 1) do |buffer, size|
+          error = yield buffer, size
+
+          if error.is_a?(Symbol) and error != :ok
+            ""
+          else
+            buffer.get_string(0, length).force_encoding(Encoding::UTF_8)
+          end
+        end
+      else
+        ""
+      end
+    end
+  end
+end

data/lib/spotify/data_converters.rb

@@ -0,0 +1,7 @@
+require 'spotify/data_converters/utf8_string'
+require 'spotify/data_converters/utf8_string_pointer'
+require 'spotify/data_converters/image_id'
+require 'spotify/data_converters/byte_string'
+require 'spotify/data_converters/best_effort_string'
+require 'spotify/data_converters/country_code'
+require 'spotify/data_converters/type_safety'

data/lib/spotify/{types → data_converters}/best_effort_string.rb

@@ -14,7 +14,7 @@ module Spotify
       # @param ctx
       # @return [String] value, up until the first NULL byte
       def to_native(value, ctx)
-        value && value.dup.force_encoding("BINARY")[/[^\x00]*/n]
+        value && value.dup.force_encoding(Encoding::BINARY)[/[^\x00]*/n]
       end
     end
   end

data/lib/spotify/data_converters/country_code.rb

@@ -0,0 +1,30 @@
+module Spotify
+  # A type for converting a country code to an int, and vice versa.
+  module CountryCode
+    extend FFI::DataConverter
+    native_type FFI::Type::INT
+
+    # String#pack format used by libspotify for storing country code.
+    PACK_FORMAT = "s>"
+
+    class << self
+      # Given a two-char country code, encodes it to an integer.
+      #
+      # @param [String, nil] country_code
+      # @param ctx
+      # @return [Integer] country code as int
+      def to_native(country_code, ctx)
+        country_code.unpack(PACK_FORMAT)[0]
+      end
+
+      # Given a two-char country code as int, decodes it to a string.
+      #
+      # @param [Integer] country_code
+      # @param ctx
+      # @return [String] country code as string
+      def from_native(country_code, ctx)
+        [country_code].pack(PACK_FORMAT)
+      end
+    end
+  end
+end

data/lib/spotify/{types → data_converters}/image_id.rb

@@ -38,7 +38,7 @@ module Spotify
       # @param ctx
       # @return [String, nil] the image ID as a string, or nil
       def from_native(value, ctx)
-        value.read_string(size) unless value.null?
+        value.get_bytes(0, size) unless value.null?
       end
 
       # @see NulString.reference_required?

data/lib/spotify/{types → data_converters}/utf8_string.rb

@@ -18,7 +18,7 @@ module Spotify
       # @param ctx
       # @return [String] value, but in UTF-8 if it wasn’t already
       def to_native(value, ctx)
-        value && value.encode('UTF-8')
+        value && value.encode(Encoding::UTF_8)
       end
 
       # Given an original string, assume it is in UTF-8.
@@ -28,7 +28,7 @@ module Spotify
       # @param ctx
       # @return [String] value, but with UTF-8 encoding
       def from_native(value, ctx)
-        value && value.force_encoding('UTF-8')
+        value && value.force_encoding(Encoding::UTF_8)
       end
     end
   end

data/lib/spotify/{types → data_converters}/utf8_string_pointer.rb

@@ -16,7 +16,7 @@ module Spotify
       # @param ctx
       # @return [FFI::Pointer]
       def to_native(value, ctx)
-        value && FFI::MemoryPointer.from_string(value.to_str.encode("UTF-8"))
+        value && FFI::MemoryPointer.from_string(value.to_str.encode(Encoding::UTF_8))
       end
 
       # Given a pointer, read out it’s string.
@@ -25,7 +25,7 @@ module Spotify
       # @param ctx
       # @return [String, nil]
       def from_native(value, ctx)
-        value.read_string.force_encoding("UTF-8") unless value.null?
+        value.read_string.force_encoding(Encoding::UTF_8) unless value.null?
       end
 
       # Used by FFI::StructLayoutField to know if this field

data/lib/spotify/error.rb

@@ -1,65 +1,198 @@
 module Spotify
   # A generic error class for Spotify errors.
   class Error < StandardError
-    class << self
-      # Explain a Spotify error with a descriptive message.
-      #
-      # @note this method calls the API directly, since the
-      #       underlying API call is considered thread-safe.
-      #
-      # @param [Symbol, Integer] error
-      # @return [String] a decriptive string of the error
-      def explain(error)
-        error, symbol = disambiguate(error)
+  end
 
-        message = []
-        message << "[#{symbol.to_s.upcase}]"
-        message << Spotify::API.error_message(error)
-        message << "(#{error})"
+  # @abstract Generic error class, extended by all libspotify errors.
+  class APIError < Spotify::Error
+    extend FFI::DataConverter
+    native_type :int
 
-        message.join(' ')
-      end
+    @@code_to_class = { 0 => nil }
 
-      # Given a number or a symbol, find both the symbol and the error
-      # number it represents.
-      #
-      # @example given an integer
-      #   Spotify::Error.disambiguate(0) # => [0, :ok]
-      #
-      # @example given a symbol
-      #   Spotify::Error.disambiguate(:ok) # => [0, :ok]
-      #
-      # @example given bogus
-      #   Spotify::Error.disambiguate(:bogus) # => [-1, nil]
+    class << self
+      # Returns an error if applicable.
       #
-      # @param [Symbol, Fixnum] error
-      # @return [[Fixnum, Symbol]] (error code, error symbol)
-      def disambiguate(error)
-        @enum ||= Spotify.enum_type(:error)
-
-        if error.is_a? Symbol
-          error = @enum[symbol = error]
-        else
-          symbol = @enum[error]
+      # @param [Integer] error
+      # @return [Error, nil] an error, unless error symbol was OK
+      def from_native(error, context)
+        error_class = @@code_to_class.fetch(error) do
+          raise ArgumentError, "unknown error code: #{error}"
         end
+        error_class.new if error_class
+      end
 
-        if error.nil? || symbol.nil?
-          [-1, nil]
+      # From an error, retrieve it's native value.
+      #
+      # @param [Error] error
+      # @return [Symbol]
+      def to_native(error, context)
+        if error
+          error.to_i
         else
-          [error, symbol]
+          0
         end
       end
-    end
 
-    # Overridden to allow raising errors with just an error code.
-    #
-    # @param [Integer, String] code_or_message spotify error code, or string message.
-    def initialize(code_or_message = nil)
-      if code_or_message.is_a?(Integer) or code_or_message.is_a?(Symbol)
-        code_or_message &&= self.class.explain(code_or_message)
+      # @return [Integer] error code
+      attr_reader :to_i
+
+      private
+
+      def error_code(number)
+        @to_i = number
+        @@code_to_class[number] = self
       end
+    end
 
-      super(code_or_message)
+    # @param [String] message only to be supplied if overridden
+    def initialize(message = "#{Spotify::API.error_message(self)} (#{to_i})")
+      super
     end
+
+    # @return (see .to_i)
+    def to_i
+      self.class.to_i
+    end
+  end
+
+  class BadAPIVersionError < APIError
+    error_code 1
+  end
+
+  class APIInitializationFailedError < APIError
+    error_code 2
+  end
+
+  class TrackNotPlayableError < APIError
+    error_code 3
+  end
+
+  class BadApplicationKeyError < APIError
+    error_code 5
+  end
+
+  class BadUsernameOrPasswordError < APIError
+    error_code 6
+  end
+
+  class UserBannedError < APIError
+    error_code 7
+  end
+
+  class UnableToContactServerError < APIError
+    error_code 8
+  end
+
+  class ClientTooOldError < APIError
+    error_code 9
+  end
+
+  class OtherPermanentError < APIError
+    error_code 10
+  end
+
+  class BadUserAgentError < APIError
+    error_code 11
+  end
+
+  class MissingCallbackError < APIError
+    error_code 12
+  end
+
+  class InvalidIndataError < APIError
+    error_code 13
+  end
+
+  class IndexOutOfRangeError < APIError
+    error_code 14
+  end
+
+  class UserNeedsPremiumError < APIError
+    error_code 15
+  end
+
+  class OtherTransientError < APIError
+    error_code 16
+  end
+
+  class IsLoadingError < APIError
+    error_code 17
+  end
+
+  class NoStreamAvailableError < APIError
+    error_code 18
+  end
+
+  class PermissionDeniedError < APIError
+    error_code 19
+  end
+
+  class InboxIsFullError < APIError
+    error_code 20
+  end
+
+  class NoCacheError < APIError
+    error_code 21
+  end
+
+  class NoSuchUserError < APIError
+    error_code 22
+  end
+
+  class NoCredentialsError < APIError
+    error_code 23
+  end
+
+  class NetworkDisabledError < APIError
+    error_code 24
+  end
+
+  class InvalidDeviceIdError < APIError
+    error_code 25
+  end
+
+  class CantOpenTraceFileError < APIError
+    error_code 26
+  end
+
+  class ApplicationBannedError < APIError
+    error_code 27
+  end
+
+  class OfflineTooManyTracksError < APIError
+    error_code 31
+  end
+
+  class OfflineDiskCacheError < APIError
+    error_code 32
+  end
+
+  class OfflineExpiredError < APIError
+    error_code 33
+  end
+
+  class OfflineNotAllowedError < APIError
+    error_code 34
+  end
+
+  class OfflineLicenseLostError < APIError
+    error_code 35
+  end
+
+  class OfflineLicenseError < APIError
+    error_code 36
+  end
+
+  class LastfmAuthError < APIError
+    error_code 39
+  end
+
+  class InvalidArgumentError < APIError
+    error_code 40
+  end
+
+  class SystemFailureError < APIError
+    error_code 41
   end
 end