spotify 12.2.0 → 12.3.0

data/lib/spotify/managed_pointer.rb

@@ -0,0 +1,90 @@
+# encoding: utf-8
+module Spotify
+  # An autopointer base class for Spotify pointers.
+  #
+  # It contains a default implementation for release, retain,
+  # and a default constructor. When the underlying pointer is
+  # garbage collected, the pointer is released automatically.
+  #
+  # This class is never instantiated; instead you’ll be dealing
+  # with any of it’s subclasses.
+  #
+  # @note The default ManagedPointer does not retain its pointer after initialization,
+  #       but provides a class that does through {.retaining_class}. This is better as
+  #       it allows you to err on the side of segfaulting, instead of leaking memory.
+  #
+  # @api private
+  class ManagedPointer < FFI::AutoPointer
+    class << self
+      # Releases the given pointer if it is not null.
+      #
+      # This method derives the release method from the class name.
+      #
+      # @param [FFI::Pointer] pointer
+      def release(pointer)
+        unless pointer.null?
+          $stderr.puts "Spotify.#{type}_release(#{pointer.inspect})" if $DEBUG
+          Spotify.public_send("#{type}_release", pointer)
+        end
+      end
+
+      # Retains the given pointer if it is not null.
+      #
+      # This method derives the retain method from the class name.
+      #
+      # @param [FFI::Pointer] pointer
+      def retain(pointer)
+        unless pointer.null?
+          $stderr.puts "Spotify.#{type}_add_ref(#{pointer.inspect})" if $DEBUG
+          Spotify.public_send("#{type}_add_ref", pointer)
+        end
+      end
+
+      # @return [self] subclass that retains its pointer on initialization.
+      def retaining_class
+        @klass ||= Class.new(self) do
+          def initialize(*args, &block)
+            superclass = self.class.superclass
+            superclass.instance_method(:initialize).bind(self).call(*args, &block)
+            superclass.retain(self)
+          end
+
+          class << self
+            alias_method :==, :<=
+
+            # @return [String] delegates to the superclass.
+            def name
+              superclass.name
+            end
+
+            # @return [String] delegates to the superclass.
+            def to_s
+              superclass.to_s
+            end
+
+            # @return [String] string representation of object
+            def inspect
+              "#{superclass}<retaining>"
+            end
+          end
+        end
+      end
+
+      alias_method :==, :>=
+
+      protected
+
+      # @return [#to_s] the spotify type of this pointer.
+      def type
+        name.split('::')[-1].downcase
+      end
+    end
+
+    # @return [String] string representation of self.
+    def inspect
+      "#<#{self.class} address=0x%x>" % address
+    end
+
+    alias_method :to_s, :inspect
+  end
+end

data/lib/spotify/objects.rb

@@ -0,0 +1,16 @@
+require 'spotify/managed_pointer'
+
+require 'spotify/objects/album'
+require 'spotify/objects/album_browse'
+require 'spotify/objects/artist'
+require 'spotify/objects/artist_browse'
+require 'spotify/objects/image'
+require 'spotify/objects/inbox'
+require 'spotify/objects/link'
+require 'spotify/objects/playlist'
+require 'spotify/objects/playlist_container'
+require 'spotify/objects/search'
+require 'spotify/objects/session'
+require 'spotify/objects/toplist_browse'
+require 'spotify/objects/track'
+require 'spotify/objects/user'

data/lib/spotify/objects/album.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Album < ManagedPointer
+  end
+end

data/lib/spotify/objects/album_browse.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class AlbumBrowse < ManagedPointer
+  end
+end

data/lib/spotify/objects/artist.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Artist < ManagedPointer
+  end
+end

data/lib/spotify/objects/artist_browse.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class ArtistBrowse < ManagedPointer
+  end
+end

data/lib/spotify/objects/image.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Image < ManagedPointer
+  end
+end

data/lib/spotify/objects/inbox.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Inbox < ManagedPointer
+  end
+end

data/lib/spotify/objects/link.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Link < ManagedPointer
+  end
+end

data/lib/spotify/objects/playlist.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Playlist < ManagedPointer
+  end
+end

data/lib/spotify/objects/playlist_container.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See the {ManagedPointer} for documentation.
+  class PlaylistContainer < ManagedPointer
+  end
+end

data/lib/spotify/objects/search.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Search < ManagedPointer
+  end
+end

data/lib/spotify/objects/session.rb

