libusb 0.1.1 → 0.1.2

data/History.txt

@@ -1,3 +1,10 @@
+=== 0.1.2 / 2012-03-14
+
+* Mark all blocking functions as blocking in FFI, so that parallel threads are not blocked
+* Add method Device#open_interface
+* Add block variant to #claim_interface
+* update API documentation
+
 === 0.1.1 / 2011-12-09
 
 * avoid ffi calls with :blocking=>true, als long as it isn't stable on win32

data/Manifest.txt

@@ -13,3 +13,4 @@ test/test_libusb_descriptors.rb
 test/test_libusb_gc.rb
 test/test_libusb_iso_transfer.rb
 test/test_libusb_mass_storage.rb
+test/test_libusb_mass_storage2.rb

data/README.rdoc

@@ -17,7 +17,7 @@ LIBUSB for Ruby is covered by the GNU Lesser General Public License version 3.
 
 == FEATURES:
 * Access to descriptors of devices, configurations, interfaces, settings and endpoints
-* Synchronous and asynchronous communication for bulk, control and interrupt transfers
+* Synchronous and asynchronous communication for bulk, control, interrupt and isochronous transfers
 * Compatibility layer for ruby-usb[http://www.a-k-r.org/ruby-usb/] (API based on libusb-0.1). See {::USB} for description.
 
 == SYNOPSIS:
@@ -27,9 +27,9 @@ LIBUSB for Ruby is covered by the GNU Lesser General Public License version 3.
   usb = LIBUSB::Context.new
   device = usb.devices(:idVendor => 0x04b4, :idProduct => 0x8613).first
   device.open do |handle|
-    handle.claim_interface(0)
-    handle.control_transfer(:bmRequestType => 0x40, :bRequest => 0xa0, :wValue => 0xe600, :wIndex => 0x0000, :dataOut => 1.chr)
-    handle.release_interface(0)
+    handle.claim_interface(0) do
+      handle.control_transfer(:bmRequestType => 0x40, :bRequest => 0xa0, :wValue => 0xe600, :wIndex => 0x0000, :dataOut => 1.chr)
+    end
   end
 {LIBUSB::Context#devices} is used to get all or only particular devices.
 After opening the {LIBUSB::Device} the resulting {LIBUSB::DevHandle} can be
@@ -55,9 +55,9 @@ maximum packet size.
 
 == REQUIREMENTS:
 
-* libusb version 1.0 or greater
+* libusb version 1.0 or greater (bundled with Windows binary gem)
 * FFI-gem[http://github.com/ffi/ffi]
-* Linux, MacOSX or Windows system
+* Linux, MacOSX or Windows system with Ruby MRI 1.8.7/1.9.x or JRuby
 
 == INSTALL:
 
@@ -65,8 +65,7 @@ maximum packet size.
 
 In order to use LIBUSB, you need the libusb-1.0 library (but not its header files).
 * On Debian and Ubuntu system, install the +libusb-1.0-0+ package.
-* The gem for Windows comes with a precompiled +libusb.dll+ and can be used
-  together with a precompiled FFI-gem, so there is no need for a compiler.
+* The gem for Windows comes with a precompiled +libusb.dll+, so there is no need for a compiler.
 
 Latest code can be used in this way:
 

data/Rakefile

@@ -93,9 +93,8 @@ file LIBUSB_MAKEFILE => LIBUSB_CONFIGURE do |t|
     options = [
       '--target=i386-mingw32',
       "--host=#{Rake::ExtensionCompiler.mingw_host}",
+      "--build=#{RbConfig::CONFIG["host"]}",
     ]
-    build_host = `sh config.guess`.chomp
-    options << "--build=#{build_host}" unless build_host.to_s.empty?
 
     configure_path = STATIC_LIBUSB_BUILDDIR + 'configure'
     cmd = [ configure_path.to_s, *options ]

data/lib/libusb.rb

@@ -18,7 +18,7 @@ require 'ffi'
 
 
 module LIBUSB
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 
   module Call
     extend FFI::Library
@@ -165,15 +165,15 @@ module LIBUSB
     attach_function 'libusb_close', [:pointer], :void
     attach_function 'libusb_get_device', [:libusb_device_handle], :pointer
 
-    attach_function 'libusb_set_configuration', [:libusb_device_handle, :int], :int
+    attach_function 'libusb_set_configuration', [:libusb_device_handle, :int], :int, :blocking=>true
     attach_function 'libusb_claim_interface', [:libusb_device_handle, :int], :int
-    attach_function 'libusb_release_interface', [:libusb_device_handle, :int], :int
+    attach_function 'libusb_release_interface', [:libusb_device_handle, :int], :int, :blocking=>true
 
     attach_function 'libusb_open_device_with_vid_pid', [:pointer, :int, :int], :pointer
 
-    attach_function 'libusb_set_interface_alt_setting', [:libusb_device_handle, :int, :int], :int
-    attach_function 'libusb_clear_halt', [:libusb_device_handle, :int], :int
-    attach_function 'libusb_reset_device', [:libusb_device_handle], :int
+    attach_function 'libusb_set_interface_alt_setting', [:libusb_device_handle, :int, :int], :int, :blocking=>true
+    attach_function 'libusb_clear_halt', [:libusb_device_handle, :int], :int, :blocking=>true
+    attach_function 'libusb_reset_device', [:libusb_device_handle], :int, :blocking=>true
 
     attach_function 'libusb_kernel_driver_active', [:libusb_device_handle, :int], :int
     attach_function 'libusb_detach_kernel_driver', [:libusb_device_handle, :int], :int
@@ -186,7 +186,7 @@ module LIBUSB
     attach_function 'libusb_cancel_transfer', [:pointer], :int
     attach_function 'libusb_free_transfer', [:pointer], :void
 
-    attach_function 'libusb_handle_events', [:libusb_context], :int
+    attach_function 'libusb_handle_events', [:libusb_context], :int, :blocking=>true
 
 
     callback :libusb_transfer_cb_fn, [:pointer], :void
@@ -971,7 +971,7 @@ module LIBUSB
       LIBUSB.raise_error res, "in libusb_get_device_descriptor" if res!=0
     end
 
-    # Open a device and obtain a device handle.
+    # Open the device and obtain a device handle.
     #
     # A handle allows you to perform I/O on the device in question.
     # This is a non-blocking function; no requests are sent over the bus.
@@ -996,6 +996,21 @@ module LIBUSB
       end
     end
 
+    # Open the device and claim an interface.
+    #
+    # This is a convenience method to {Device#open} and {DevHandle#claim_interface}.
+    # Must be called with a block. When the block has finished, the interface
+    # will be released and the device will be closed.
+    #
+    # @param [Interface, Fixnum] interface  the interface or it's bInterfaceNumber you wish to claim
+    def open_interface(interface)
+      open do |dev|
+        dev.claim_interface(interface) do
+          yield dev
+        end
+      end
+    end
+
     # Get the number of the bus that a device is connected to.
     def bus_number
       Call.libusb_get_bus_number(@pDev)
@@ -1199,11 +1214,20 @@ module LIBUSB
     #
     # This is a non-blocking function.
     #
+    # If called with a block, the device handle is passed through to the block
+    # and the interface is released when the block has finished.
+    #
     # @param [Interface, Fixnum] interface  the interface or it's bInterfaceNumber you wish to claim
     def claim_interface(interface)
       interface = interface.bInterfaceNumber if interface.respond_to? :bInterfaceNumber
       res = Call.libusb_claim_interface(@pHandle, interface)
       LIBUSB.raise_error res, "in libusb_claim_interface" if res!=0
+      return self unless block_given?
+      begin
+        yield self
+      ensure
+        release_interface(interface)
+      end
     end
 
     # Release an interface previously claimed with {DevHandle#claim_interface}.
@@ -1272,8 +1296,7 @@ module LIBUSB
     #   to activate or the bInterfaceNumber of the previously-claimed interface
     # @param [Fixnum, nil] alternate_setting  the bAlternateSetting of the alternate setting to activate
     #   (only if first param is a Fixnum)
-    def set_interface_alt_setting(setting_or_interface_number,
-alternate_setting=nil)
+    def set_interface_alt_setting(setting_or_interface_number, alternate_setting=nil)
       alternate_setting ||= setting_or_interface_number.bAlternateSetting if setting_or_interface_number.respond_to? :bAlternateSetting
       setting_or_interface_number = setting_or_interface_number.bInterfaceNumber if setting_or_interface_number.respond_to? :bInterfaceNumber
       res = Call.libusb_set_interface_alt_setting(@pHandle, setting_or_interface_number, alternate_setting)
@@ -1356,7 +1379,7 @@ alternate_setting=nil)
     # The direction of the transfer is inferred from the direction bits of the
     # endpoint address.
     #
-    # For bulk reads, the :dataIn param indicates the maximum length of data you are
+    # For bulk reads, the +:dataIn+ param indicates the maximum length of data you are
     # expecting to receive. If less data arrives than expected, this function will
     # return that data.
     #
@@ -1373,6 +1396,8 @@ alternate_setting=nil)
     # @param [Endpoint, Fixnum] :endpoint  the (address of a) valid endpoint to communicate with
     # @param [String] :dataOut  the data to send with an outgoing transfer
     # @param [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
+    # @param [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
+    #   up due to no response being received. For an unlimited timeout, use value 0. Defaults to 1000 ms.
     #
     # @return [Fixnum] Number of bytes sent for an outgoing transfer
     # @return [String] Received data for an ingoing transfer
@@ -1412,7 +1437,7 @@ alternate_setting=nil)
     # The direction of the transfer is inferred from the direction bits of the
     # endpoint address.
     #
