libusb 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d72428d38fc654c53b2a8d3bb182ae790f2860154eb1d350f7ca57292bc0ff6
-  data.tar.gz: 737cc6576964289bc028380e39d5404fd91fec0fb85f2ab919df9c8c6449a297
+  metadata.gz: 81987d2e99821ceff5acf54c463c28b83fcb586aa401d3c90d23af4777bde459
+  data.tar.gz: 9921b3deb351982884c2848313721d786fe1e4bcf5e4db2dcff37cda297ec05a
 SHA512:
-  metadata.gz: ae37e6a1cb842de3b0e1eacd17896a35276c7f68c4f55d9f9b00ae21d832aaacc6a671171f2b5c85ee64449147b668239e8c6fb44203a4a394c4dade30b16928
-  data.tar.gz: 7270194dac34b088447b998e76b805e7c33b17a03dd67209c80c4f9d7cbd52fd6610f1092e61027454179f1626f8f17649fdc414c6d80b68f09452235ae3f6eb
+  metadata.gz: 39ab11140cb2d68b5540337fb7d5c27743956cd479576002f194ac5f2b89d67711819fee84932f76090cb877cb11034294721f56031b4578fb717a722ebf0184
+  data.tar.gz: c11df155a20a7cfbeeae72bb313c79ea47b1d5fb3a6c94869e294ba261f7a995901553aafc943719ffd13db31e5d592c32c6a08ce53b887d3382788de9a83434

data/Gemfile

@@ -10,8 +10,9 @@ end
 
 gem 'rake-compiler-dock', '~> 1.1'
 gem 'rake-compiler', '~> 1.0'
-gem 'bundler', '>= 1', '< 3'
+gem 'bundler', '>= 1', '< 5.a'
 gem 'yard', '~> 0.6', '>= 0.9.36'
+gem 'ostruct', '~> 0.1'
 
 # For some reason this is required in addition to the gemspec
 # when 'bundle config force_ruby_platform true' is active:

data/History.md

@@ -1,3 +1,19 @@
+0.8.0 / 2026-08-02
+------------------
+
+Added:
+* Add LIBUSB::SsplusUsbDeviceCapability introduced in libusb-1.0.28. #53
+* Add LIBUSB::Device#device_string and prefer it in Device#inspect. #54
+  This retrievs product string, manufacturer and serial number from the OS without opening the device.
+* Enable hotplug support on Windows introduced in libusb-1.0.30.
+* Add LIBUSB::Device#get_session_data introduced in libusb-1.0.30. #54
+
+Changed:
+* Don't kill the EventMachine reactor on LIBUSB_ERROR_INTERRUPTED. #52
+* Improve yard docs.
+* Update builtin libusb to 1.0.30
+
+
 0.7.2 / 2024-10-23
 ------------------
 
@@ -150,7 +166,7 @@ Deprecated:
 * 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 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

data/Rakefile

@@ -5,7 +5,6 @@ require 'bundler/gem_helper'
 require 'rubygems/package_task'
 require 'pathname'
 require 'uri'
-require 'ostruct'
 require 'rake/clean'
 require_relative 'lib/libusb/libusb_recipe'
 require_relative 'lib/libusb/gem_helper'
@@ -39,7 +38,7 @@ task :gemfile_libusb_gem do
 end
 
 task :test do
-  sh "ruby -w -W2 -I.:lib -e \"#{Dir["test/test_*.rb"].map{|f| "require '#{f}';"}.join}\" -- -v"
+  sh "ruby -w -W2 -I. -Ilib -e \"#{Dir["test/test_*.rb"].map{|f| "require '#{f}';"}.join}\" -- -v"
 end
 task :default => :test
 

data/ext/extconf.rb

@@ -70,6 +70,7 @@ def build_bundled_libusb(have_udev)
 
   require_relative '../lib/libusb/libusb_recipe'
   recipe = LIBUSB::LibusbRecipe.new
+  recipe.configure_options << "--enable-windows-hotplug"
   recipe.configure_options << "--disable-udev" unless have_udev
   recipe.cook_and_activate
   recipe.path

data/lib/libusb/bos.rb

@@ -169,10 +169,11 @@ module LIBUSB
       # device supports all its functionality when connected at
       # full speed and above then it sets this value to 1.
       #
-      # 0 - low speed
-      # 1 - full speed
-      # 2 - high speed
-      # 3 - super speed
+      # * 0 - low speed
+      # * 1 - full speed
+      # * 2 - high speed
+      # * 3 - super speed
+      #
       # @return [Integer]
       def bFunctionalitySupport
         self[:bFunctionalitySupport]
@@ -189,6 +190,137 @@ module LIBUSB
       end
     end
 
