libusb 0.3.3-x64-mingw32

data/lib/libusb/transfer.rb

@@ -0,0 +1,282 @@
+# 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 'libusb/call'
+
+module LIBUSB
+  # Abstract base class for USB transfers. Use
+  # {ControlTransfer}, {BulkTransfer}, {InterruptTransfer}, {IsochronousTransfer}
+  # to do transfers.
+  #
+  # There are convenience methods for {DevHandle#bulk_transfer}, {DevHandle#control_transfer}
+  # and {DevHandle#interrupt_transfer}, that fit for most use cases.
+  # Using {Transfer} derived classes directly, however, is needed for isochronous transfers and
+  # allows a more advanced buffer management.
+  class Transfer
+    def initialize(args={})
+      args.each{|k,v| send("#{k}=", v) }
+      @buffer = nil
+      @completion_flag = Context::CompletionFlag.new
+    end
+    private :initialize
+
+    # Set the handle for the device to communicate with.
+    def dev_handle=(dev)
+      @dev_handle = dev
+      @transfer[:dev_handle] = @dev_handle.pHandle
+    end
+
+    # Timeout for this transfer in millseconds.
+    #
+    # A value of 0 indicates no timeout.
+    def timeout=(value)
+      @transfer[:timeout] = value
+    end
+
+    # Set the address of a valid endpoint to communicate with.
+    def endpoint=(endpoint)
+      endpoint = endpoint.bEndpointAddress if endpoint.respond_to? :bEndpointAddress
+      @transfer[:endpoint] = endpoint
+    end
+
+    # Set output data that should be sent.
+    def buffer=(data)
+      if !@buffer || data.bytesize>@buffer.size
+        free_buffer
+        @buffer = FFI::MemoryPointer.new(data.bytesize, 1, false)
+      end
+      @buffer.put_bytes(0, data)
+      @transfer[:buffer] = @buffer
+      @transfer[:length] = data.bytesize
+    end
+
+    # Retrieve the current data buffer.
+    def buffer
+      @transfer[:buffer].read_string(@transfer[:length])
+    end
+
+    # Clear the current data buffer.
+    def free_buffer
+      if @buffer
+        @buffer.free
+        @buffer = nil
+        @transfer[:buffer] = nil
+        @transfer[:length] = 0
+      end
+    end
+
+    # Allocate +len+ bytes of data buffer for input transfer.
+    #
+    # @param [Fixnum]  len  Number of bytes to allocate
+    # @param [String, nil] data  some data to initialize the buffer with
+    def alloc_buffer(len, data=nil)
+      if !@buffer || len>@buffer.size
+        free_buffer
+        @buffer = FFI::MemoryPointer.new(len, 1, false)
+      end
+      @buffer.put_bytes(0, data) if data
+      @transfer[:buffer] = @buffer
+      @transfer[:length] = len
+    end
+
+    # The number of bytes actually transferred.
+    def actual_length
+      @transfer[:actual_length]
+    end
+
+    # Retrieve the data actually transferred.
+    #
+    # @param [Fixnum] offset  optional offset of the retrieved data in the buffer.
+    def actual_buffer(offset=0)
+      @transfer[:buffer].get_bytes(offset, @transfer[:actual_length])
+    end
+
+    # Set the block that will be invoked when the transfer completes,
+    # fails, or is cancelled.
+    #
+    # @param [Proc] proc  The block that should be called
+    def callback=(proc)
+      # Save proc to instance variable so that GC doesn't free
+      # the proc object before the transfer.
+      @callback_proc = proc do |pTrans|
+        proc.call(self)
+      end
+      @transfer[:callback] = @callback_proc
+    end
+
+    # The status of the transfer.
+    #
+    # Only for use within transfer callback function or after the callback was called.
+    #
+    # If this is an isochronous transfer, this field may read :TRANSFER_COMPLETED even if there
+    # were errors in the frames. Use the status field in each packet to determine if
+    # errors occurred.
+    def status
+      @transfer[:status]
+    end
+
+    # Submit a transfer.
+    #
+    # This function will fire off the USB transfer and then return immediately.
+    # This method can be called with block. It is called when the transfer completes,
+    # fails, or is cancelled.
+    def submit!(&block)
+      self.callback = block if block_given?
+
+#       puts "submit transfer #{@transfer.inspect} buffer: #{@transfer[:buffer].inspect} length: #{@transfer[:length].inspect} status: #{@transfer[:status].inspect} callback: #{@transfer[:callback].inspect} dev_handle: #{@transfer[:dev_handle].inspect}"
+
+      res = Call.libusb_submit_transfer( @transfer )
+      LIBUSB.raise_error res, "in libusb_submit_transfer" if res!=0
+    end
+
+    # Asynchronously cancel a previously submitted transfer.
+    #
+    # This function returns immediately, but this does not indicate cancellation is
+    # complete. Your callback function will be invoked at some later time with a
+    # transfer status of :TRANSFER_CANCELLED.
+    def cancel!
+      res = Call.libusb_cancel_transfer( @transfer )
+      LIBUSB.raise_error res, "in libusb_cancel_transfer" if res!=0
+    end
+
+    TransferStatusToError = {
+      :TRANSFER_ERROR => LIBUSB::ERROR_IO,
+      :TRANSFER_TIMED_OUT => LIBUSB::ERROR_TIMEOUT,
+      :TRANSFER_CANCELLED => LIBUSB::ERROR_INTERRUPTED,
+      :TRANSFER_STALL => LIBUSB::ERROR_PIPE,
+      :TRANSFER_NO_DEVICE => LIBUSB::ERROR_NO_DEVICE,
+      :TRANSFER_OVERFLOW => LIBUSB::ERROR_OVERFLOW,
+    }
+
+    # Submit the transfer and wait until the transfer completes or fails.
+    #
+    # Inspect {#status} to check for transfer errors.
+    def submit_and_wait
+      @completion_flag.completed = false
+      submit! do |tr2|
+        @completion_flag.completed = true
+      end
+
+      until @completion_flag.completed?
+        begin
+          @dev_handle.device.context.handle_events nil, @completion_flag
+        rescue ERROR_INTERRUPTED
+          next
+        rescue LIBUSB::Error
+          cancel!
+          until @completion_flag.completed?
+            @dev_handle.device.context.handle_events nil, @completion_flag
+          end
+          raise
+        end
+      end
+    end
+
+    # Submit the transfer and wait until the transfer completes or fails.
+    #
+    # A proper {LIBUSB::Error} is raised, in case the transfer did not complete.
+    def submit_and_wait!
+      submit_and_wait
+
+      raise( TransferStatusToError[status] || ERROR_OTHER, "error #{status}") unless status==:TRANSFER_COMPLETED
+    end
+  end
+
+  class BulkTransfer < Transfer
+    def initialize(args={})
+      @transfer = Call::Transfer.new Call.libusb_alloc_transfer(0)
+      @transfer[:type] = TRANSFER_TYPE_BULK
+      @transfer[:timeout] = 1000
+      super
+    end
+  end
+
+  class ControlTransfer < Transfer
+    def initialize(args={})
+      @transfer = Call::Transfer.new Call.libusb_alloc_transfer(0)
+      @transfer[:type] = TRANSFER_TYPE_CONTROL
+      @transfer[:timeout] = 1000
+      super
+    end
+  end
+
+  class InterruptTransfer < Transfer
+    def initialize(args={})
+      @transfer = Call::Transfer.new Call.libusb_alloc_transfer(0)
+      @transfer[:type] = TRANSFER_TYPE_INTERRUPT
+      @transfer[:timeout] = 1000
+      super
+    end
+  end
+
+  class IsoPacket
+    def initialize(ptr, pkg_nr)
+      @packet = Call::IsoPacketDescriptor.new ptr
+      @pkg_nr = pkg_nr
+    end
+
+    def status
+      @packet[:status]
+    end
+
+    def length
+      @packet[:length]
+    end
+    def length=(len)
+      @packet[:length] = len
+    end
+
+    def actual_length
+      @packet[:actual_length]
+    end
+  end
+
+  class IsochronousTransfer < Transfer
+    def initialize(num_packets, args={})
+      @ptr = Call.libusb_alloc_transfer(num_packets)
+      @transfer = Call::Transfer.new @ptr
+      @transfer[:type] = TRANSFER_TYPE_ISOCHRONOUS
+      @transfer[:timeout] = 1000
+      @transfer[:num_iso_packets] = num_packets
+      super(args)
+    end
+
+    def num_packets
+      @transfer[:num_iso_packets]
+    end
+    def num_packets=(number)
+      @transfer[:num_iso_packets] = number
+    end
+
+    def [](nr)
+      IsoPacket.new( @ptr + Call::Transfer.size + nr*Call::IsoPacketDescriptor.size, nr)
+    end
+
+    # Convenience function to set the length of all packets in an
+    # isochronous transfer, based on {IsochronousTransfer#num_packets}.
+    def packet_lengths=(len)
+      ptr = @ptr + Call::Transfer.size
+      num_packets.times do
+        ptr.write_uint(len)
+        ptr += Call::IsoPacketDescriptor.size
+      end
+    end
+
+    # The actual_length field of the transfer is meaningless and should not
+    # be examined; instead you must refer to the actual_length field of
+    # each individual packet.
+    private :actual_length, :actual_buffer
+  end
+end

