libusb 0.3.4 → 0.4.0

data/lib/libusb.rb

@@ -47,5 +47,9 @@ module LIBUSB
       r = Call.libusb_has_capability(capability)
       return r != 0
     end
+  else
+    def self.has_capability?(capability)
+      false
+    end
   end
 end

data/lib/libusb/call.rb

@@ -149,11 +149,44 @@ module LIBUSB
     ]
 
     Capabilities = enum :libusb_capability, [
-      :CAP_HAS_CAPABILITY, 0,
+      :CAP_HAS_CAPABILITY, 0x0000,
+      # Hotplug support is available on this platform.
+      :CAP_HAS_HOTPLUG, 0x0001,
+      # The library can access HID devices without requiring user intervention.
+      # Note that before being able to actually access an HID device, you may
+      # still have to call additional libusb functions such as
+      # {DevHandle#detach_kernel_driver}.
+      :CAP_HAS_HID_ACCESS, 0x0100,
+      # The library supports detaching of the default USB driver, using
+      # {DevHandle#detach_kernel_driver}, if one is set by the OS kernel.
+      :CAP_SUPPORTS_DETACH_KERNEL_DRIVER, 0x0101,
+    ]
+
+    # Since libusb version 1.0.16.
+    #
+    # Hotplug events
+    HotplugEvents = enum :libusb_hotplug_event, [
+      # A device has been plugged in and is ready to use.
+      :HOTPLUG_EVENT_DEVICE_ARRIVED, 0x01,
+
+      # A device has left and is no longer available.
+      # It is the user's responsibility to call libusb_close on any handle associated with a disconnected device.
+      # It is safe to call libusb_get_device_descriptor on a device that has left.
+      :HOTPLUG_EVENT_DEVICE_LEFT, 0x02,
+    ]
+
+    # Since libusb version 1.0.16.
+    #
+    # Flags for hotplug events */
+    HotplugFlags = enum :libusb_hotplug_flag, [
+      # Arm the callback and fire it for all matching currently attached devices.
+      :HOTPLUG_ENUMERATE, 1,
     ]
 
     typedef :pointer, :libusb_context
+    typedef :pointer, :libusb_device
     typedef :pointer, :libusb_device_handle
+    typedef :int, :libusb_hotplug_callback_handle
 
     def self.try_attach_function(method, *args)
       if ffi_libraries.find{|lib| lib.find_function(method) }
@@ -182,6 +215,7 @@ module LIBUSB
     try_attach_function 'libusb_get_port_number', [:pointer], :uint8
     try_attach_function 'libusb_get_parent', [:pointer], :pointer
     try_attach_function 'libusb_get_port_path', [:pointer, :pointer, :pointer, :uint8], :uint8
+    try_attach_function 'libusb_get_port_numbers', [:pointer, :pointer, :uint8], :uint8
     attach_function 'libusb_get_device_address', [:pointer], :uint8
     try_attach_function 'libusb_get_device_speed', [:pointer], :libusb_speed
     attach_function 'libusb_get_max_packet_size', [:pointer, :uint8], :int
@@ -204,6 +238,7 @@ module LIBUSB
     attach_function 'libusb_kernel_driver_active', [:libusb_device_handle, :int], :int
     attach_function 'libusb_detach_kernel_driver', [:libusb_device_handle, :int], :int
     attach_function 'libusb_attach_kernel_driver', [:libusb_device_handle, :int], :int
+    try_attach_function 'libusb_set_auto_detach_kernel_driver', [:libusb_device_handle, :int], :int
 
     attach_function 'libusb_get_string_descriptor_ascii', [:pointer, :uint8, :pointer, :int], :int
 
@@ -226,6 +261,13 @@ module LIBUSB
 
     callback :libusb_transfer_cb_fn, [:pointer], :void
 