+    # A structure representing a SuperSpeedPlus descriptor attribute
+    #
+    # @see SsplusUsbDeviceCapability
+    class SsplusSublinkAttribute < FFI::Struct
+
+      layout :ssid, :uint8,
+          :exponent, Call::SuperspeedplusSublinkAttributeExponent,
+          :type, Call::SuperspeedplusSublinkAttributeSublinkType,
+          :direction, Call::SuperspeedplusSublinkAttributeSublinkDirection,
+          :protocol, Call::SuperspeedplusSublinkAttributeLinkProtocol,
+          :mantissa, :uint16
+
+      # Sublink Speed Attribute ID (SSID).
+      #
+      # This field is an ID that uniquely identifies the speed of this sublink.
+      def ssid
+        self[:ssid]
+      end
+
+      # This field defines the base 10 exponent times 3, that shall be applied to the mantissa.
+      # @see Call::SuperspeedplusSublinkAttributeExponent
+      def exponent
+        self[:exponent]
+      end
+
+      # This field identifies whether the Sublink Speed Attribute defines a symmetric or asymmetric bit rate.
+      # @see Call::SuperspeedplusSublinkAttributeSublinkType
+      def type
+        self[:type]
+      end
+
+      # This field  indicates if this Sublink Speed Attribute defines the receive or transmit bit rate.
+      # @see Call::SuperspeedplusSublinkAttributeSublinkDirection
+      def direction
+        self[:direction]
+      end
+
+      # This field identifies the protocol supported by the link.
+      # @see Call::SuperspeedplusSublinkAttributeLinkProtocol
+      def protocol
+        self[:protocol]
+      end
+
+      # This field defines the mantissa that shall be applied to the exponent when calculating the maximum bit rate.
+      def mantissa
+        self[:mantissa]
+      end
+
+      def to_s_human_readable
+        exponents = {
+          SSPLUS_ATTR_EXP_BPS: " ",
+          SSPLUS_ATTR_EXP_KBS: "K",
+          SSPLUS_ATTR_EXP_MBS: "M",
+          SSPLUS_ATTR_EXP_GBS: "G",
+          }
+        format("id=%u speed=%u%sbs %s %s SuperSpeed%s",
+                      ssid,
+                      mantissa,
+                      exponents[exponent],
+                      type == :SSPLUS_ATTR_TYPE_ASYM ? "Asym" : "Sym",
+                      direction == :SSPLUS_ATTR_DIR_TX ? "TX" : "RX",
+                      protocol == :SSPLUS_ATTR_PROT_SSPLUS ? "+": "" )
+      end
+
+      def inspect
+        "\#<#{self.class} #{to_s_human_readable}>"
+      end
+    end
+
+    # A structure representing the SuperSpeedPlus descriptor
+    # This descriptor is documented in section 9.6.2.5 of the USB 3.1 specification.
+    class SsplusUsbDeviceCapability < FFI::Struct
+      include ContextReference
+
+      layout :numSublinkSpeedAttributes, :uint8,
+          :numSublinkSpeedIDs, :uint8,
+          :ssid, :uint8,
+          :minRxLaneCount, :uint8,
+          :minTxLaneCount, :uint8,
+          :sublinkSpeedAttributes, [SsplusSublinkAttribute, 0]
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_ssplus_usb_device_capability_descriptor)
+      end
+
+      def inspect
+        attrs = %i[ numSublinkSpeedAttributes numSublinkSpeedIDs ssid minRxLaneCount minTxLaneCount ].map do |key|
+          "#{key}: #{self.send(key).inspect}"
+        end
+        "\#<#{self.class} #{attrs.join(", ")}>"
+      end
+
+      # Sublink Speed Attribute Count
+      def numSublinkSpeedAttributes
+        self[:numSublinkSpeedAttributes]
+      end
+
+      # Sublink Speed ID Count
+      def numSublinkSpeedIDs
+        self[:numSublinkSpeedIDs]
+      end
+
+      # Unique ID to indicates the minimum lane speed
+      def ssid
+        self[:ssid]
+      end
+
+      # This field indicates the minimum receive lane count.
+      def minRxLaneCount
+        self[:minRxLaneCount]
+      end
+
+      # This field indicates the minimum transmit lane count
+      def minTxLaneCount
+        self[:minTxLaneCount]
+      end
+
+      # Returns an Array of SublinkSpeedAttributes
+      #
+      # The array size equals {numSublinkSpeedAttributes}.
+      #
+      # @return [Array<SsplusSublinkAttribute>]
+      def sublinkSpeedAttributes
+        self[:numSublinkSpeedAttributes].times.map do |idx|
+          self[:sublinkSpeedAttributes][idx]
+        end
+      end
+    end
+
     # A structure representing the Container ID descriptor.
     # This descriptor is documented in section 9.6.2.3 of the USB 3.0 specification.
     # All multiple-byte fields, except UUIDs, are represented in host-endian format.
@@ -308,33 +440,40 @@ module LIBUSB
       self[:bNumDeviceCaps]
     end
 