@@ -0,0 +1,20 @@
+module Spotify
+  # Session pointers are special in that they are created once,
+  # never increases or decreases in reference count and should
+  # never be released.
+  #
+  # See the {ManagedPointer} for documentation.
+  class Session < ManagedPointer
+    class << self
+      undef :retaining_class
+    end
+
+    # After initialization sets autorelease to false.
+    #
+    # @param (see ManagedPointer)
+    def initialize(*)
+      super
+      self.autorelease = false
+    end
+  end
+end

data/lib/spotify/objects/toplist_browse.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class ToplistBrowse < ManagedPointer
+  end
+end

data/lib/spotify/objects/track.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class Track < ManagedPointer
+  end
+end

data/lib/spotify/objects/user.rb

@@ -0,0 +1,5 @@
+module Spotify
+  # See {ManagedPointer} for documentation.
+  class User < ManagedPointer
+  end
+end

data/lib/spotify/structs.rb

@@ -0,0 +1,46 @@
+module Spotify
+  # Spotify::Struct is a regular FFI::Struct, but with type
+  # checking that happens in the Spotify::API namespace, and
+  # it also allows you to initialize structs with a hash.
+  class Struct < FFI::Struct
+    # This is used by FFI to do type lookups when creating the
+    # struct layout. By overriding this we can trick FFI into
+    # looking up types in the right location.
+    #
+    # @return [Spotify::API]
+    def self.enclosing_module
+      Spotify::API
+    end
+
+    # When initialized with a hash, assigns each value of the
+    # hash to the newly created struct before returning.
+    #
+    # If not given a hash, it behaves exactly as FFI::Struct.
+    #
+    # @param [#each_pair, FFI::Pointer, nil] pointer
+    # @param [Array<Symbol, Type>] layout
+    def initialize(pointer = nil, *layout, &block)
+      if pointer.respond_to?(:each_pair)
+        options = pointer
+        pointer = nil
+      else
+        options = {}
+      end
+
+      super(pointer, *layout, &block)
+
+      options.each_pair do |key, value|
+        self[key] = value
+      end
+    end
+  end
+end
+
+require 'spotify/structs/audio_buffer_stats'
+require 'spotify/structs/audio_format'
+require 'spotify/structs/offline_sync_status'
+require 'spotify/structs/playlist_callbacks'
+require 'spotify/structs/playlist_container_callbacks'
+require 'spotify/structs/session_callbacks'
+require 'spotify/structs/session_config'
+require 'spotify/structs/subscribers'

data/lib/spotify/structs/audio_buffer_stats.rb

@@ -0,0 +1,10 @@
+module Spotify
+  # Spotify::Struct for Audio Buffer Stats.
+  #
+  # @attr [Fixnum] samples
+  # @attr [Fixnum] stutter
+  class AudioBufferStats < Spotify::Struct
+    layout :samples => :int,
+           :stutter => :int
+  end
+end

data/lib/spotify/structs/audio_format.rb

@@ -0,0 +1,12 @@
+module Spotify
+  # Spotify::Struct for Audio Format.
+  #
+  # @attr [:sampletype] sample_type
+  # @attr [Fixnum] sample_rate
+  # @attr [Fixnum] channels
+  class AudioFormat < Spotify::Struct
+    layout :sample_type => :sampletype,
+           :sample_rate => :int,
+           :channels => :int
+  end
+end

data/lib/spotify/structs/offline_sync_status.rb

@@ -0,0 +1,24 @@
+module Spotify
+  # Spotify::Struct for Offline Sync Status
+  #
+  # @attr [Fixnum] queued_tracks
+  # @attr [Fixnum] queued_bytes
+  # @attr [Fixnum] done_tracks
+  # @attr [Fixnum] done_bytes
+  # @attr [Fixnum] copied_tracks
+  # @attr [Fixnum] copied_bytes
+  # @attr [Fixnum] willnotcopy_tracks
+  # @attr [Fixnum] error_tracks
+  # @attr [Boolean] syncing
+  class OfflineSyncStatus < Spotify::Struct
+    layout :queued_tracks => :int,
+           :queued_bytes => :uint64,
+           :done_tracks => :int,
+           :done_bytes => :uint64,
+           :copied_tracks => :int,
+           :copied_bytes => :uint64,
+           :willnotcopy_tracks => :int,
+           :error_tracks => :int,
+           :syncing => :bool
+  end
+end

data/lib/spotify/structs/playlist_callbacks.rb