+    callback :libusb_hotplug_callback_fn, [:libusb_context, :libusb_device, :libusb_hotplug_event, :pointer], :int
+    try_attach_function 'libusb_hotplug_register_callback', [
+        :libusb_context, :libusb_hotplug_event, :libusb_hotplug_flag,
+        :int, :int, :int, :libusb_hotplug_callback_fn,
+        :pointer, :pointer], :int
+    try_attach_function 'libusb_hotplug_deregister_callback', [:libusb_context, :libusb_hotplug_callback_handle], :void
+
     class IsoPacketDescriptor < FFI::Struct
       layout :length, :uint,
           :actual_length, :uint,

data/lib/libusb/constants.rb

@@ -26,6 +26,8 @@ module LIBUSB
   Call::IsoSyncTypes.to_h.each{|k,v| const_set(k,v) }
   Call::Speeds.to_h.each{|k,v| const_set(k,v) }
   Call::Capabilities.to_h.each{|k,v| const_set(k,v) }
+  Call::HotplugEvents.to_h.each{|k,v| const_set(k,v) }
+  Call::HotplugFlags.to_h.each{|k,v| const_set(k,v) }
 
   # Base class of libusb errors
   class Error < RuntimeError
@@ -73,6 +75,9 @@ module LIBUSB
   POLLIN = 1
   POLLOUT = 4
 
+  # Wildcard matching for hotplug events.
+  HOTPLUG_MATCH_ANY = -1
+
 
   # http://www.usb.org/developers/defined_class
   # @private

data/lib/libusb/context.rb

@@ -70,6 +70,31 @@ module LIBUSB
       end
     end
 
+    class HotplugCallback < FFI::Struct
+      layout :handle,  :int
+
+      attr_reader :context
+
+      # @private
+      def initialize(context, ctx, callbacks)
+        super()
+        @context = context
+        @ctx = ctx
+        @callbacks = callbacks
+      end
+
+      # Deregisters the hotplug callback.
+      #
+      # Deregister a callback from a {Context}. This function is safe to call from within
+      # a hotplug callback.
+      #
+      # Since libusb version 1.0.16.
+      def deregister
+        Call.libusb_hotplug_deregister_callback(@ctx, self[:handle])
+        @callbacks.delete(self[:handle])
+      end
+    end
+
 
     # Initialize libusb context.
     def initialize
@@ -79,6 +104,7 @@ module LIBUSB
       @ctx = m.read_pointer
       @on_pollfd_added = nil
       @on_pollfd_removed = nil
+      @hotplug_callbacks = {}
     end
 
     # Deinitialize libusb.
@@ -304,5 +330,79 @@ module LIBUSB
       end
       Call.libusb_set_pollfd_notifiers @ctx, @on_pollfd_added, @on_pollfd_removed, nil
     end