+    private def wrap_device_capability(cap, func, struct)
+      if Call.respond_to?(func)
+        pp_ext = FFI::MemoryPointer.new :pointer
+        res = Call.send(func, @ctx, cap.pointer, pp_ext)
+        struct.new(@ctx, pp_ext.read_pointer) if res==0
+      end || cap
+    end
+
     # bNumDeviceCap Device Capability Descriptors
     #
     # @return [Array<Bos::DeviceCapability, Bos::Usb20Extension, Bos::SsUsbDeviceCapability, Bos::ContainerId>]
     def device_capabilities
-      pp_ext = FFI::MemoryPointer.new :pointer
       caps = []
       # Capabilities are appended to the bos header
       ptr = pointer + offset_of(:dev_capability)
       bNumDeviceCaps.times do
         cap = DeviceCapability.new self, ptr.read_pointer
-        case cap.bDevCapabilityType
+        cap = case cap.bDevCapabilityType
           when LIBUSB::BT_WIRELESS_USB_DEVICE_CAPABILITY
             # no struct defined in libusb -> use generic DeviceCapability
+            cap
           when LIBUSB::BT_USB_2_0_EXTENSION
-            res = Call.libusb_get_usb_2_0_extension_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = Usb20Extension.new(@ctx, pp_ext.read_pointer) if res==0
+            wrap_device_capability(cap, :libusb_get_usb_2_0_extension_descriptor, Usb20Extension)
           when LIBUSB::BT_SS_USB_DEVICE_CAPABILITY
-            res = Call.libusb_get_ss_usb_device_capability_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = SsUsbDeviceCapability.new(@ctx, pp_ext.read_pointer) if res==0
+            wrap_device_capability(cap, :libusb_get_ss_usb_device_capability_descriptor, SsUsbDeviceCapability)
+          when LIBUSB::BT_SUPERSPEED_PLUS_CAPABILITY
+            wrap_device_capability(cap, :libusb_get_ssplus_usb_device_capability_descriptor, SsplusUsbDeviceCapability)
           when LIBUSB::BT_CONTAINER_ID
-            res = Call.libusb_get_container_id_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = ContainerId.new(@ctx, pp_ext.read_pointer) if res==0
+            wrap_device_capability(cap, :libusb_get_container_id_descriptor, ContainerId)
           when LIBUSB::BT_PLATFORM_DESCRIPTOR
-            res = Call.libusb_get_platform_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = PlatformDescriptor.new(@ctx, pp_ext.read_pointer) if res==0
+            wrap_device_capability(cap, :libusb_get_platform_descriptor, PlatformDescriptor)
           else
             # unknown capability -> use generic DeviceCapability
+            cap
         end
         ptr += FFI.type_size(:pointer)
         caps << cap

data/lib/libusb/call.rb

@@ -224,6 +224,39 @@ module LIBUSB
       :BM_LTM_SUPPORT, 2,
     ]
 
+
+    # enum used in SsplusSublinkAttribute
+    SuperspeedplusSublinkAttributeSublinkType = enum :libusb_superspeedplus_sublink_attribute_sublink_type, [
+      :SSPLUS_ATTR_TYPE_SYM, 0,
+      :SSPLUS_ATTR_TYPE_ASYM, 1,
+    ]
+
+    # enum used in SsplusSublinkAttribute
+    SuperspeedplusSublinkAttributeSublinkDirection = enum :libusb_superspeedplus_sublink_attribute_sublink_direction, [
+      :SSPLUS_ATTR_DIR_RX, 0,
+      :SSPLUS_ATTR_DIR_TX, 1,
+    ]
+
+    # enum used in SsplusSublinkAttribute
+    #
+    # This field defines the base 10 exponent times 3, that shall be applied to the mantissa.
+    # * Bit   = Bits per second
+    # * Kb = Kbps
+    # * Mb = Mbps
+    # * Gb = Gbps
+    SuperspeedplusSublinkAttributeExponent = enum :libusb_superspeedplus_sublink_attribute_exponent, [
+      :SSPLUS_ATTR_EXP_BPS, 0,
+      :SSPLUS_ATTR_EXP_KBS, 1,
+      :SSPLUS_ATTR_EXP_MBS, 2,
+      :SSPLUS_ATTR_EXP_GBS, 3,
+    ]
+
+    # enum used in SsplusSublinkAttribute
+    SuperspeedplusSublinkAttributeLinkProtocol = enum :libusb_superspeedplus_sublink_attribute_link_protocol, [
+      :SSPLUS_ATTR_PROT_SS, 0,
+      :SSPLUS_ATTR_PROT_SSPLUS, 1,
+    ]
+
     # USB capability types
     #
     # @see Bos::DeviceCapability
@@ -237,7 +270,7 @@ module LIBUSB
       :BT_BATTERY_INFO_CAPABILITY, 0x07, # Provides information on each battery supported by the device
       :BT_PD_CONSUMER_PORT_CAPABILITY, 0x08, # The consumer characteristics of a port on the device
       :BT_PD_PROVIDER_PORT_CAPABILITY, 0x09, # The provider characteristics of a port on the device