data/lib/libusb/version_gem.rb

@@ -0,0 +1,19 @@
+# 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/>.
+
+module LIBUSB
+  # Library version of libusb for Ruby
+  VERSION = "0.3.3"
+end

data/lib/libusb/version_struct.rb

@@ -0,0 +1,63 @@
+# 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 'libusb/call'
+
+module LIBUSB
+  class Version < FFI::Struct
+    layout :major, :uint16,
+        :minor, :uint16,
+        :micro, :uint16,
+        :nano, :uint16,
+        :rc, :pointer,
+        :describe, :pointer
+
+    # Library major version.
+    def major
+      self[:major]
+    end
+    # Library minor version.
+    def minor
+      self[:minor]
+    end
+    # Library micro version.
+    def micro
+      self[:micro]
+    end
+    # Library nano version.
+    def nano
+      self[:nano]
+    end
+
+    # Library release candidate suffix string, e.g. "-rc4".
+    def rc
+      self[:rc].read_string
+    end
+
+    # For ABI compatibility only.
+    def describe
+      self[:describe].read_string
+    end
+
+    # Version string, e.g. "1.2.3-rc4"
+    def to_s
+      "#{major}.#{minor}.#{micro}#{rc}"
+    end
+
+    def inspect
+      "\#<#{self.class} #{to_s}>"
+    end
+  end
+end