+
+    # Register a hotplug event notification.
+    #
+    # Register a callback with the {LIBUSB::Context}. The callback will fire
+    # when a matching event occurs on a matching device. The callback is armed
+    # until either it is deregistered with {HotplugCallback#deregister} or the
+    # supplied block returns +:finish+ to indicate it is finished processing events.
+    #
+    # If the flag {Call::HotplugFlags HOTPLUG_ENUMERATE} is passed the callback will be
+    # called with a {Call::HotplugEvents :HOTPLUG_EVENT_DEVICE_ARRIVED} for all devices
+    # already plugged into the machine. Note that libusb modifies its internal
+    # device list from a separate thread, while calling hotplug callbacks from
+    # {#handle_events}, so it is possible for a device to already be present
+    # on, or removed from, its internal device list, while the hotplug callbacks
+    # still need to be dispatched. This means that when using
+    # {Call::HotplugFlags HOTPLUG_ENUMERATE}, your callback may be called twice for the arrival
+    # of the same device, once from {#on_hotplug_event} and once
+    # from {#handle_events}; and/or your callback may be called for the
+    # removal of a device for which an arrived call was never made.
+    #
+    # Since libusb version 1.0.16.
+    #
+    # @param [Hash] args
+    # @option args [Fixnum,Symbol] :events  bitwise or of events that will trigger this callback.
+    #   Default is +LIBUSB::HOTPLUG_EVENT_DEVICE_ARRIVED|LIBUSB::HOTPLUG_EVENT_DEVICE_LEFT+ .
+    #   See {Call::HotplugEvents HotplugEvents}
+    # @option args [Fixnum,Symbol] :flags hotplug callback flags. Default is 0. See {Call::HotplugFlags HotplugFlags}
+    # @option args [Fixnum] :vendor_id the vendor id to match. Default is {HOTPLUG_MATCH_ANY}.
+    # @option args [Fixnum] :product_id the product id to match. Default is {HOTPLUG_MATCH_ANY}.
+    # @option args [Fixnum] :dev_class the device class to match. Default is {HOTPLUG_MATCH_ANY}.
+    # @return [HotplugCallback]  The handle to the registered callback.
+    #
+    # @yieldparam [Device] device  the attached or removed {Device} is yielded to the block
+    # @yieldparam [Symbol] event  a {Call::HotplugEvents HotplugEvents} symbol
+    # @yieldreturn [Symbol] +:finish+ to deregister the callback, +:repeat+ to receive additional events
+    # @raise [ArgumentError, LIBUSB::Error] in case of failure
+    def on_hotplug_event(args={}, &block)
+      events = args.delete(:events) || (HOTPLUG_EVENT_DEVICE_ARRIVED | HOTPLUG_EVENT_DEVICE_LEFT)
+      flags = args.delete(:flags) || 0
+      vendor_id = args.delete(:vendor_id) || HOTPLUG_MATCH_ANY
+      product_id = args.delete(:product_id) || HOTPLUG_MATCH_ANY
+      dev_class = args.delete(:dev_class) || HOTPLUG_MATCH_ANY
+      raise ArgumentError, "invalid params #{args.inspect}" unless args.empty?
+
+      handle = HotplugCallback.new self, @ctx, @hotplug_callbacks
+
+      block2 = proc do |ctx, pDevice, event, _user_data|
+        raise "internal error: unexpected context" unless @ctx==ctx
+        dev = Device.new @ctx, pDevice
+
+        blres = block.call(dev, event)
+
+        case blres
+        when :finish
+          1
+        when :repeat
+          0
+        else
+          raise ArgumentError, "hotplug event handler must return :finish or :repeat"
+        end
+      end
+
+      res = Call.libusb_hotplug_register_callback(@ctx,
+                  events, flags,
+                  vendor_id, product_id, dev_class,
+                  block2, nil, handle)
+
+      LIBUSB.raise_error res, "in libusb_hotplug_register_callback" if res<0
+
+      # Avoid GC'ing of the block:
+      @hotplug_callbacks[handle[:handle]] = block2
+
+      return handle
+    end
   end
 end

data/lib/libusb/dev_handle.rb

@@ -225,6 +225,33 @@ module LIBUSB
       LIBUSB.raise_error res, "in libusb_attach_kernel_driver" if res!=0
     end
 
+    # @private
+    if Call.respond_to?(:libusb_set_auto_detach_kernel_driver)
+
+      # @method auto_detach_kernel_driver=
+      # Enable/disable libusb's automatic kernel driver detachment.
+      #
+      # When this is enabled libusb will automatically detach the kernel driver on an
+      # interface when claiming the interface, and attach it when releasing the
+      # interface.
+      #
+      # Automatic kernel driver detachment is disabled on newly opened device handles by
+      # default.
+      #
+      # On platforms which do not have CAP_SUPPORTS_DETACH_KERNEL_DRIVER this
+      # function will return ERROR_NOT_SUPPORTED, and libusb will continue as if
+      # this function was never called.
+      #
+      # Available since libusb-1.0.16.
+      #
+      # @param [Boolean] enable    whether to enable or disable auto kernel driver detachment
+      #
+      # @see LIBUSB.has_capability?
+      def auto_detach_kernel_driver=(enable)
+        res = Call.libusb_set_auto_detach_kernel_driver(@pHandle, enable ? 1 : 0)
+        LIBUSB.raise_error res, "in libusb_set_auto_detach_kernel_driver" if res!=0
+      end
+    end
 
     # Perform a USB bulk transfer.
     #

data/lib/libusb/device.rb

