libusb 0.6.4 → 0.7.0

data/lib/libusb/bos.rb

@@ -19,7 +19,7 @@ module LIBUSB
   # A structure representing the Binary Device Object Store (BOS) descriptor.
   # This descriptor is documented in section 9.6.2 of the USB 3.0 specification.
   # All multiple-byte fields are represented in host-endian format.
-  class Bos < FFI::ManagedStruct
+  class Bos < FFI::Struct
 
     module GenericMethods
       # @return [Integer]  Size of this descriptor (in bytes)
@@ -39,7 +39,7 @@ module LIBUSB
       end
 
       def inspect
-        "\#<#{self.class} cap: #{bDevCapabilityType} data: #{dev_capability_data.unpack("H*")[0]}>"
+        "\#<#{self.class} cap: #{bDevCapabilityType} data: #{dev_capability_data.unpack1("H*")}>"
       end
 
       # @return [String]  Device Capability data (bLength - 3 bytes)
@@ -66,14 +66,21 @@ module LIBUSB
     # A structure representing the USB 2.0 Extension descriptor
     # This descriptor is documented in section 9.6.2.1 of the USB 3.0 specification.
     # All multiple-byte fields are represented in host-endian format.
-    class Usb20Extension < FFI::ManagedStruct
+    class Usb20Extension < FFI::Struct
       include GenericMethods
+      include ContextReference
 
       layout :bLength, :uint8,
           :bDescriptorType, :uint8,
           :bDevCapabilityType, :uint8,
           :bmAttributes, :uint32
 
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_usb_2_0_extension_descriptor)
+      end
+
       # Bitmap encoding of supported device level features.
       # A value of one in a bit location indicates a feature is
       # supported; a value of zero indicates it is not supported.
@@ -93,28 +100,30 @@ module LIBUSB
         end
         "\#<#{self.class} #{attrs.compact.join(",")}>"
       end
-
-      # @private
-      def self.release(ptr)
-        Call.libusb_free_usb_2_0_extension_descriptor(ptr)
-      end
     end
 
     # A structure representing the SuperSpeed USB Device Capability descriptor
     # This descriptor is documented in section 9.6.2.2 of the USB 3.0 specification.
     # All multiple-byte fields are represented in host-endian format.
-    class SsUsbDeviceCapability < FFI::ManagedStruct
+    class SsUsbDeviceCapability < FFI::Struct
       include GenericMethods
+      include ContextReference
 
       layout :bLength, :uint8,
           :bDescriptorType, :uint8,
           :bDevCapabilityType, :uint8,
-          :bmAttributes, :uint32,
+          :bmAttributes, :uint8,
           :wSpeedSupported, :uint16,
           :bFunctionalitySupport, :uint8,
           :bU1DevExitLat, :uint8,
           :bU2DevExitLat, :uint16
 
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_ss_usb_device_capability_descriptor)
+      end
+
       # Bitmap encoding of supported device level features.
       # A value of one in a bit location indicates a feature is
       # supported; a value of zero indicates it is not supported.
@@ -178,18 +187,14 @@ module LIBUSB
       def bU2DevExitLat
         self[:bU2DevExitLat]
       end
-
-      # @private
-      def self.release(ptr)
-        Call.libusb_free_ss_usb_device_capability_descriptor(ptr)
-      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.
-    class ContainerId < FFI::ManagedStruct
+    class ContainerId < FFI::Struct
       include GenericMethods
+      include ContextReference
 
       layout :bLength, :uint8,
           :bDescriptorType, :uint8,
@@ -197,6 +202,12 @@ module LIBUSB
           :bReserved, :uint8,
           :ContainerID, [:uint8, 16]
 
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_container_id_descriptor)
+      end
+
       # Reserved field
       def bReserved
         self[:bReserved]
@@ -208,18 +219,65 @@ module LIBUSB
       end
 
       def inspect
-        "\#<#{self.class} #{container_id.unpack("H*")[0]}>"
+        "\#<#{self.class} #{container_id.unpack1("H*")}>"
+      end
+    end
+
+
+    # A structure representing a Platform descriptor.
+    # This descriptor is documented in section 9.6.2.4 of the USB 3.2 specification.
+    class PlatformDescriptor < FFI::Struct
+      include GenericMethods
+      include ContextReference
+
+      layout :bLength, :uint8,
+          :bDescriptorType, :uint8,
+          # Capability type. Will have value
+          # libusb_capability_type::LIBUSB_BT_PLATFORM_DESCRIPTOR
+          # LIBUSB_BT_CONTAINER_ID in this context.
+          :bDevCapabilityType, :uint8,
+          # Reserved field
+          :bReserved, :uint8,
+          # 128 bit UUID
+          :PlatformCapabilityUUID, [:uint8, 16],
+          # Capability data (bLength - 20)
+          :CapabilityData, [:uint8, 0]
+
+      def initialize(ctx, *args)
+        super(*args)
+
+        register_context(ctx, :libusb_free_platform_descriptor)
+      end
+
+      # Reserved field
+      def bReserved
+        self[:bReserved]
+      end
+
+      # @return [String] 128 bit UUID
+      def platformCapabilityUUID
+        self[:PlatformCapabilityUUID].to_ptr.read_bytes(16)
       end
 