-      :BT_SUPERSPEED_PLUS, 0x0A, # Defines the set of SuperSpeed Plus USB specific device level capabilities
+      :BT_SUPERSPEED_PLUS_CAPABILITY, 0x0A, # Defines the set of SuperSpeed Plus USB specific device level capabilities
       :BT_PRECISION_TIME_MEASUREMENT, 0x0B, # Precision Time Measurement (PTM) Capability Descriptor
       :BT_Wireless_USB_Ext, 0x0C, # Defines the set of Wireless USB 1.1-specific device level capabilities
       :BT_BILLBOARD, 0x0D, # Billboard capability
@@ -268,6 +301,14 @@ module LIBUSB
       :HOTPLUG_ENUMERATE, 1,
     ]
 
+    # The device string type.
+    DeviceStringType = enum :libusb_device_string_type, [
+      :DEVICE_STRING_MANUFACTURER,
+      :DEVICE_STRING_PRODUCT,
+      :DEVICE_STRING_SERIAL_NUMBER,
+      :DEVICE_STRING_COUNT  # The total number of string types.
+    ]
+
     # Log message levels.
     #
     # - :LOG_LEVEL_NONE (0)    : no messages ever printed by the library (default)
@@ -459,6 +500,8 @@ module LIBUSB
     try_attach_function 'libusb_free_usb_2_0_extension_descriptor', [:pointer], :void
     try_attach_function 'libusb_get_ss_usb_device_capability_descriptor', [:libusb_context, :pointer, :pointer], :int
     try_attach_function 'libusb_free_ss_usb_device_capability_descriptor', [:pointer], :void
+    try_attach_function 'libusb_get_ssplus_usb_device_capability_descriptor', [:libusb_context, :pointer, :pointer], :int
+    try_attach_function 'libusb_free_ssplus_usb_device_capability_descriptor', [:pointer], :void
     try_attach_function 'libusb_get_container_id_descriptor', [:libusb_context, :pointer, :pointer], :int
     try_attach_function 'libusb_free_container_id_descriptor', [:pointer], :void
     try_attach_function 'libusb_get_platform_descriptor', [:libusb_context, :pointer, :pointer], :int
@@ -521,6 +564,46 @@ module LIBUSB
         :pointer, :pointer], :int
     try_attach_function 'libusb_hotplug_deregister_callback', [:libusb_context, :libusb_hotplug_callback_handle], :void
 
+    # Retrieve a device string without needing to open the device.
+    #
+    # Since version v1.0.30 \ref LIBUSB_API_VERSION >= 0x0100010C
+    #
+    # \param dev the target device
+    # \param string_type the string type to retrieve
+    # \param data the data buffer for the UTF-8 encoded string.
+    # \param length the size of the data buffer in bytes.
+    #      USB string descriptors cannot be longer than
+    #      LIBUSB_DEVICE_STRING_BYTES_MAX.
+    # \returns a negative error code or
+    #      the actual string length in bytes including the null terminator.
+    # \see libusb_get_string_descriptor()
+    # \see libusb_get_string_descriptor_ascii()
+    #
+    # This function works when the device is still closed since it relies
+    # on the operating system to provide the string.  The operating system
+    # normally reads and caches the common string descriptors during
+    # USB enumeration.
+    #
+    # Since the USB string descriptor could be processed by the OS,
+    # this function returns a UTF-8 encoded string.
+    #
+    # The string will be returned untranslated or in the default OS language
+    # when supported by the OS and USB device.
+    #
+    # One way to call this function is using a buffer on the stack:
+    #
+    #     char buffer[LIBUSB_DEVICE_STRING_BYTES_MAX];
+    #     int ret = libusb_get_device_string(dev, LIBUSB_DEVICE_STRING_SERIAL_NUMBER, buffer, sizeof(buffer));
+    #     if (ret < 0) {
+    #         // handle error
+    #     }
+    #
+    # This function is commonly used to get the serial number to allow
+    # for device selection before opening the selected device.
+    try_attach_function 'libusb_get_device_string', [:libusb_device, DeviceStringType, :pointer, :int], :int
+
+    try_attach_function 'libusb_get_session_data', [:libusb_device], :ulong
+
     class IsoPacketDescriptor < FFI::Struct
       layout :length, :uint,
           :actual_length, :uint,
@@ -554,6 +637,8 @@ module LIBUSB
         super
 
         ptr = pointer
+        # @private
+        # called by GC
         def ptr.free_struct(id)
           Call.libusb_free_transfer(self)
           return unless @ctx

data/lib/libusb/constants.rb

@@ -36,6 +36,7 @@ module LIBUSB
     Call::LogLevels,
     Call::LogCbMode,
     Call::Options,
+    Call::DeviceStringType,
   ].each do |enum|
     enum.to_h.each{|k,v| const_set(k,v) }
   end
@@ -92,6 +93,16 @@ module LIBUSB
   # Wildcard matching for hotplug events.
   HOTPLUG_MATCH_ANY = -1
 