@@ -95,7 +95,7 @@ module LIBUSB
       # Available since libusb-1.0.12.
       #
       # @return [Fixnum, nil]  the port number (+nil+ if not available)
-      # @see #port_path
+      # @see #port_numbers
       def port_number
         r = Call.libusb_get_port_number(@pDev)
         r==0 ? nil : r
@@ -105,7 +105,7 @@ module LIBUSB
       # Available since libusb-1.0.12.
       #
       # @return [Device, nil]  the device parent or +nil+ if not available
-      # @see #port_path
+      # @see #port_numbers
       def parent
         pppDevs = FFI::MemoryPointer.new :pointer
         Call.libusb_get_device_list(@context.instance_variable_get(:@ctx), pppDevs)
@@ -122,13 +122,19 @@ module LIBUSB
       # @return [Array<Fixnum>]
       # @see #parent
       # @see #port_number
-      def port_path
+      def port_numbers
         # As per the USB 3.0 specs, the current maximum limit for the depth is 7.
         path_len = 7
         pPath = FFI::MemoryPointer.new :pointer, path_len
-        l = Call.libusb_get_port_path(@context.instance_variable_get(:@ctx), @pDev, pPath, path_len)
+
+        l = if Call.respond_to?(:libusb_get_port_numbers)
+          Call.libusb_get_port_numbers(@pDev, pPath, path_len)
+        else
+          Call.libusb_get_port_path(@context.instance_variable_get(:@ctx), @pDev, pPath, path_len)
+        end
         pPath.read_array_of_uint8(l)
       end
+      alias port_path port_numbers
     end
 
     if Call.respond_to?(:libusb_get_device_speed)

data/lib/libusb/version_gem.rb

@@ -15,5 +15,5 @@
 
 module LIBUSB
   # Library version of libusb for Ruby
-  VERSION = "0.3.4"
+  VERSION = "0.4.0"
 end

data/test/test_libusb_capability.rb

@@ -13,10 +13,10 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb"
 
-class TestLibusbCapability < Test::Unit::TestCase
+class TestLibusbCapability < Minitest::Test
   def test_version_parts
     assert LIBUSB.has_capability?(:CAP_HAS_CAPABILITY)
   end

data/test/test_libusb_compat.rb

@@ -13,10 +13,10 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb/compat"
 
-class TestLibusbCompat < Test::Unit::TestCase
+class TestLibusbCompat < Minitest::Test
   include USB
 
   attr_accessor :usb

data/test/test_libusb_compat_mass_storage.rb

@@ -13,10 +13,10 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb/compat"
 
-class TestLibusbCompatMassStorage < Test::Unit::TestCase
+class TestLibusbCompatMassStorage < Minitest::Test
   include USB
 
   attr_accessor :devh

data/test/test_libusb_descriptors.rb

@@ -13,10 +13,10 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb"
 
-class TestLibusbDescriptors < Test::Unit::TestCase
+class TestLibusbDescriptors < Minitest::Test
   include LIBUSB
 
   attr_accessor :usb
@@ -165,6 +165,8 @@ class TestLibusbDescriptors < Test::Unit::TestCase
         assert_operator dev.bus_number, :>=, 0, "#{dev.inspect} should have a bus_number"
         assert_operator dev.device_address, :>=, 0, "#{dev.inspect} should have a device_address"
         assert_operator([:SPEED_UNKNOWN, :SPEED_LOW, :SPEED_FULL, :SPEED_HIGH, :SPEED_SUPER], :include?, dev.device_speed, "#{dev.inspect} should have a device_speed")
+        path = dev.port_numbers
+        assert_kind_of Array, path, "#{dev.inspect} should have port_numbers"
         path = dev.port_path
         assert_kind_of Array, path, "#{dev.inspect} should have a port_path"
         path.each do |port|

data/test/test_libusb_event_machine.rb

@@ -13,12 +13,12 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb"
 require "libusb/eventmachine"
 require "eventmachine"
 
-class TestLibusbEventMachine < Test::Unit::TestCase
+class TestLibusbEventMachine < Minitest::Test
   include LIBUSB
   BOMS_GET_MAX_LUN = 0xFE
 