-      # @private
-      def self.release(ptr)
-        Call.libusb_free_container_id_descriptor(ptr)
+      # This is a variable-length field containing data associated with the platform specific capability.
+      # This field may be zero bytes in length.
+      # @return [String]
+      def capabilityData
+        self[:CapabilityData].to_ptr.read_bytes(bLength - 20)
+      end
+
+      def inspect
+        "\#<#{self.class} #{platformCapabilityUUID.unpack1("H*")} (#{capabilityData.unpack1("H*")})>"
       end
     end
 
-    def initialize( ctx, *args)
+    include ContextReference
+
+    def initialize(ctx, *args)
       @ctx = ctx
       super(*args)
+
+      register_context(ctx, :libusb_free_bos_descriptor)
     end
 
     layout :bLength, :uint8,
@@ -265,13 +323,16 @@ module LIBUSB
             # no struct defined in libusb -> use generic DeviceCapability
           when LIBUSB::BT_USB_2_0_EXTENSION
             res = Call.libusb_get_usb_2_0_extension_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = Usb20Extension.new(pp_ext.read_pointer) if res==0
+            cap = Usb20Extension.new(@ctx, pp_ext.read_pointer) if res==0
           when LIBUSB::BT_SS_USB_DEVICE_CAPABILITY
             res = Call.libusb_get_ss_usb_device_capability_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = SsUsbDeviceCapability.new(pp_ext.read_pointer) if res==0
+            cap = SsUsbDeviceCapability.new(@ctx, pp_ext.read_pointer) if res==0
           when LIBUSB::BT_CONTAINER_ID
             res = Call.libusb_get_container_id_descriptor(@ctx, cap.pointer, pp_ext)
-            cap = ContainerId.new(pp_ext.read_pointer) if res==0
+            cap = ContainerId.new(@ctx, pp_ext.read_pointer) if res==0
+          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
           else
             # unknown capability -> use generic DeviceCapability
         end
@@ -297,10 +358,5 @@ module LIBUSB
     def inspect
       "\#<#{self.class} #{device_capability_types.join(", ")}>"
     end
-
-    # @private
-    def self.release(ptr)
-      Call.libusb_free_bos_descriptor(ptr)
-    end
   end
 end

data/lib/libusb/call.rb

@@ -228,14 +228,23 @@ module LIBUSB
     #
     # @see Bos::DeviceCapability
     BosTypes = enum :libusb_bos_type, [
-      # Wireless USB device capability
-      :BT_WIRELESS_USB_DEVICE_CAPABILITY, 1,
-      # USB 2.0 extensions
-      :BT_USB_2_0_EXTENSION, 2,
-      # SuperSpeed USB device capability
-      :BT_SS_USB_DEVICE_CAPABILITY, 3,
-      # Container ID type
-      :BT_CONTAINER_ID, 4,
+      :BT_WIRELESS_USB_DEVICE_CAPABILITY, 0x01, # Wireless USB device capability
+      :BT_USB_2_0_EXTENSION, 0x02, # USB 2.0 extensions
+      :BT_SS_USB_DEVICE_CAPABILITY, 0x03, # SuperSpeed USB device capability
+      :BT_CONTAINER_ID, 0x04, # Container ID type
+      :BT_PLATFORM_DESCRIPTOR, 0x05, # Platform descriptor
+      :BT_POWER_DELIVERY_CAPABILITY, 0x06, # Defines the various PD Capabilities of this device
+      :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_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
+      :BT_AUTHENTICATION, 0x0E, # Authentication Capability Descriptor
+      :BT_BILLBOARD_EX, 0x0F, # Billboard Ex capability
+      :BT_CONFIGURATION_SUMMARY, 0x10, # Summarizes configuration information for a function implemented by the device
+      :BT_FWStatus_Capability, 0x11, # Describes the capability to support FWStatus
     ]
 
     # Since libusb version 1.0.16.
@@ -274,6 +283,25 @@ module LIBUSB
       :LOG_LEVEL_DEBUG, 4,
     ]
 