-    # For interrupt reads, the :dataIn param indicates the maximum length of data you
+    # For interrupt reads, the +:dataIn+ param indicates the maximum length of data you
     # are expecting to receive. If less data arrives than expected, this function will
     # return that data.
     #
@@ -1431,6 +1456,8 @@ alternate_setting=nil)
     # @param [Endpoint, Fixnum] :endpoint  the (address of a) valid endpoint to communicate with
     # @param [String] :dataOut  the data to send with an outgoing transfer
     # @param [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
+    # @param [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
+    #   up due to no response being received. For an unlimited timeout, use value 0. Defaults to 1000 ms.
     #
     # @return [Fixnum] Number of bytes sent for an outgoing transfer
     # @return [String] Received data for an ingoing transfer
@@ -1467,7 +1494,7 @@ alternate_setting=nil)
 
     # Perform a USB control transfer.
     #
-    # The direction of the transfer is inferred from the bmRequestType field of the
+    # The direction of the transfer is inferred from the +:bmRequestType+ field of the
     # setup packet.
     #
     # @param [Fixnum] :bmRequestType   the request type field for the setup packet
@@ -1479,7 +1506,7 @@ alternate_setting=nil)
     # @param [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
     #   (excluding setup packet)
     # @param [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
-    #   up due to no response being received. For an unlimited timeout, use value 0.
+    #   up due to no response being received. For an unlimited timeout, use value 0. Defaults to 1000 ms.
     #
     # @return [Fixnum] Number of bytes sent (excluding setup packet) for outgoing transfer
     # @return [String] Received data (without setup packet) for ingoing transfer