+  # The maximum length for a device string descriptor in UTF-8.
+  #
+  # 255 max descriptor length with 2 byte header
+  #  => 253 bytes UTF-16LE, no null termination (USB 2.0 9.6.7)
+  #  => 126.5 codepoints
+  #  => 126 * 3 + 1
+  #  => 382 bytes
+  #
+  # Stay with 256 * 2/3 = 384 to be safe.
+  DEVICE_STRING_BYTES_MAX = 384
 
   # http://www.usb.org/developers/defined_class
   # @private

data/lib/libusb/context.rb

@@ -523,14 +523,13 @@ module LIBUSB
     #
     # Since libusb version 1.0.16.
     #
-    # @param [Hash] args
-    # @option args [Fixnum,Symbol] :events  bitwise or of events that will trigger this callback.
+    # @param [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}.
+    # @param [Fixnum,Symbol] flags hotplug callback flags. Default is 0. See {Call::HotplugFlags HotplugFlags}
+    # @param [Fixnum] vendor_id the vendor id to match. Default is {HOTPLUG_MATCH_ANY}.
+    # @param [Fixnum] product_id the product id to match. Default is {HOTPLUG_MATCH_ANY}.
+    # @param [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

data/lib/libusb/context_reference.rb

@@ -17,16 +17,21 @@ module LIBUSB
   module ContextReference
     def register_context(ctx, free_sym)
       ptr = pointer
+
+      # @private
+      # called by GC or #free
       def ptr.free_struct(id)
         return unless @ctx
         Call.send(@free_sym, self)
         @ctx.unref_context
       end
+
       ptr.instance_variable_set(:@free_sym, free_sym)
       ptr.instance_variable_set(:@ctx, ctx.ref_context)
       ObjectSpace.define_finalizer(self, ptr.method(:free_struct))
     end
 
+    # Free the struct manually
     def free
       ptr = pointer
       ptr.free_struct nil

data/lib/libusb/dependencies.rb

@@ -1,7 +1,7 @@
 module LIBUSB
-  LIBUSB_VERSION = ENV['LIBUSB_VERSION'] || '1.0.27'
+  LIBUSB_VERSION = ENV['LIBUSB_VERSION'] || '1.0.30'
   LIBUSB_SOURCE_URI = "https://github.com/libusb/libusb/releases/download/v#{LIBUSB_VERSION}/libusb-#{LIBUSB_VERSION}.tar.bz2"
-  LIBUSB_SOURCE_SHA256 = 'ffaa41d741a8a3bee244ac8e54a72ea05bf2879663c098c82fc5757853441575'
+  LIBUSB_SOURCE_SHA256 = 'fea36f34f9156400209595e300840767ab1a385ede1dc7ee893015aea9c6dbaf'
 
   MINI_PORTILE_VERSION = '~> 2.1'
 end

data/lib/libusb/dev_handle.rb

@@ -194,7 +194,7 @@ module LIBUSB
 
     if Call.respond_to?(:libusb_alloc_streams)
 
-      # @method alloc_streams
+      # @method alloc_streams(num_streams, endpoints)
       #
       # Allocate up to num_streams usb bulk streams on the specified endpoints. This
       # function takes an array of endpoints rather then a single endpoint because
@@ -222,7 +222,7 @@ module LIBUSB
         res
       end
 
-      # @method free_streams
+      # @method free_streams(endpoints)
       #
       # Free usb bulk streams allocated with {alloc_streams}
       #
@@ -286,7 +286,7 @@ module LIBUSB
     # @private
     if Call.respond_to?(:libusb_set_auto_detach_kernel_driver)
 
-      # @method auto_detach_kernel_driver=
+      # @method auto_detach_kernel_driver=(enable)
       # Enable/disable libusb's automatic kernel driver detachment.
       #
       # When this is enabled libusb will automatically detach the kernel driver on an
@@ -358,11 +358,10 @@ module LIBUSB
     # transferred; do not assume that timeout conditions indicate a complete lack of
     # I/O.
     #
-    # @param [Hash] args
-    # @option args [Endpoint, Fixnum] :endpoint  the (address of a) valid endpoint to communicate with
-    # @option args [String] :dataOut  the data to send with an outgoing transfer
-    # @option args [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
-    # @option args [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
+    # @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
@@ -429,11 +428,10 @@ module LIBUSB
     #
     # The default endpoint bInterval value is used as the polling interval.
     #
-    # @param [Hash] args
-    # @option args [Endpoint, Fixnum] :endpoint  the (address of a) valid endpoint to communicate with
-    # @option args [String] :dataOut  the data to send with an outgoing transfer
-    # @option args [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
-    # @option args [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
+    # @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
@@ -483,16 +481,15 @@ module LIBUSB
     # The direction of the transfer is inferred from the +:bmRequestType+ field of the
     # setup packet.
     #