@@ -0,0 +1,32 @@
+module Spotify
+  # Spotify::Struct for Playlist callbacks.
+  #
+  # @attr [callback(Playlist, :array, :int, :int, :userdata):void] tracks_added
+  # @attr [callback(Playlist, :array, :int, :userdata):void] tracks_removed
+  # @attr [callback(Playlist, :array, :int, :int, :userdata):void] tracks_moved
+  # @attr [callback(Playlist, :userdata):void] playlist_renamed
+  # @attr [callback(Playlist, :userdata):void] playlist_state_changed
+  # @attr [callback(Playlist, :bool, :userdata):void] playlist_update_in_progress
+  # @attr [callback(Playlist, :userdata):void] playlist_metadata_updated
+  # @attr [callback(Playlist, :int, User, :int, :userdata):void] track_created_changed
+  # @attr [callback(Playlist, :int, :bool, :userdata):void] track_seen_changed
+  # @attr [callback(Playlist, UTF8String, :userdata):void] description_changed
+  # @attr [callback(Playlist, ImageID, :userdata):void] image_changed
+  # @attr [callback(Playlist, :int, UTF8String, :userdata):void] track_message_changed
+  # @attr [callback(Playlist, :userdata):void] subscribers_changed
+  class PlaylistCallbacks < Spotify::Struct
+    layout :tracks_added => callback([ Playlist.retaining_class, :array, :int, :int, :userdata ], :void),
+           :tracks_removed => callback([ Playlist.retaining_class, :array, :int, :userdata ], :void),
+           :tracks_moved => callback([ Playlist.retaining_class, :array, :int, :int, :userdata ], :void),
+           :playlist_renamed => callback([ Playlist.retaining_class, :userdata ], :void),
+           :playlist_state_changed => callback([ Playlist.retaining_class, :userdata ], :void),
+           :playlist_update_in_progress => callback([ Playlist.retaining_class, :bool, :userdata ], :void),
+           :playlist_metadata_updated => callback([ Playlist.retaining_class, :userdata ], :void),
+           :track_created_changed => callback([ Playlist.retaining_class, :int, User.retaining_class, :int, :userdata ], :void),
+           :track_seen_changed => callback([ Playlist.retaining_class, :int, :bool, :userdata ], :void),
+           :description_changed => callback([ Playlist.retaining_class, UTF8String, :userdata ], :void),
+           :image_changed => callback([ Playlist.retaining_class, ImageID, :userdata ], :void),
+           :track_message_changed => callback([ Playlist.retaining_class, :int, UTF8String, :userdata ], :void),
+           :subscribers_changed => callback([ Playlist.retaining_class, :userdata ], :void)
+  end
+end

data/lib/spotify/structs/playlist_container_callbacks.rb

@@ -0,0 +1,14 @@
+module Spotify
+  # Spotify::Struct for the PlaylistContainer.
+  #
+  # @attr [callback(PlaylistContainer, Playlist, :int, :userdata):void] playlist_added
+  # @attr [callback(PlaylistContainer, Playlist, :int, :userdata):void] playlist_removed
+  # @attr [callback(PlaylistContainer, Playlist, :int, :int, :userdata):void] playlist_moved
+  # @attr [callback(PlaylistContainer, :userdata):void] container_loaded
+  class PlaylistContainerCallbacks < Spotify::Struct
+    layout :playlist_added, callback([ PlaylistContainer.retaining_class, Playlist.retaining_class, :int, :userdata ], :void),
+           :playlist_removed, callback([ PlaylistContainer.retaining_class, Playlist.retaining_class, :int, :userdata ], :void),
+           :playlist_moved, callback([ PlaylistContainer.retaining_class, Playlist.retaining_class, :int, :int, :userdata ], :void),
+           :container_loaded, callback([ PlaylistContainer.retaining_class, :userdata ], :void)
+  end
+end

data/lib/spotify/structs/session_callbacks.rb