+    # /** \ingroup libusb_lib
+    #  *  Log callback mode.
+    #  *
+    #  *  Since version 1.0.23, \ref LIBUSB_API_VERSION >= 0x01000107
+    #  *
+    #  * \see libusb_set_log_cb()
+    #  */
+    # enum libusb_log_cb_mode {
+    #   /** Callback function handling all log messages. */
+    #   LIBUSB_LOG_CB_GLOBAL = (1 << 0),
+    #
+    #   /** Callback function handling context related log messages. */
+    #   LIBUSB_LOG_CB_CONTEXT = (1 << 1)
+    # };
+    LogCbMode = enum :libusb_log_cb_mode, [
+      :LOG_CB_GLOBAL, (1 << 0),
+      :LOG_CB_CONTEXT, (1 << 1),
+    ]
+
     # Available option values for {Context#set_option}.
     Options = enum :libusb_option, [
       # Set the log message verbosity.
@@ -296,7 +324,7 @@ module LIBUSB
       #
       # If libusb was compiled with verbose debug message logging, this function
       # does nothing: you'll always get messages from all levels.
-      :OPTION_LOG_LEVEL,
+      :OPTION_LOG_LEVEL, 0,
 
       # Use the UsbDk backend for a specific context, if available.
       #
@@ -306,7 +334,33 @@ module LIBUSB
       # Only valid on Windows.
       #
       # Available since libusb-1.0.22.
-      :OPTION_USE_USBDK,
+      :OPTION_USE_USBDK, 1,
+
+      # Do not scan for devices
+      #
+      # With this option set, libusb will skip scanning devices in
+      # libusb_init_context().
+      #
+      # Hotplug functionality will also be deactivated.
+      #
+      # The option is useful in combination with libusb_wrap_sys_device(),
+      # which can access a device directly without prior device scanning.
+      #
+      # This is typically needed on Android, where access to USB devices
+      # is limited.
+      #
+      # Only valid on Linux. Ignored on all other platforms.
+      :OPTION_NO_DEVICE_DISCOVERY, 2,
+
+      # Set the context log callback functon.
+      #
+      # Set the log callback function either on a context or globally.
+      # This option must be provided a Proc argument or +nil+ to remove the callback.
+      # Using this option with a +nil+ context is equivalent to calling libusb_set_log_cb with mode :LOG_CB_GLOBAL.
+      # Using it with a non- +nil+ context is equivalent to calling libusb_set_log_cb with mode :LOG_CB_CONTEXT.
+      :OPTION_LOG_CB, 3,
+
+      :OPTION_MAX, 4,
     ]
 
     typedef :pointer, :libusb_context
@@ -315,15 +369,60 @@ module LIBUSB
     typedef :pointer, :libusb_transfer
     typedef :int, :libusb_hotplug_callback_handle
 
-    def self.try_attach_function(method, *args)
-      if ffi_libraries.find{|lib| lib.find_function(method) }
-        attach_function method, *args
+    # /** \ingroup libusb_lib
+    #  * Callback function for handling log messages.
+    #  * \param ctx the context which is related to the log message, or +nil+ if it
+    #  * is a global log message
+    #  * \param level the log level, see \ref libusb_log_level for a description
+    #  * \param str the log message
+    #  *
+    #  * Since version 1.0.23, \ref LIBUSB_API_VERSION >= 0x01000107
+    #  *
+    #  * \see libusb_set_log_cb()
+    #  */
+    # typedef void (LIBUSB_CALL *libusb_log_cb)(libusb_context *ctx,
+    #               enum libusb_log_level level, const char *str);
+    callback :libusb_log_cb, [:libusb_context, :libusb_log_level, :string], :void
+
+    # @private
+    # /** \ingroup libusb_lib
+    #  * Structure used for setting options through \ref libusb_init_context.
+    #  *
+    #  */
+    # struct libusb_init_option {
+    #     /** Which option to set */
+    #     enum libusb_option option;
+    #     /** An integer value used by the option (if applicable). */
+    #     union {
+    #         int64_t ival;
+    #         libusb_log_cb log_cbval;
+    #     } value;
+    # };
+    class InitOptionValue < FFI::Union
+      layout :ival, :int64_t,
+             :log_cbval, :libusb_log_cb
+    end
+    class InitOption < FFI::Struct
+      layout :option, :libusb_option,
+        :value, InitOptionValue
+    end
+
+    class << self
+      private def try_attach_function(method, *args, **kwargs)
+        if ffi_libraries.find{|lib| lib.find_function(method) }
+          attach_function method, *args, **kwargs
+        end
       end
     end
 
     try_attach_function 'libusb_get_version', [], :pointer
 
     attach_function 'libusb_init', [ :pointer ], :int