data/test/test_libusb_gc.rb

@@ -16,10 +16,10 @@
 # These tests should be started with valgrind to check for
 # invalid memmory access.
 
-require "test/unit"
+require "minitest/autorun"
 require "libusb"
 
-class TestLibusbGc < Test::Unit::TestCase
+class TestLibusbGc < Minitest::Test
   include LIBUSB
 
   def get_some_endpoint

data/test/test_libusb_hotplug.rb

@@ -0,0 +1,115 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require "minitest/autorun"
+require "libusb"
+
+class TestLibusbHotplug < Minitest::Test
+  include LIBUSB
+
+  attr_reader :ctx
+
+  def setup
+    @ctx = Context.new
+  end
+
+  def teardown
+    @ctx.exit
+  end
+
+  def test_enumerate
+    devs = []
+    ctx.on_hotplug_event :flags => HOTPLUG_ENUMERATE do |dev, event|
+      devs << dev
+      assert_equal :HOTPLUG_EVENT_DEVICE_ARRIVED, event
+      :repeat
+    end
+    # Not really necessary, but just to be sure that the callback was called:
+    ctx.handle_events 0
+
+    assert_equal ctx.devices.sort, devs.sort
+  end
+
+  def test_enumerate_with_left
+    devs = []
+    ctx.on_hotplug_event :flags => HOTPLUG_ENUMERATE, :events => HOTPLUG_EVENT_DEVICE_LEFT do |dev, event|
+      devs << dev
+      assert_equal :HOTPLUG_EVENT_DEVICE_ARRIVED, event
+      :repeat
+    end
+    # Not really necessary, but just to be sure that the callback was called:
+    ctx.handle_events 0
+
+    assert_equal [], devs.sort, "Enumerate should not send any LEFT events"
+  end
+
+  def test_deregister
+    handle1 = ctx.on_hotplug_event{ assert false, "Callback should not be called" }
+    handle2 = ctx.on_hotplug_event{ assert false, "Callback should not be called" }
+    handle1.deregister
+    handle2.deregister
+    ctx.handle_events 0
+  end
+
+  def test_wrong_yieldreturn
+    ex = assert_raises(ArgumentError) do
+      ctx.on_hotplug_event :flags => :HOTPLUG_ENUMERATE do |dev, event|
+      end
+    end
+
+    assert_match(/:finish.*:repeat/, ex.to_s, "Should give a useful hint")
+  end
+
+  def test_context
+    handle = ctx.on_hotplug_event do |dev, event|
+    end
+    assert_equal ctx, handle.context, "The callback handle should have it's context"
+  end
+
+  def test_real_device_plugging_and_yieldreturn_and_gc_and_deregister
+    # This callback should be triggered once
+    devs = []
+    ctx.on_hotplug_event do |dev, event|
+      devs << [dev, event]
+      :finish
+    end
+
+    # This callback should be triggered twice
+    devs2 = []
+    ctx.on_hotplug_event do |dev, event|
+      devs2 << [dev, event]
+      puts format("  %p: %p", event, dev)
+      :repeat
+    end
+
+    # This callback should never be triggered
+    handle = ctx.on_hotplug_event{ assert false, "Deregistered callback should never be called" }
+
+    # GC shouldn't free any relevant callbacks or blocks
+    GC.start
+
+    print "\nPlease add and remove an USB device (2*5 sec): "
+    handle.deregister
+    ctx.handle_events 0
+    ctx.handle_events 5000
+    ctx.handle_events 5000
+
+    skip if devs.empty? && devs2.empty?
+    assert_equal 1, devs.length, "Should be deregistered after the first event"
+    assert_equal 2, devs2.length, "Should have received two events"
+    assert_operator devs2.map(&:last), :include?, :HOTPLUG_EVENT_DEVICE_ARRIVED, "Should have received ARRIVED"
+    assert_operator devs2.map(&:last), :include?, :HOTPLUG_EVENT_DEVICE_LEFT, "Should have received LEFT"
+  end
+end