@@ -0,0 +1,48 @@
+module Spotify
+  # Spotify::Struct for Session callbacks.
+  #
+  # @attr [callback(Session, :error):void] logged_in
+  # @attr [callback(Session):void] logged_out
+  # @attr [callback(Session):void] metadata_updated
+  # @attr [callback(Session, :error):void] connection_error
+  # @attr [callback(Session, UTF8String):void] message_to_user
+  # @attr [callback(Session):void] notify_main_thread
+  # @attr [callback(Session, AudioFormat, :frames, :int):int] music_delivery
+  # @attr [callback(Session):void] play_token_lost
+  # @attr [callback(Session, UTF8String):void] log_message
+  # @attr [callback(Session):void] end_of_track
+  # @attr [callback(Session, :error):void] streaming_error
+  # @attr [callback(Session):void] userinfo_updated
+  # @attr [callback(Session):void] start_playback
+  # @attr [callback(Session):void] stop_playback
+  # @attr [callback(Session, AudioBufferStats):void] get_audio_buffer_stats
+  # @attr [callback(Session):void] offline_status_updated
+  # @attr [callback(Session, :error):void] offline_error
+  # @attr [callback(Session, :string):void] credentials_blob_updated
+  # @attr [callback(Session):void] connectionstate_updated
+  # @attr [callback(Session, :error):void] scrobble_error
+  # @attr [callback(Session, :bool):void] private_session_mode_changed
+  class SessionCallbacks < Spotify::Struct
+    layout :logged_in => callback([ Session, :error ], :void),
+           :logged_out => callback([ Session ], :void),
+           :metadata_updated => callback([ Session ], :void),
+           :connection_error => callback([ Session, :error ], :void),
+           :message_to_user => callback([ Session, UTF8String ], :void),
+           :notify_main_thread => callback([ Session ], :void),
+           :music_delivery => callback([ Session, AudioFormat, :frames, :int ], :int),
+           :play_token_lost => callback([ Session ], :void),
+           :log_message => callback([ Session, UTF8String ], :void),
+           :end_of_track => callback([ Session ], :void),
+           :streaming_error => callback([ Session, :error ], :void),
+           :userinfo_updated => callback([ Session ], :void),
+           :start_playback => callback([ Session ], :void),
+           :stop_playback => callback([ Session ], :void),
+           :get_audio_buffer_stats => callback([ Session, AudioBufferStats ], :void),
+           :offline_status_updated => callback([ Session ], :void),
+           :offline_error => callback([ Session, :error ], :void),
+           :credentials_blob_updated => callback([ Session, :string ], :void),
+           :connectionstate_updated => callback([ Session ], :void),
+           :scrobble_error => callback([ Session, :error ], :void),
+           :private_session_mode_changed => callback([ Session, :bool ], :void)
+  end
+end

data/lib/spotify/structs/session_config.rb

@@ -0,0 +1,64 @@
+module Spotify
+  # Spotify::Struct for Session configuration.
+  #
+  # @attr [Fixnum] api_version
+  # @attr [StringPointer] cache_location
+  # @attr [StringPointer] settings_location
+  # @attr [size_t] application_key_size
+  # @attr [StringPointer] user_agent
+  # @attr [StructPointer] callbacks
+  # @attr [Pointer] userdata
+  # @attr [Fixnum] dont_save_metadata_for_playlists
+  # @attr [Fixnum] initially_unload_playlists
+  # @attr [Boolean] initially_unload_playlists
+  # @attr [StringPointer] device_id
+  # @attr [StringPointer] proxy
+  # @attr [StringPointer] proxy_username
+  # @attr [StringPointer] proxy_password
+  # @attr [StringPointer] ca_certs_filename
+  # @attr [StringPointer] tracefile
+  class SessionConfig < Spotify::Struct
+    it = {}
+    it[:api_version] = :int
+    it[:cache_location] = NULString
+    it[:settings_location] = NULString
+    it[:application_key] = :pointer
+    it[:application_key_size] = :size_t
+    it[:user_agent] = NULString
+    it[:callbacks] = SessionCallbacks.by_ref
+    it[:userdata] = :userdata
+    it[:compress_playlists] = :bool
+    it[:dont_save_metadata_for_playlists] = :bool
+    it[:initially_unload_playlists] = :bool
+    it[:device_id] = NULString
+    it[:proxy] = NULString
+    it[:proxy_username] = NULString
+    it[:proxy_password] = NULString
+    it[:ca_certs_filename] = NULString if Spotify::API.linux?
+    it[:tracefile] = NULString
+    layout(it)
+
+    # Overridden for some keys for convenience.
+    #
+    # @example setting application key
+    #   struct[:application_key] = "application key"
+    #   # ^ also sets :application_key_size
+    #
+    # @param [Symbol] key
+    # @param [Object] value
+    def []=(key, value)
+      case key
+      when :application_key
+        if value.is_a?(String)
+          pointer = FFI::MemoryPointer.new(:char, value.bytesize)
+          pointer.write_bytes(value)
+          super(key, pointer)
+          self[:application_key_size] = pointer.size
+        else
+          super
+        end
+      else super
+      end
+    end
+  end
+end