libusb 0.2.2-x86-mingw32 → 0.3.0-x86-mingw32

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+lib/libusb-1.0*
+lib/pkgconfig
+include
+tmp

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - "1.8.7"
+  - "1.9.2"
+  - "1.9.3"
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+script: bundle exec rake travis

data/.yardopts

@@ -1 +1,6 @@
---title "libusb-1.0 Ruby Interface" --no-private lib/**/*.rb
+--title "libusb-1.0 Ruby Interface"
+--no-private
+lib/**/*.rb
+-
+README.md
+History.md

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in libusb.gemspec
+gemspec
+
+group :test do
+  gem 'eventmachine'
+end
+
+platforms :rbx do
+  # travis currently runs a slightly older version of rbx,
+  # that needs this special ffi version.
+  if ENV['TRAVIS']
+    gem 'ffi', :git => "git://github.com/ffi/ffi.git", :ref => '5f31908'
+  end
+end

data/{History.txt → History.md}

@@ -1,40 +1,52 @@
-=== 0.2.2 / 2012-10-19
-
+0.3.0 / 2013-01-21
+------------------
+* Build bundled libusbx sources in case libusb-1.0.so can not be loaded from the system
+* Replace Hoe with Bundler
+* Add timeout and completion_flag to Context#handle_events
+* Add asynchronous DevHandle#{control|interrupt|bulk}_transfer method variants
+* Add the ability to retrieve the data already transfered when it comes to an exception
+* Add notification API for libusb's file describtors for event driven USB transfers
+* Add experimental integration to EventMachine
+* Add several convenience methods to descriptors
+* Add missing return code checks to libusb_init() and libusb_get_device_list()
+
+0.2.2 / 2012-10-19
+------------------
 * Add method Interface#bInterfaceNumber
 * Fix methods (#claim_interface, #detach_kernel_driver) with Interface-type parameter
 * update to libusbx-1.0.14 for windows build
 
-=== 0.2.1 / 2012-09-25
-
+0.2.1 / 2012-09-25
+------------------
 * Rename Configuration#maxPower to #bMaxPower as done in libusbx-1.0.13 and in ruby-usb.gem
 * update to libusbx-1.0.13 for windows build (with support for libusbK and libusb0)
 
-=== 0.2.0 / 2012-06-15
-
+0.2.0 / 2012-06-15
+------------------
 * Divide up the libusb library across multiple files, required with autoload
 * add methods: LIBUSB.has_capability?, Device#device_speed (libusb-1.0.9+)
 * add possibility to read out libusb version: LIBUSB.version (libusbx-1.0.10+)
 * add methods: Device#parent, Device#port_number, Device#port_path (libusbx-1.0.12+)
 * switch to libusbx-1.0.12 for windows build
 
-=== 0.1.3 / 2012-03-15
-
+0.1.3 / 2012-03-15
+-------------------
 * Add documentation of descriptor accessors
 * Fix #extra accessor of Configuration, Setting and Endpoint
 
-=== 0.1.2 / 2012-03-14
-
+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
-
+0.1.1 / 2011-12-09
+------------------
 * avoid ffi calls with :blocking=>true, als long as it isn't stable on win32
 
-=== 0.1.0 / 2011-10-01
-
+0.1.0 / 2011-10-01
+------------------
 * add test suite based on mass storage devices
 * usable async transfers
 * migration to rake-compiler and hoe
@@ -45,6 +57,6 @@
 * add LIBUSB constants
 * downcase methods names
 
-=== 0.0.1 / 2009-06-23
-
+0.0.1 / 2009-06-23
+------------------
 * first public release

data/README.md

@@ -0,0 +1,144 @@
+<!-- -*- coding: utf-8 -*- -->
+
+[![Build Status](https://travis-ci.org/larskanis/libusb.png?branch=debug_travis)](https://travis-ci.org/larskanis/libusb)
+
+Access USB devices from Ruby
+============================
+
+LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices.
+
+* [libusb](http://libusbx.org) is a library that gives full access to devices connected via the USB bus. No special kernel driver is thus necessary for accessing USB devices.
+* This Ruby binding supports the API version 1.0 of [libusb](http://libusbx.org). Note that the old "legacy" version 0.1.x of libusb uses a completely different API that is covered by the ruby extension [ruby-usb](http://www.a-k-r.org/ruby-usb/) .
+
+
+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, 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
+--------
+See [the documentation](http://rubydoc.info/gems/libusb/frames) for a full API description.
+
+```ruby
+require "libusb"
+
+usb = LIBUSB::Context.new
+device = usb.devices(:idVendor => 0x04b4, :idProduct => 0x8613).first
+device.open_interface(0) do |handle|
+  handle.control_transfer(:bmRequestType => 0x40, :bRequest => 0xa0, :wValue => 0xe600, :wIndex => 0x0000, :dataOut => 1.chr)
+end
+```
+{LIBUSB::Context#devices} is used to get all or only particular devices.
+After {LIBUSB::Device#open_interface opening and claiming} the {LIBUSB::Device} the resulting {LIBUSB::DevHandle} can be
+used to communicate with the connected USB device
+by {LIBUSB::DevHandle#control_transfer}, {LIBUSB::DevHandle#bulk_transfer},
+{LIBUSB::DevHandle#interrupt_transfer} or by using the {LIBUSB::Transfer} classes.
+
+A {LIBUSB::Device} can also be used to retrieve information about it,
+by using the device descriptor attributes.
+A {LIBUSB::Device} could have several configurations. You can then decide of which
+configuration to enable. You can only enable one configuration at a time.
+
+Each {LIBUSB::Configuration} has one or more interfaces. These can be seen as functional group
+performing a single feature of the device.
+
+Each {LIBUSB::Interface} has at least one {LIBUSB::Setting}. The first setting is always default.
+An alternate setting can be used independent on each interface.
+
+Each {LIBUSB::Setting} specifies it's own set of communication endpoints.
+Each {LIBUSB::Endpoint} specifies the type of transfer, direction, polling interval and
+maximum packet size.
+
+
+Prerequisites
+-------------
+
+* Linux, MacOSX or Windows system with Ruby MRI 1.8.7/1.9.x, JRuby or recent version of Rubinius
+* [libusb](http://libusb.org) or [libusbx](http://libusbx.org) library version 1.0.8+ :
+  * Debian or Ubuntu:
+
+      ```
+      $ sudo apt-get install libusb-1.0-0-dev
+      ```
+  * OS-X: install with homebrew:
+
+      ```
+      $ brew install libusb
+      ```
+    or macports:
+
+      ```
+      $ port install libusb
+      ```
+  * Windows: libusb.gem already comes with a precompiled `libusb.dll`, but you need to install a device driver (see below)
+
+
+Install
+-------
+
+    $ gem install libusb
+
+Latest code can be used in this way:
+
+    $ git clone git://github.com/larskanis/libusb.git
+    $ rake install_gem
+
+
+Usage on Windows
+----------------
+
+In contrast to Linux, any access to an USB device by LIBUSB on Windows requires a proper driver
+installed in the system. Fortunately creating such a driver is quite easy with
+[Zadig](http://sourceforge.net/projects/libwdi/files/zadig/). Select the interesting USB device,
+choose WinUSB driver and press "Install Driver". That's it. You may take the generated output directory
+with it's INI-file and use it for driver installation on other 32 or 64 bit Windows
+systems.
+
+
+Cross compiling for Windows
+---------------------------
+
+Libusb-gem can be build on a linux or darwin host for the win32 platform,
+using the mingw cross compiler collection. Libusb is downloaded from source
+git repo, cross compiled and included in the generated libusb.gem.
+
+Install mingw32. On a debian based system this should work:
+
+    $ apt-get install mingw32
+
+On MacOS X, if you have MacPorts installed:
+
+    $ port install i386-mingw32-gcc
+
+Download and cross compile libusb for win32:
+
+    $ rake cross gem
+
+If everything works, there should be `libusb-VERSION-x86-mingw32.gem` in the pkg
+directory.
+
+EventMachine integration
+------------------------
+
+Libusb for Ruby comes with an experimental integration to [EventMachine](http://rubyeventmachine.com/).
+That API is currently proof of concept - see {LIBUSB::Context#eventmachine_register}.
+If you're experienced with EventMachine, please leave a comment.
+
+
+Resources
+---------
+
+* Project's home page: http://github.com/larskanis/libusb
+* API documentation: http://rubydoc.info/gems/libusb/frames
+* Mailinglist: http://rubyforge.org/mailman/listinfo/libusb-hackers
+* Overall introduction to USB: http://www.usbmadesimple.co.uk
+
+Todo
+----
+
+* stabilize EventMachine interface

data/Rakefile

@@ -1,13 +1,24 @@
 # -*- coding: utf-8 -*-
 # -*- ruby -*-
 
-require 'rubygems'
-require 'hoe'
+require 'bundler/gem_tasks'
 require 'pathname'
 require 'uri'
 require 'rake/extensiontask'
 require 'rake/extensioncompiler'
 
+task :gem => :build
+task :compile do
+  sh "ruby ext/extconf.rb"
+end
+task :test=>:compile do
+  sh "ruby -w -W2 -I. -Ilib -e \"#{Dir["test/test_*.rb"].map{|f| "require '#{f}';"}.join}\" -- -v"
+end
+travis_tests = %w[test_libusb_capability.rb test_libusb_structs.rb test_libusb_version.rb]
+task :travis=>:compile do
+  sh "ruby -w -W2 -I. -Ilib -e \"#{travis_tests.map{|f| "require 'test/#{f}';"}.join}\" -- -v"
+end
+task :default => :test
 
 # Cross-compilation constants
 COMPILE_HOME               = Pathname( "./tmp" ).expand_path
@@ -45,28 +56,10 @@ LIBUSB_TARBALL            = STATIC_SOURCESDIR + File.basename( LIBUSB_SOURCE_URI
 STATIC_LIBUSB_BUILDDIR    = STATIC_BUILDDIR + LIBUSB_TARBALL.basename(".tar.bz2")
 LIBUSB_CONFIGURE          = STATIC_LIBUSB_BUILDDIR + 'configure'
 LIBUSB_MAKEFILE           = STATIC_LIBUSB_BUILDDIR + 'Makefile'
-LIBUSB_DLL                  = STATIC_LIBUSB_BUILDDIR + 'libusb/.libs/libusb-1.0.dll'
-
-
-hoe = Hoe.spec 'libusb' do
-  developer('Lars Kanis', 'kanis@comcard.de')
-
-  extra_deps << ['ffi', '>= 1.0']
-  extra_dev_deps << ['rake-compiler', '>= 0.6']
-
-  self.url = 'http://github.com/larskanis/libusb'
-  self.summary = 'Access USB devices from Ruby via libusb-1.0'
-  self.description = 'LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices'
-
-  self.readme_file = 'README.rdoc'
-  spec_extras[:rdoc_options] = ['--main', readme_file, "--charset=UTF-8"]
-  spec_extras[:files] = `git ls-files`.split
-  self.extra_rdoc_files << self.readme_file
-
-  # clean intermediate files and folders
-  self.clean_globs << STATIC_BUILDDIR.to_s
-end
+LIBUSB_DLL                = STATIC_LIBUSB_BUILDDIR + 'libusb/.libs/libusb-1.0.dll'
 
+EXT_BUILDDIR              = Pathname( "./ext" ).expand_path
+EXT_LIBUSB_BUILDDIR       = EXT_BUILDDIR + LIBUSB_TARBALL.basename(".tar.bz2")
 
 #####################################################################
 ### C R O S S - C O M P I L A T I O N - T A S K S
@@ -135,10 +128,11 @@ task :libusb_dll => [ "copy:libusb_dll" ]
 
 desc 'Cross compile libusb for win32'
 task :cross => [ :mingw32, :libusb_dll ] do |t|
-  spec = hoe.spec.dup
+  spec = Gem::Specification::load("libusb.gemspec")
   spec.instance_variable_set(:"@cache_file", nil) if spec.respond_to?(:cache_file)
   spec.platform = Gem::Platform.new('i386-mingw32')
   spec.files << "lib/#{File.basename(LIBUSB_DLL)}"
+  spec.files -= `git ls-files ext/libusbx-*`.split("\n")
 
   # Generate a package for this gem
   Gem::PackageTask.new(spec) do |pkg|
@@ -156,4 +150,14 @@ task :mingw32 do
   end
 end
 
+desc "Download and update bundled libusb(x)"
+task :update_libusb => LIBUSB_TARBALL do
+  sh 'rm', '-r', (EXT_BUILDDIR + "libusbx-*").to_s do end
+  sh 'git', 'rm', '-rfq', (EXT_BUILDDIR + "libusbx-*").to_s do end
+  sh 'tar', '-xjf', LIBUSB_TARBALL.to_s, '-C', EXT_LIBUSB_BUILDDIR.parent.to_s
+  drops = %w[msvc].map{|f| (EXT_LIBUSB_BUILDDIR+f).to_s }
+  sh 'rm', '-r', '-f', *drops
+  sh 'git', 'add', EXT_LIBUSB_BUILDDIR.to_s
+end
+
 # vim: syntax=ruby

data/ext/extconf.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'ffi'
+
+begin
+  module LibTest
+    extend FFI::Library
+    ext = FFI::Platform.windows? ? 'dll' : 'so'
+    bundled_dll = File.expand_path("../../lib/libusb-1.0.#{ext}", __FILE__)
+    ffi_lib(['libusb-1.0', bundled_dll])
+  end
+rescue LoadError
+  # Unable to load libusb library on this system,
+  # so we build our bundled version:
+
+  libusb_dir = Dir[File.expand_path('../../ext/libusbx-*', __FILE__)].first
+  root_dir = File.expand_path('../..', __FILE__)
+  raise "could not find embedded libusb sources" unless libusb_dir
+
+  old_dir = Dir.pwd
+  Dir.chdir libusb_dir
+  cmd = "./configure --prefix=#{root_dir} && make && make install"
+  puts cmd
+  system cmd
+  raise "libusb build exited with #{$?.exitstatus}" if $?.exitstatus!=0
+  Dir.chdir old_dir
+end
+
+File.open("Makefile", "w") do |mf|
+  mf.puts "# Dummy makefile since libusb-1.0 is usable on this system"
+  mf.puts "all install::\n"
+end

data/lib/libusb.rb

@@ -14,12 +14,11 @@
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
 module LIBUSB
-  VERSION = "0.2.2"
-
   require 'libusb/call'
   require 'libusb/constants'
   require 'libusb/context'
-  autoload :Version, 'libusb/version'
+  autoload :VERSION, 'libusb/version_gem'
+  autoload :Version, 'libusb/version_struct'
   autoload :Configuration, 'libusb/configuration'
   autoload :DevHandle, 'libusb/dev_handle'
   autoload :Device, 'libusb/device'

data/lib/libusb/call.rb

@@ -17,16 +17,15 @@ require 'rubygems'
 require 'ffi'
 
 module LIBUSB
-  # C level interface
+  # C level interface - for internal use only
+  #
+  # All enum codes are available as constants in {LIBUSB} namespace.
   module Call
     extend FFI::Library
 
-    if FFI::Platform.windows?
-      bundled_dll = File.join(File.dirname(__FILE__), '..', 'libusb-1.0.dll')
-      ffi_lib(['libusb-1.0', bundled_dll])
-    else
-      ffi_lib 'libusb-1.0'
-    end
+    ext = FFI::Platform.windows? ? 'dll' : 'so'
+    bundled_dll = File.expand_path("../../libusb-1.0.#{ext}", __FILE__)
+    ffi_lib(['libusb-1.0', bundled_dll])
 
     ClassCodes = enum :libusb_class_code, [
       :CLASS_PER_INTERFACE, 0,
@@ -211,7 +210,16 @@ module LIBUSB
     attach_function 'libusb_free_transfer', [:pointer], :void
 
     attach_function 'libusb_handle_events', [:libusb_context], :int, :blocking=>true
+    try_attach_function 'libusb_handle_events_completed', [:libusb_context, :pointer], :int, :blocking=>true
+    attach_function 'libusb_handle_events_timeout', [:libusb_context, :pointer], :int, :blocking=>true
+    try_attach_function 'libusb_handle_events_timeout_completed', [:libusb_context, :pointer, :pointer], :int, :blocking=>true
+
+    callback :libusb_pollfd_added_cb, [:int, :short, :pointer], :void
+    callback :libusb_pollfd_removed_cb, [:int, :pointer], :void
 
+    attach_function 'libusb_get_pollfds', [:libusb_context], :pointer
+    attach_function 'libusb_get_next_timeout', [:libusb_context, :pointer], :int
+    attach_function 'libusb_set_pollfd_notifiers', [:libusb_context, :libusb_pollfd_added_cb, :libusb_pollfd_removed_cb, :pointer], :void
 
     callback :libusb_transfer_cb_fn, [:pointer], :void
 
@@ -267,5 +275,39 @@ module LIBUSB
           :iSerialNumber, :uint8,
           :bNumConfigurations, :uint8
     end
+
+    class Timeval < FFI::Struct
+      layout :tv_sec,  :long,
+        :tv_usec, :long
+
+      # set timeval to the number of milliseconds
+      # @param [Fixnum] value
+      def in_ms=(value)
+        self[:tv_sec], self[:tv_usec] = (value*1000).divmod(1000000)
+      end
+
+      # get the number of milliseconds in timeval
+      # @return [Fixnum]
+      def in_ms
+        self[:tv_sec]*1000 + self[:tv_usec]/1000
+      end
+
+      # set timeval to the number of seconds
+      # @param [Numeric] value
+      def in_s=(value)
+        self[:tv_sec], self[:tv_usec] = (value*1000000).divmod(1000000)
+      end
+
+      # get the number of seconds in timeval
+      # @return [Float]
+      def in_s
+        self[:tv_sec] + self[:tv_usec]/1000000.0
+      end
+    end
+
+    class Pollfd < FFI::Struct
+      layout :fd,  :int,
+          :events, :short
+    end
   end
 end