+    # int LIBUSB_CALL libusb_init_context(libusb_context **ctx, const struct libusb_init_option options[], int num_options);
+    try_attach_function 'libusb_init_context', [:pointer, :pointer, :int], :int
+    # may be deprecated in the future in favor of libusb_init_context()+libusb_set_option()
+    # void LIBUSB_CALL libusb_set_log_cb(libusb_context *ctx, libusb_log_cb cb, int mode);
+    try_attach_function 'libusb_set_log_cb', [:libusb_context, :libusb_log_cb, :int], :void
     attach_function 'libusb_exit', [ :pointer ], :void
     attach_function 'libusb_set_debug', [:pointer, :libusb_log_level], :void
     try_attach_function 'libusb_set_option', [:libusb_context, :libusb_option, :varargs], :int
@@ -348,6 +447,8 @@ module LIBUSB
     try_attach_function 'libusb_get_device_speed', [:pointer], :libusb_speed
     attach_function 'libusb_get_max_packet_size', [:pointer, :uint8], :int
     attach_function 'libusb_get_max_iso_packet_size', [:pointer, :uint8], :int
+    # int API_EXPORTED libusb_get_max_alt_packet_size(libusb_device *dev, int interface_number, int alternate_setting, unsigned char endpoint)
+    try_attach_function 'libusb_get_max_alt_packet_size', [:pointer, :int, :int, :uchar], :int
 
     try_attach_function 'libusb_get_ss_endpoint_companion_descriptor', [:pointer, :pointer, :pointer], :int
     try_attach_function 'libusb_free_ss_endpoint_companion_descriptor', [:pointer], :void
@@ -360,7 +461,11 @@ module LIBUSB
     try_attach_function 'libusb_free_ss_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
+    try_attach_function 'libusb_free_platform_descriptor', [:pointer], :void
 
+    # int LIBUSB_CALL libusb_wrap_sys_device(libusb_context *ctx, intptr_t sys_dev, libusb_device_handle **dev_handle);
+    try_attach_function 'libusb_wrap_sys_device', [:libusb_context, :intptr_t, :pointer], :int
     attach_function 'libusb_open', [:pointer, :pointer], :int
     attach_function 'libusb_close', [:pointer], :void
     attach_function 'libusb_get_device', [:libusb_device_handle], :pointer
@@ -431,7 +536,7 @@ module LIBUSB
           :wLength, :uint16
     end
 
-    class Transfer < FFI::ManagedStruct
+    class Transfer < FFI::Struct
       layout :dev_handle, :libusb_device_handle,
         :flags, :uint8,
         :endpoint, :uchar,
@@ -445,8 +550,19 @@ module LIBUSB
         :buffer, :pointer,
         :num_iso_packets, :int
 
-      def self.release(ptr)
-        Call.libusb_free_transfer(ptr)
+      def initialize(*)
+        super
+
+        ptr = pointer
+        def ptr.free_struct(id)
+          Call.libusb_free_transfer(self)
+          return unless @ctx
+          @ctx.unref_context
+        end
+        # The ctx pointer is not yet assigned.
+        # It happens at LIBUSB::Transfer#dev_handle= later on.
+        ptr.instance_variable_set(:@ctx, nil)
+        ObjectSpace.define_finalizer(self, ptr.method(:free_struct))
       end
     end
 

data/lib/libusb/configuration.rb

@@ -16,8 +16,9 @@
 require 'libusb/call'
 
 module LIBUSB
-  class Configuration < FFI::ManagedStruct
+  class Configuration < FFI::Struct
     include Comparable
+    include ContextReference
 
     layout :bLength, :uint8,
         :bDescriptorType, :uint8,
@@ -108,10 +109,8 @@ module LIBUSB
     def initialize(device, *args)
       @device = device
       super(*args)
-    end
 
-    def self.release(ptr)
-      Call.libusb_free_config_descriptor(ptr)
+      register_context(device.context.instance_variable_get(:@ctx), :libusb_free_config_descriptor)
     end
 
     # @return [Device] the device this configuration belongs to.

data/lib/libusb/constants.rb

@@ -34,6 +34,7 @@ module LIBUSB
     Call::HotplugEvents,
     Call::HotplugFlags,
     Call::LogLevels,
+    Call::LogCbMode,
     Call::Options,
   ].each do |enum|
     enum.to_h.each{|k,v| const_set(k,v) }
@@ -52,6 +53,9 @@ module LIBUSB
     end
   end
 
+  class RemainingReferencesError < Error
+  end
+
   # @private
   ErrorClassForResult = {}