data/test/test_libusb_mass_storage.rb

@@ -215,7 +215,7 @@ class TestLibusbMassStorage < Test::Unit::TestCase
       end
     end
     assert_raise(CSWError, LIBUSB::ERROR_TIMEOUT) do
-      invalid_command
+      bulk_transfer(:endpoint=>endpoint_in, :dataIn=>123)
     end
     th.kill
     dev.clear_halt(endpoint_in)

data/test/test_libusb_mass_storage2.rb

@@ -0,0 +1,69 @@
+# 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 "test/unit"
+require "libusb"
+
+class TestLibusbMassStorage2 < Test::Unit::TestCase
+  include LIBUSB
+
+  attr_accessor :usb
+  attr_accessor :device
+
+  def setup
+    @usb = Context.new
+    @usb.debug = 3
+    @device = usb.devices( :bClass=>CLASS_MASS_STORAGE, :bSubClass=>[0x06,0x01], :bProtocol=>0x50 ).last
+    abort "no mass storage device found" unless @device
+
+    # Ensure kernel driver is detached
+    device.open do |dev|
+      if RUBY_PLATFORM=~/linux/i && dev.kernel_driver_active?(0)
+        dev.detach_kernel_driver(0)
+      end
+    end
+  end
+
+  def teardown
+  end
+
+  def test_open_with_block
+    device.open do |dev|
+      assert_kind_of DevHandle, dev
+      assert_kind_of String, dev.string_descriptor_ascii(1)
+    end
+  end
+
+  def test_claim_interface_with_block
+    res = device.open do |dev|
+      dev.claim_interface(0) do |dev2|
+        assert_kind_of DevHandle, dev2
+        assert_kind_of String, dev2.string_descriptor_ascii(1)
+        12345
+      end
+    end
+    assert_equal 12345, res, "Block versions should pass through the result"
+  end
+
+  def test_open_interface
+    res = device.open_interface(0) do |dev|
+      assert_kind_of DevHandle, dev
+      assert_kind_of String, dev.string_descriptor_ascii(1)
+      12345
+    end
+    assert_equal 12345, res, "Block versions should pass through the result"
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libusb
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-09 00:00:00.000000000 Z
+date: 2012-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &20041800 !ruby/object:Gem::Requirement
+  requirement: &7425600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *20041800
+  version_requirements: *7425600
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &20040960 !ruby/object:Gem::Requirement
+  requirement: &7424760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,18 +32,29 @@ dependencies:
         version: '0.6'
   type: :development
   prerelease: false
