spotify 12.0.0 → 12.0.1

data/lib/spotify/gc_wrappers.rb

@@ -0,0 +1,104 @@
+# This file contains a tiny (!) DSL that wraps existing Spotify
+# functions into versions that return Spotify::Pointers instead
+# of the usual FFI::Pointers. The Spotify::Pointer automatically
+# manages the underlying pointers reference count, which allows
+# us to piggyback on the Ruby GC mechanism.
+
+module Spotify
+  # Wraps the function `function` so that it always returns
+  # a Spotify::Pointer with correct refcount. Functions that
+  # contain the word `create` are assumed to start out with
+  # a refcount of `+1`.
+  #
+  # @note This method is removed at the bottom of this file.
+  #
+  # @param [#to_s] function
+  # @param [#to_s] return_type
+  # @raise [NoMethodError] if `function` is not defined
+  # @see Spotify::Pointer
+  def self.wrap_function(function, return_type)
+    method(function) # make sure it exists
+    define_singleton_method("#{function}!") do |*args, &block|
+      pointer = public_send(function, *args, &block)
+      Spotify::Pointer.new(pointer, return_type, function !~ /create/)
+    end
+  end
+
+  # @macro [attach] wrap_function
+  #   Same as {Spotify}.`$1`, but wraps result in a {Spotify::Pointer}.
+  #
+  #   @method $1!
+  #   @return [Spotify::Pointer<$2>]
+  #   @see #$1
+  wrap_function :session_user, :user
+  wrap_function :session_playlistcontainer, :playlistcontainer
+  wrap_function :session_inbox_create, :playlist
+  wrap_function :session_starred_create, :playlist
+  wrap_function :session_starred_for_user_create, :playlist
+  wrap_function :session_publishedcontainer_for_user_create, :playlistcontainer
+
+  wrap_function :track_artist, :artist
+  wrap_function :track_album, :album
+  wrap_function :localtrack_create, :track
+  wrap_function :track_get_playable, :track
+
+  wrap_function :album_artist, :artist
+
+  wrap_function :albumbrowse_create, :albumbrowse
+  wrap_function :albumbrowse_album, :album
+  wrap_function :albumbrowse_artist, :artist
+  wrap_function :albumbrowse_track, :track
+
+  wrap_function :artistbrowse_create, :artistbrowse
+  wrap_function :artistbrowse_artist, :artist
+  wrap_function :artistbrowse_track, :track
+  wrap_function :artistbrowse_album, :album
+  wrap_function :artistbrowse_similar_artist, :artist
+  wrap_function :artistbrowse_tophit_track, :track
+
+  wrap_function :image_create, :image
+  wrap_function :image_create_from_link, :image
+
+  wrap_function :link_as_track, :track
+  wrap_function :link_as_track_and_offset, :track
+  wrap_function :link_as_album, :album
+  wrap_function :link_as_artist, :artist
+  wrap_function :link_as_user, :user
+
+  wrap_function :link_create_from_string, :link
+  wrap_function :link_create_from_track, :link
+  wrap_function :link_create_from_album, :link
+  wrap_function :link_create_from_artist, :link
+  wrap_function :link_create_from_search, :link
+  wrap_function :link_create_from_playlist, :link
+  wrap_function :link_create_from_artist_portrait, :link
+  wrap_function :link_create_from_artistbrowse_portrait, :link
+  wrap_function :link_create_from_album_cover, :link
+  wrap_function :link_create_from_image, :link
+  wrap_function :link_create_from_user, :link
+
+  wrap_function :search_create, :search
+  wrap_function :search_track, :track
+  wrap_function :search_album, :album
+  wrap_function :search_artist, :artist
+
+  wrap_function :playlist_track, :track
+  wrap_function :playlist_track_creator, :user
+  wrap_function :playlist_owner, :user
+  wrap_function :playlist_create, :playlist
+
+  wrap_function :playlistcontainer_playlist, :playlist
+  wrap_function :playlistcontainer_add_new_playlist, :playlist
+  wrap_function :playlistcontainer_add_playlist, :playlist
+  wrap_function :playlistcontainer_owner, :user
+
+  wrap_function :toplistbrowse_create, :toplistbrowse
+  wrap_function :toplistbrowse_artist, :artist
+  wrap_function :toplistbrowse_album, :album
+  wrap_function :toplistbrowse_track, :track
+
+  wrap_function :inbox_post_tracks, :inbox
+
+  # Clean up
+  class << self; undef :wrap_function; end
+end