data/libusb.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "libusb/version_gem"
+
+Gem::Specification.new do |s|
+  s.name        = "libusb"
+  s.version     = LIBUSB::VERSION
+  s.authors     = ["Lars Kanis"]
+  s.email       = ["lars@greiz-reinsdorf.de"]
+  s.homepage    = "http://github.com/larskanis/libusb"
+  s.summary     = %q{Access USB devices from Ruby via libusb-1.0}
+  s.description = %q{LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices}
+  s.rdoc_options = %w[--main README.md --charset=UTF-8]
+
+  s.rubyforge_project = "libusb"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.extensions    = ['ext/extconf.rb']
+
+  # travis currently runs a slightly older version of rbx,
+  # that needs a special ffi version.
+  unless ENV['TRAVIS'] && defined?(RUBY_ENGINE) && RUBY_ENGINE=='rbx'
+    s.add_runtime_dependency 'ffi', '>= 1.0'
+  end
+
+  s.add_development_dependency 'rake-compiler', '>= 0.6'
+  s.add_development_dependency 'bundler'
+end

data/test/test_libusb_capability.rb

@@ -0,0 +1,23 @@
+# 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 TestLibusbCapability < Test::Unit::TestCase
+  def test_version_parts
+    assert LIBUSB.has_capability?(:CAP_HAS_CAPABILITY)
+  end
+end

data/test/test_libusb_compat.rb

@@ -0,0 +1,78 @@
+# 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/compat"
+
+class TestLibusbCompat < Test::Unit::TestCase
+  include USB
+
+  attr_accessor :usb
+
+  def test_find
+    devlist = USB.devices
+    assert_kind_of Array, devlist, "Bus#find should return an Array"
+    assert_kind_of Device, devlist.first, "Bus#find should return Devices"
+    devlist.each do |dev|
+      assert_match( /Device/, dev.inspect, "Device#inspect should work")
+    end
+  end
+
+  def test_constants
+    assert_equal 7, USB_CLASS_PRINTER, "Printer class id should be defined"
+    assert_equal 32, USB_TYPE_CLASS, "type class should be defined"
+  end
+
+  def test_descriptors
+    USB.devices.each do |dev|
+      assert_match(/Device/, dev.inspect, "Device#inspect should work")
+      dev.configurations.each do |config_desc|
+        assert_match(/Configuration/, config_desc.inspect, "Configuration#inspect should work")
+        assert dev.configurations.include?(config_desc), "Device#configurations should include this one"
+
+        config_desc.interfaces.each do |interface|
+          assert_match(/Interface/, interface.inspect, "Interface#inspect should work")
+
+          assert dev.interfaces.include?(interface), "Device#interfaces should include this one"
+          assert config_desc.interfaces.include?(interface), "Configuration#interfaces should include this one"
+
+          interface.settings.each do |if_desc|
+            assert_match(/Setting/, if_desc.inspect, "Setting#inspect should work")
+
+            assert dev.settings.include?(if_desc), "Device#settings should include this one"
+            assert config_desc.settings.include?(if_desc), "Configuration#settings should include this one"
+            assert interface.settings.include?(if_desc), "Interface#settings should include this one"
+
+            if_desc.endpoints.each do |ep|
+              assert_match(/Endpoint/, ep.inspect, "Endpoint#inspect should work")
+
+              assert dev.endpoints.include?(ep), "Device#endpoints should include this one"
+              assert config_desc.endpoints.include?(ep), "Configuration#endpoints should include this one"
+              assert interface.endpoints.include?(ep), "Interface#endpoints should include this one"
+              assert if_desc.endpoints.include?(ep), "Setting#endpoints should include this one"
+
+              assert_equal if_desc, ep.setting, "backref should be correct"
+              assert_equal interface, ep.interface, "backref should be correct"
+              assert_equal config_desc, ep.configuration, "backref should be correct"
+              assert_equal dev, ep.device, "backref should be correct"
+
+              assert_operator 0, :<=, ep.wMaxPacketSize, "packet size should be > 0"
+            end
+          end
+        end
+      end
+    end
+  end
+end