Method: LIBUSB::DevHandle#interrupt_transfer

Defined in:
lib/libusb/dev_handle.rb

#interrupt_transfer(timeout: 1000, endpoint:, dataIn: nil, dataOut: nil, allow_device_memory: false) {|result| ... } ⇒ Fixnum, ...

Perform a USB interrupt transfer.

When called without a block, the transfer is done synchronously - so all events are handled internally and the sent/received data will be returned after completion or an exception will be raised.

When called with a block, the method returns immediately after submitting the transfer. You then have to ensure, that Context#handle_events is called properly. As soon as the transfer is completed, the block is called with the sent/received data in case of success or the exception instance in case of failure.

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 are expecting to receive. If less data arrives than expected, this function will return that data.

You should check the returned number of bytes for interrupt writes. Not all of the data may have been written.

Also check Error#transferred when dealing with a timeout exception. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O.

The default endpoint bInterval value is used as the polling interval.

Parameters:

  • args (Hash)

Yield Parameters:

  • result (String, Integer, LIBUSB::Error) —

    result of the transfer is yielded to the block, when the asynchronous transfer has finished

Returns:

  • (Fixnum) —

    Number of bytes sent for an outgoing transfer

  • (String) —

    Received data for an ingoing transfer

  • (self) —

    When called with a block

Raises:


446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
 
# File 'lib/libusb/dev_handle.rb', line 446

def interrupt_transfer(timeout: 1000,
                       endpoint:,
                       dataIn: nil,
                       dataOut: nil,
                       allow_device_memory: false,
                       &block)
  endpoint = endpoint.bEndpointAddress if endpoint.respond_to? :bEndpointAddress
  if endpoint&ENDPOINT_IN != 0
    dataIn || raise(ArgumentError, "no :dataIn given for interrupt read")
  else
    dataOut || raise(ArgumentError, "no :dataOut given for interrupt write")
  end

  # reuse transfer struct to speed up transfer
  @interrupt_transfer ||= InterruptTransfer.new dev_handle: self, allow_device_memory: allow_device_memory
  tr = @interrupt_transfer
  tr.endpoint = endpoint
  tr.timeout = timeout
  if dataOut
    tr.buffer = dataOut
  else
    tr.alloc_buffer(dataIn)
  end

  submit_transfer(tr, dataIn, 0, &block)
end