Method: LIBUSB::DevHandle#interrupt_transfer

Defined in:
lib/libusb/dev_handle.rb

#interrupt_transfer(args = {}) {|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) (defaults to: {})

Options Hash (args):

  • :endpoint (Endpoint, Fixnum) —

    the (address of a) valid endpoint to communicate with

  • :dataOut (String) —

    the data to send with an outgoing transfer

  • :dataIn (Fixnum) —

    the number of bytes expected to receive with an ingoing transfer

  • :timeout (Fixnum) —

    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.

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:



365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'lib/libusb/dev_handle.rb', line 365

def interrupt_transfer(args={}, &block)
  timeout = args.delete(:timeout) || 1000
  endpoint = args.delete(:endpoint) || raise(ArgumentError, "no endpoint given")
  endpoint = endpoint.bEndpointAddress if endpoint.respond_to? :bEndpointAddress
  if endpoint&ENDPOINT_IN != 0
    dataIn = args.delete(:dataIn) || raise(ArgumentError, "no :dataIn given for interrupt read")
  else
    dataOut = args.delete(:dataOut) || raise(ArgumentError, "no :dataOut given for interrupt write")
  end
  raise ArgumentError, "invalid params #{args.inspect}" unless args.empty?

  # reuse transfer struct to speed up transfer
  @interrupt_transfer ||= InterruptTransfer.new :dev_handle => self
  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