data/lib/spotify/types/image_id.rb

@@ -0,0 +1,38 @@
+module Spotify
+  # A custom data type for Spotify image IDs.
+  #
+  # It will convert strings to image ID pointers when handling
+  # values from Ruby to C, and it will convert pointers to Ruby
+  # strings when handling values from C to Ruby.
+  module ImageID
+    extend FFI::DataConverter
+    native_type FFI::Type::POINTER
+
+    # Given a string, convert it to an image ID pointer.
+    #
+    # @param [String] value image id as a string
+    # @param ctx
+    # @return [FFI::Pointer] pointer to the image ID
+    def self.to_native(value, ctx)
+      pointer = if value
+        if value.bytesize != 20
+          raise ArgumentError, "image id bytesize must be 20, was #{value.bytesize}"
+        end
+
+        pointer = FFI::MemoryPointer.new(:char, 20)
+        pointer.write_string(value.to_s)
+      end
+
+      super(pointer, ctx)
+    end
+
+    # Given a pointer, read a 20-byte image ID from it.
+    #
+    # @param [FFI::Pointer] value
+    # @param ctx
+    # @return [String, nil] the image ID as a string, or nil
+    def self.from_native(value, ctx)
+      value.read_string(20) unless value.null?
+    end
+  end
+end

data/lib/spotify/types/pointer.rb

@@ -0,0 +1,61 @@
+require 'set'
+
+module Spotify
+  # The Pointer is a kind of AutoPointer specially tailored for Spotify
+  # objects, that releases the raw pointer on GC.
+  class Pointer < FFI::AutoPointer
+    # Raised when #releaser_for is given an invalid type.
+    class InvalidTypeError < StandardError
+    end
+
+    class << self
+      # Create a proc that will accept a pointer of a given type and
+      # release it with the correct function if it’s not null.
+      #
+      # @raise [InvalidTypeError] when given an invalid type
+      # @param [Symbol] type
+      # @return [Proc]
+      def releaser_for(type)
+        unless Spotify.respond_to?(:"#{type}_release")
+          raise InvalidTypeError, "#{type} is not a valid Spotify type"
+        end
+
+        lambda do |pointer|
+          $stdout.puts "Spotify::#{type}_release(#{pointer})" if $DEBUG
+          Spotify.send(:"#{type}_release", pointer) unless pointer.null?
+        end
+      end
+
+      # Checks an object by pointer kind and type.
+      #
+      # @param [Object] object
+      # @param [Symbol] type
+      # @return [Boolean] true if object is a spotify pointer and of correct type
+      def typechecks?(object, type)
+        object.is_a?(Spotify::Pointer) && (object.type == type.to_s)
+      end
+    end
+
+    # @return [Symbol] type
+    attr_reader :type
+
+    # Initialize a Spotify pointer, which will automatically decrease
+    # the reference count of it’s pointer when garbage collected.
+    #
+    # @param [FFI::Pointer] pointer
+    # @param [#to_s] type session, link, etc
+    # @param [Boolean] add_ref will increase refcount by one if true
+    def initialize(pointer, type, add_ref)
+      super pointer, self.class.releaser_for(@type = type.to_s)
+
+      unless pointer.null?
+        Spotify.send(:"#{type}_add_ref", pointer)
+      end if add_ref
+    end
+
+    # @return [String] representation of the spotify pointer
+    def to_s
+      "<#{self.class} address=0x#{address.to_s(16)} type=#{type}>"
+    end
+  end
+end

data/lib/spotify/types/utf8_string.rb