-  version_requirements: *20040960
+  version_requirements: *7424760
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: &7423680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: *7423680
 - !ruby/object:Gem::Dependency
   name: hoe
-  requirement: &20040440 !ruby/object:Gem::Requirement
+  requirement: &7422380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.12'
+        version: '2.16'
   type: :development
   prerelease: false
-  version_requirements: *20040440
+  version_requirements: *7422380
 description: LIBUSB is a Ruby binding that gives Ruby programmers access to all functionality
   of libusb, version 1.0
 email:
@@ -70,7 +81,7 @@ files:
 - test/test_libusb_gc.rb
 - test/test_libusb_iso_transfer.rb
 - test/test_libusb_mass_storage.rb
-- test/test_libusb_keyboard.rb
+- test/test_libusb_mass_storage2.rb
 homepage: http://github.com/larskanis/libusb
 licenses: []
 post_install_message: 
@@ -94,15 +105,15 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: libusb
-rubygems_version: 1.8.10
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Access USB devices from Ruby via libusb-1.0
 test_files:
-- test/test_libusb_compat_mass_storage.rb
-- test/test_libusb_gc.rb
+- test/test_libusb_compat.rb
 - test/test_libusb_iso_transfer.rb
+- test/test_libusb_mass_storage2.rb
 - test/test_libusb_descriptors.rb
-- test/test_libusb_compat.rb
-- test/test_libusb_keyboard.rb
 - test/test_libusb_mass_storage.rb
+- test/test_libusb_compat_mass_storage.rb
+- test/test_libusb_gc.rb

data/test/test_libusb_keyboard.rb

@@ -1,50 +0,0 @@
-# This test requires a connected, but not mounted mass storage device with
-# read/write access allowed. Based on the following specifications:
-#   http://www.usb.org/developers/devclass_docs/usbmassbulk_10.pdf
-#   http://en.wikipedia.org/wiki/SCSI_command
-#
-
-require "test/unit"
-require "libusb"
-
-class TestLibusbKeyboard < Test::Unit::TestCase
-  include LIBUSB
-
-  attr_accessor :usb
-  attr_accessor :device
-  attr_accessor :dev
-  attr_accessor :endpoint_in
-  attr_accessor :endpoint_out
-
-  def setup
-    @usb = Context.new
-    @usb.debug = 3
-
-    @device = usb.devices( :bDeviceClass=>CLASS_HID, :bDeviceProtocol=>1 ).first
-    abort "no keyboard device found" unless @device
-
-    @endpoint_in = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN != 0 }.bEndpointAddress
-    @endpoint_out = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN == 0 }.bEndpointAddress
-
-    @dev = @device.open
-
-    if RUBY_PLATFORM=~/linux/i && dev.kernel_driver_active?(0)
-      dev.detach_kernel_driver(0)
-    end
-    dev.claim_interface(0)
-
-    # clear any pending data
-    dev.clear_halt(endpoint_in)
-  end
-
-  def teardown
-    dev.release_interface(0) if dev
-    dev.close if dev
-  end
-
-  def test_read
-    data_length = 8
-    recv = dev.interrupt_transfer(:endpoint=>endpoint_in, :dataIn=>data_length)
-    p recv
-  end
-end