-    # @param [Hash] args
-    # @option args [Fixnum] :bmRequestType   the request type field for the setup packet
-    # @option args [Fixnum] :bRequest  the request field for the setup packet
-    # @option args [Fixnum] :wValue  the value field for the setup packet
-    # @option args [Fixnum] :wIndex  the index field for the setup packet
-    # @option args [String] :dataOut  the data to send with an outgoing transfer, it
+    # @param [Fixnum] bmRequestType   the request type field for the setup packet
+    # @param [Fixnum] bRequest  the request field for the setup packet
+    # @param [Fixnum] wValue  the value field for the setup packet
+    # @param [Fixnum] wIndex  the index field for the setup packet
+    # @param [String] dataOut  the data to send with an outgoing transfer, it
     #   is appended to the setup packet
-    # @option args [Fixnum] :dataIn   the number of bytes expected to receive with an ingoing transfer
+    # @param [Fixnum] dataIn   the number of bytes expected to receive with an ingoing transfer
     #   (excluding setup packet)
-    # @option args [Fixnum] :timeout   timeout (in millseconds) that this function should wait before giving
+    # @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 (excluding setup packet) for outgoing transfer

data/lib/libusb/device.rb

@@ -319,6 +319,51 @@ module LIBUSB
       @pDevDesc[:bNumConfigurations]
     end
 
+    if Call.respond_to?(:libusb_get_device_string)
+      # Retrieve the device description strings without opening the device.
+      # So permissions for open aren't necessary.
+      #
+      # This function works when the device is still closed since it relies
+      # on the operating system to provide the string.  The operating system
+      # normally reads and caches the common string descriptors during
+      # USB enumeration.
+      #
+      # Since the USB string descriptor could be processed by the OS,
+      # this function returns a UTF-8 encoded string.
+      #
+      # The string will be returned untranslated or in the default OS language
+      # when supported by the OS and USB device.
+      #
+      # @param [Symbol, Integer] string_type   One of {Call::DeviceStringType}
+      #
+      # Available since libusb-1.0.30
+      #
+      def device_string(string_type)
+        buffer = FFI::MemoryPointer.new(DEVICE_STRING_BYTES_MAX)
+        res = Call.libusb_get_device_string(@pDev, string_type, buffer, buffer.size)
+        LIBUSB.raise_error res, "in libusb_get_device_string" if res<0
+        buffer.read_bytes(res)
+      end
+    end
+
+    if Call.respond_to?(:libusb_get_session_data)
+      # Returns the backend-specific identifier of the underlying system device tree
+      # node. Can be used to find the corresponding system device and directly query
+      # it (or access it otherwise) when and if necessary.
+      #
+      # Relevant backends:
+      # - Darwin: IOKit `sessionID`
+      # - Windows WinUSB: `DEVINST`
+      # - Linux, BSD: `busnum << 8 | devnum`
+      #
+      # Since version 1.0.30, \ref LIBUSB_API_VERSION >= 0x0100010C
+      #
+      # \param dev a device (must not be null)
+      # \returns the backend-specific device identifier
+      def get_session_data
+        Call.libusb_get_session_data(@pDev)
+      end
+    end
 
     def inspect
       attrs = []
@@ -339,9 +384,13 @@ module LIBUSB
       "\#<#{self.class} #{attrs.join(' ')}>"
     end
 
-    def try_string_descriptor_ascii(i)
+    def try_string_descriptor_ascii(i, enum=nil)
       begin
-        open{|h| h.string_descriptor_ascii(i) }
+        if enum && respond_to?(:device_string)
+          device_string(enum)
+        else
+          open{|h| h.string_descriptor_ascii(i) }
+        end
       rescue
         "?"
       end
@@ -351,7 +400,7 @@ module LIBUSB
     # @return String
     def manufacturer
       return @manufacturer if defined? @manufacturer
-      @manufacturer = try_string_descriptor_ascii(self.iManufacturer)
+      @manufacturer = try_string_descriptor_ascii(self.iManufacturer, DEVICE_STRING_MANUFACTURER)
       @manufacturer = @manufacturer.strip if @manufacturer
       @manufacturer
     end
@@ -360,7 +409,7 @@ module LIBUSB
     # @return String
     def product
       return @product if defined? @product
-      @product = try_string_descriptor_ascii(self.iProduct)
+      @product = try_string_descriptor_ascii(self.iProduct, DEVICE_STRING_PRODUCT)
       @product = @product.strip if @product
       @product
     end
@@ -369,7 +418,7 @@ module LIBUSB
     # @return String
     def serial_number
       return @serial_number if defined? @serial_number
-      @serial_number = try_string_descriptor_ascii(self.iSerialNumber)
+      @serial_number = try_string_descriptor_ascii(self.iSerialNumber, DEVICE_STRING_SERIAL_NUMBER)
       @serial_number = @serial_number.strip if @serial_number
       @serial_number
     end

data/lib/libusb/eventmachine.rb

@@ -52,7 +52,12 @@ class Context
       # Libusb pollfd API is not available on this platform.
       # Use simple polling timer, instead:
       EventMachine.add_periodic_timer(0.01) do