@@ -0,0 +1,45 @@
+module Spotify
+  # A UTF-8 FFI type, making sure all strings are UTF8 in and out.
+  #
+  # Given an ingoing (ruby to C) string, it will make sure the string
+  # is in UTF-8 encoding. An outgoing (C to Ruby) will be assumed to
+  # actually be in UTF-8, and force-encoded as such.
+  module UTF8String
+    extend FFI::DataConverter
+    native_type FFI::Type::STRING
+
+    if "".respond_to?(:encode)
+      # Given a value, encodes it to UTF-8 no matter what.
+      #
+      # @note if the value is already in UTF-8, ruby does nothing
+      # @note if the given value is falsy, default behaviour is used
+      #
+      # @param [String] value
+      # @param ctx
+      # @return [String] value, but in UTF-8 if it wasn’t already
+      def self.to_native(value, ctx)
+        if value
+          value.encode('UTF-8')
+        else
+          super
+        end
+      end
+    end
+
+    if "".respond_to?(:force_encoding)
+      # Given an original string, assume it is in UTF-8.
+      #
+      # @note NO error checking is made, the string is just forced to UTF-8
+      # @param [String] value can be in any encoding
+      # @param ctx
+      # @return [String] value, but with UTF-8 encoding
+      def self.from_native(value, ctx)
+        if value
+          value.force_encoding('UTF-8')
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/spotify/version.rb

@@ -1,4 +1,4 @@
 module Spotify
   # See README for versioning policy.
-  VERSION = [12, 0, 0].join('.')
+  VERSION = [12, 0, 1].join('.')
 end

data/spec/spotify_spec.rb

@@ -1,7 +1,10 @@
 # coding: utf-8
 require 'rubygems' # needed for 1.8, does not matter in 1.9
 
+require 'ostruct'
+require 'set'
 require 'rbgccxml'
+require 'minitest/mock'
 require 'minitest/autorun'
 
 #
@@ -44,6 +47,19 @@ module C
   attach_function :strncpy, [ :pointer, :utf8_string, :size_t ], :utf8_string
 end
 
+# Used for checking Spotify::Pointer things.
+module Spotify
+  def bogus_add_ref(pointer)
+  end
+
+  def bogus_release(pointer)
+  end
+
+  # This may be called after our GC test. Randomly.
+  def garbage_release(pointer)
+  end
+end
+
 #
 # Utility
 #
@@ -67,6 +83,16 @@ describe Spotify do
     end
   end
 
+  describe ".enum_value!" do
+    it "raises an error if given an invalid enum value" do
+      proc { Spotify.enum_value!(:moo, "error value") }.must_raise(ArgumentError)
+    end
+
+    it "gives back the enum value for that enum" do
+      Spotify.enum_value!(:ok, "error value").must_equal 0
+    end
+  end
+
   describe Spotify::SessionConfig do
     it "allows setting boolean values with bools" do
       subject = Spotify::SessionConfig.new
@@ -111,7 +137,129 @@ describe Spotify do
     end
   end
 