-        @eventmachine_timer = self.handle_events 0
+        begin
+          @eventmachine_timer = self.handle_events 0
+        rescue ERROR_INTERRUPTED
+          # Interrupted by a signal; nothing was handled. The next tick of this
+          # periodic timer retries. See the pollfd callback below.
+        end
       end
     end
   end
@@ -98,7 +103,18 @@ class Context
         @eventmachine_timer = nil
       end
 
-      self.handle_events 0
+      begin
+        self.handle_events 0
+      rescue ERROR_INTERRUPTED
+        # poll() was interrupted by a signal, so no events were handled. This
+        # is transient and retryable: the descriptor stays watched and the next
+        # readable/writable event re-enters this callback. Without this rescue
+        # the exception unwinds out of EventMachine.run and takes the whole
+        # reactor (and typically the process) down. Same handling as the
+        # synchronous transfer path in transfer.rb.
+        next
+      end
+
       timeout = self.next_timeout
 #         puts "libusb new timeout: #{timeout.inspect}"
       if timeout

data/lib/libusb/gem_helper.rb

@@ -14,6 +14,7 @@
 # along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
 
 require "bundler/gem_helper"
+require 'ostruct'
 
 module LIBUSB
   class GemHelper < Bundler::GemHelper

data/lib/libusb/transfer.rb

@@ -311,9 +311,9 @@ module LIBUSB
       # Set a transfers bulk stream id.
       #
       # @param [Fixnum] stream_id  the stream id to set
-      def stream_id=(v)
-        Call.libusb_transfer_set_stream_id(@transfer, v)
-        v
+      def stream_id=(stream_id)
+        Call.libusb_transfer_set_stream_id(@transfer, stream_id)
+        stream_id
       end
 
       # Get a transfers bulk stream id.

data/lib/libusb/version_gem.rb

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

data/test/test_libusb_bos.rb

@@ -62,7 +62,7 @@ class TestLibusbBos < Minitest::Test
                 :BT_BATTERY_INFO_CAPABILITY,
                 :BT_PD_CONSUMER_PORT_CAPABILITY,
                 :BT_PD_PROVIDER_PORT_CAPABILITY,
-                :BT_SUPERSPEED_PLUS,
+                :BT_SUPERSPEED_PLUS_CAPABILITY,
                 :BT_PRECISION_TIME_MEASUREMENT,
                 :BT_Wireless_USB_Ext,
                 :BT_BILLBOARD,
@@ -77,11 +77,14 @@ class TestLibusbBos < Minitest::Test
           caps.each do |cap|
             did_cap = true
 
-            assert_operator 4, :<=, cap.bLength
-            assert_equal LIBUSB::DT_DEVICE_CAPABILITY, cap.bDescriptorType
-            assert_kind_of String, cap.dev_capability_data, "should provide binary capability data"
+            unless cap.is_a?(Bos::SsplusUsbDeviceCapability)
+              assert_operator 4, :<=, cap.bLength
+              assert_equal LIBUSB::DT_DEVICE_CAPABILITY, cap.bDescriptorType
+              assert_kind_of String, cap.dev_capability_data, "should provide binary capability data"
+              assert_operator 1, :<=, cap.dev_capability_data.length, "dev_capability_data should be at least one byte"
+            end
             assert_kind_of String, cap.inspect, "should respond to inspect"
-            assert_operator 1, :<=, cap.dev_capability_data.length, "dev_capability_data should be at least one byte"
+            assert_match(/\#<#{cap.class}/, cap.inspect, "inspect contains the class name")
 
             case cap
               when Bos::DeviceCapability
@@ -102,6 +105,25 @@ class TestLibusbBos < Minitest::Test
                 assert_operator 0, :<=, cap.bU1DevExitLat
                 assert_operator 0, :<=, cap.bU2DevExitLat
 
+              when Bos::SsplusUsbDeviceCapability
+                assert_kind_of Array, cap.sublinkSpeedAttributes
+                assert_equal cap.numSublinkSpeedAttributes, cap.sublinkSpeedAttributes.size
+                assert_operator 1, :<=, cap.numSublinkSpeedIDs
+                assert_operator 1, :<=, cap.numSublinkSpeedAttributes
+                assert_kind_of Integer, cap.ssid
+                assert_operator 0, :<=, cap.minRxLaneCount
+                assert_operator 0, :<=, cap.minTxLaneCount
+
+                sl = cap.sublinkSpeedAttributes[0]
+                assert_match(/id=.* SuperSpeed/, sl.to_s_human_readable)
+                assert_kind_of String, sl.inspect, "should respond to inspect"
+                assert_kind_of Integer, sl.ssid
+                assert_kind_of Symbol, sl.exponent
+                assert_kind_of Symbol, sl.type
+                assert_kind_of Symbol, sl.direction
+                assert_kind_of Symbol, sl.protocol
+                assert_operator 1, :<=, sl.mantissa
+
               when Bos::ContainerId
                 assert_equal 4, cap.bDevCapabilityType
                 assert_operator 0, :<=, cap.bReserved

data/test/test_libusb_descriptors.rb

@@ -45,6 +45,10 @@ class TestLibusbDescriptors < Minitest::Test
       assert_kind_of Integer, dev.iSerialNumber
       assert_kind_of Integer, dev.bNumConfigurations
 
+      assert_kind_of String,  dev.manufacturer
+      assert_kind_of String,  dev.product
+      assert_kind_of String,  dev.serial_number
+
       dev.configurations.each do |config_desc|
         assert_match(/Configuration/, config_desc.inspect, "ConfigDescriptor#inspect should work")
         assert dev.configurations.include?(config_desc), "Device#configurations should include this one"
@@ -242,4 +246,13 @@ class TestLibusbDescriptors < Minitest::Test
       end
     end
   end
+
+  def test_get_session_data
+    skip "libusb version older than 1.0.30" if Gem::Version.new(LIBUSB.version) < Gem::Version.new("1.0.30")
+
+    usb.devices.each do |dev|
+      assert_kind_of Integer, dev.get_session_data
+      refute_equal 0, dev.get_session_data
+    end
+  end
 end

data/test/test_libusb_event_machine_eintr.rb

@@ -0,0 +1,81 @@
+# 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"
+require "libusb/eventmachine"
+require "eventmachine"
+
+# LIBUSB_ERROR_INTERRUPTED means poll() was interrupted by a signal and no
+# events were handled. It is transient and retryable, but Context#handle_events
+# raises on it like any other negative return, and the EventMachine integration
+# used to call handle_events unrescued -- so a signal arriving at the wrong
+# moment unwound out of EventMachine.run and killed the reactor.
+#
+# These tests need no USB device: they drive the registered callback directly.
+class TestLibusbEventMachineEintr < Minitest::Test
+  include LIBUSB
+
+  def setup
+    @context = Context.new
+    skip "libusb pollfd API not available on this platform" unless @context.pollfds&.any?
+  end
+
+  # The callback the pollfd handler invokes must swallow ERROR_INTERRUPTED and
+  # leave the reactor running.
+  def test_pollfd_callback_survives_eintr
+    interrupts = 0
+    @context.define_singleton_method(:handle_events) do |*|
+      interrupts += 1
+      raise LIBUSB::ERROR_INTERRUPTED
+    end
+
+    assert dispatch_pollfd_events, "reactor must stay up after ERROR_INTERRUPTED"
+    assert_operator interrupts, :>=, 1, "handle_events should have been called"
+  end
+
+  # Only ERROR_INTERRUPTED is transient. Every other libusb error must still
+  # propagate, so a real fault is not silently swallowed.
+  def test_pollfd_callback_still_raises_other_errors
+    @context.define_singleton_method(:handle_events) do |*|
+      raise LIBUSB::ERROR_NO_DEVICE
+    end
+
+    assert_raises(LIBUSB::ERROR_NO_DEVICE) { dispatch_pollfd_events }
+  end
+
+  private
+
+  # Run the reactor, register libusb's pollfds with it and invoke the resulting
+  # callbacks exactly as EMPollfdHandler#notify_readable does. Returns whether
+  # the reactor was still running once they had been dispatched.
+  def dispatch_pollfd_events
+    reactor_alive = false
+
+    EventMachine.run do
+      @context.eventmachine_register
+
+      begin
+        @context.instance_variable_get(:@eventmachine_attached_fds).each_value(&:need_handle_events)
+        reactor_alive = EventMachine.reactor_running?
+      ensure
+        @context.eventmachine_unregister
+        EventMachine.stop
+      end
+    end
+
+    reactor_alive
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: libusb
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Lars Kanis
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -81,7 +80,7 @@ files:
 - lib/libusb/version_gem.rb
 - lib/libusb/version_struct.rb
 - libusb.gemspec
-- ports/archives/libusb-1.0.27.tar.bz2
+- ports/archives/libusb-1.0.30.tar.bz2
 - test/test_libusb.rb
 - test/test_libusb_bos.rb
 - test/test_libusb_bulk_stream_transfer.rb
@@ -90,6 +89,7 @@ files:
 - test/test_libusb_context.rb
 - test/test_libusb_descriptors.rb
 - test/test_libusb_event_machine.rb
+- test/test_libusb_event_machine_eintr.rb
 - test/test_libusb_gc.rb
 - test/test_libusb_hotplug.rb
 - test/test_libusb_iso_transfer.rb
@@ -103,7 +103,6 @@ licenses:
 - LGPL-3.0
 metadata:
   yard.run: yri
-post_install_message: 
 rdoc_options:
 - "--main"
 - README.md
@@ -121,8 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key: 
+rubygems_version: 4.1.0.dev
 specification_version: 4
 summary: Access USB devices from Ruby via libusb-1.0
 test_files: []