-  describe "UTF8 string" do
+  describe "error wrapped functions" do
+    wrapped_methods = Spotify.attached_methods.find_all { |meth, info| info[:returns] == :error }
+    wrapped_methods.each do |meth, info|
+      it "raises an error if #{meth}! returns non-ok" do
+        Spotify.stub(meth, :bad_application_key) do
+          proc { Spotify.send("#{meth}!") }.must_raise(Spotify::Error, /BAD_APPLICATION_KEY/)
+        end
+      end
+    end
+  end
+
+  describe "GC wrapped functions" do
+    gc_types = Set.new([:session, :track, :user, :playlistcontainer, :playlist, :link, :album, :artist, :search, :image, :albumbrowse, :artistbrowse, :toplistbrowse, :inbox])
+    wrapped_methods = Spotify.attached_methods.find_all { |meth, info| gc_types.member?(info[:returns]) }
+    wrapped_methods.each do |meth, info|
+      it "returns a Spotify::Pointer for #{meth}!" do
+        Spotify.stub(meth, lambda { FFI::Pointer.new(0) }) do
+          Spotify.send("#{meth}!").must_be_instance_of Spotify::Pointer
+        end
+      end
+    end
+
+    it "adds a ref to the pointer if required" do
+      session = FFI::Pointer.new(1)
+      ref_added = false
+
+      Spotify.stub(:session_user, FFI::Pointer.new(1)) do
+        Spotify.stub(:user_add_ref, proc { ref_added = true }) do
+          Spotify.session_user!(session)
+        end
+      end
+
+      ref_added.must_equal true
+    end
+
+    it "does not add a ref when the result is null" do
+      session = FFI::Pointer.new(1)
+      ref_added = false
+
+      Spotify.stub(:session_user, FFI::Pointer.new(0)) do
+        Spotify.stub(:user_add_ref, proc { ref_added = true }) do
+          Spotify.session_user!(session)
+        end
+      end
+
+      ref_added.must_equal false
+    end
+
+    it "does not add a ref when the result already has one" do
+      session = FFI::Pointer.new(1)
+      ref_added = false
+
+      Spotify.stub(:albumbrowse_create, FFI::Pointer.new(1)) do
+        Spotify.stub(:albumbrowse_add_ref, proc { ref_added = true }) do
+          # to avoid it trying to GC our fake pointer later, and cause a
+          # segfault in our tests
+          Spotify::Pointer.stub(:releaser_for, proc { proc {} }) do
+            Spotify.albumbrowse_create!(session)
+          end
+        end
+      end
+
+      ref_added.must_equal false
+    end
+  end
+
+  describe Spotify::Pointer do
+    describe ".new" do
+      it "adds a reference on the given pointer" do
+        ref_added = false
+
+        Spotify.stub(:bogus_add_ref, proc { ref_added = true }) do
+          Spotify::Pointer.new(FFI::Pointer.new(1), :bogus, true)
+        end
+
+        ref_added.must_equal true
+      end
+
+      it "does not add a reference on the given pointer if it is NULL" do
+        ref_added = false
+
+        Spotify.stub(:bogus_add_ref, proc { ref_added = true }) do
+          Spotify::Pointer.new(FFI::Pointer::NULL, :bogus, true)
+        end
+
+        ref_added.must_equal false
+      end
+
+      it "raises an error when given an invalid type" do
+        proc { Spotify::Pointer.new(FFI::Pointer.new(1), :really_bogus, true) }.
+          must_raise(Spotify::Pointer::InvalidTypeError, /invalid/)
+      end
+    end
+
+    describe ".typechecks?" do
+      it "typechecks a given spotify pointer" do
+        pointer = Spotify::Pointer.new(FFI::Pointer.new(1), :bogus, true)
+        bogus   = OpenStruct.new(:type => :bogus)
+        Spotify::Pointer.typechecks?(bogus, :bogus).must_equal false
+        Spotify::Pointer.typechecks?(pointer, :link).must_equal false
+        Spotify::Pointer.typechecks?(pointer, :bogus).must_equal true
+      end
+    end
+
+    describe "garbage collection" do
+      let(:my_pointer) { FFI::Pointer.new(1) }
+
+      it "should work" do
+        gc_count = 0
+
+        Spotify.stub(:garbage_release, proc { gc_count += 1 }) do
+          5.times { Spotify::Pointer.new(my_pointer, :garbage, false) }
+          5.times { GC.start; sleep 0.01 }
+        end
+
+        # GC tests are a bit funky, but as long as we garbage_release at least once, then
+        # we can assume our GC works properly, but up the stakes just for the sake of it
+        gc_count.must_be :>, 3
+      end
+    end
+  end
+
+  describe Spotify::UTF8String do
     let(:char) do
       char = "\xC4"
       char.force_encoding('ISO-8859-1') if char.respond_to?(:force_encoding)
@@ -136,7 +284,7 @@ describe Spotify do
     end unless "".respond_to?(:force_encoding)
   end
 
-  describe "Image ID" do
+  describe Spotify::ImageID do
     let(:context) { nil }
     let(:subject) { Spotify.find_type(:image_id) }
     let(:null_pointer) { FFI::Pointer::NULL }

data/spotify.gemspec

@@ -27,5 +27,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'yard'
   gem.add_development_dependency 'rbgccxml'
-  gem.add_development_dependency 'minitest', '~> 2.0'
+  gem.add_development_dependency 'minitest', '~> 3.0'
 end