UsbDeviceConnection

Kotlin |Java

open class UsbDeviceConnection

kotlin.Any
↳	android.hardware.usb.UsbDeviceConnection

This class is used for sending and receiving data and control messages to a USB device. Instances of this class are created by UsbManager#openDevice.

Summary

Public methods
open Int	`bulkTransfer(endpoint: UsbEndpoint!, buffer: ByteArray!, length: Int, timeout: Int)` Performs a bulk transaction on the given endpoint.
open Int	`bulkTransfer(endpoint: UsbEndpoint!, buffer: ByteArray!, offset: Int, length: Int, timeout: Int)` Performs a bulk transaction on the given endpoint.
open Boolean	`claimInterface(intf: UsbInterface!, force: Boolean)` Claims exclusive access to a `android.hardware.usb.UsbInterface`.
open Unit	`close()` Releases all system resources related to the device.
open Int	`controlTransfer(requestType: Int, request: Int, value: Int, index: Int, buffer: ByteArray?, length: Int, timeout: Int)` Performs a control transaction on endpoint zero for this device.
open Int	`controlTransfer(requestType: Int, request: Int, value: Int, index: Int, buffer: ByteArray?, offset: Int, length: Int, timeout: Int)` Performs a control transaction on endpoint zero for this device.
open Int	`getFileDescriptor()` Returns the native file descriptor for the device, or -1 if the device is not opened.
open ByteArray!	`getRawDescriptors()` Returns the raw USB descriptors for the device.
open String!	`getSerial()` Returns the serial number for the device.
open Boolean	`releaseInterface(intf: UsbInterface!)` Releases exclusive access to a `android.hardware.usb.UsbInterface`.
open UsbRequest!	`requestWait()` Waits for the result of a android.
open UsbRequest!	`requestWait(timeout: Long)` Waits for the result of a android.
open Boolean	`setConfiguration(configuration: UsbConfiguration!)` Sets the device's current `android.hardware.usb.UsbConfiguration`.
open Boolean	`setInterface(intf: UsbInterface!)` Sets the current `android.hardware.usb.UsbInterface`.

Protected methods
open Unit	`finalize()`

Public methods

bulkTransfer

Added in API level 12

open fun bulkTransfer(
    endpoint: UsbEndpoint!, 
    buffer: ByteArray!, 
    length: Int, 
    timeout: Int
): Int

Performs a bulk transaction on the given endpoint. The direction of the transfer is determined by the direction of the endpoint.

This method transfers data starting from index 0 in the buffer. To specify a different offset, use bulkTransfer(android.hardware.usb.UsbEndpoint,byte[],int,int,int).

Parameters
`endpoint`	UsbEndpoint!: the endpoint for this transaction
`buffer`	ByteArray!: buffer for data to send or receive; can be `null` to wait for next transaction without reading data
`length`	Int: the length of the data to send or receive. Before {@value android.os.Build.VERSION_CODES#P Build.VERSION_CODES#P}, a value larger than 16384 bytes would be truncated down to 16384. In API {@value android.os.Build.VERSION_CODES#P Build.VERSION_CODES#P} and after, any value of length is valid.
`timeout`	Int: in milliseconds, 0 is infinite

Return
`Int`	length of data transferred (or zero) for success, or negative value for failure

bulkTransfer

Added in API level 18

open fun bulkTransfer(
    endpoint: UsbEndpoint!, 
    buffer: ByteArray!, 
    offset: Int, 
    length: Int, 
    timeout: Int
): Int

Performs a bulk transaction on the given endpoint. The direction of the transfer is determined by the direction of the endpoint.

Parameters
`endpoint`	UsbEndpoint!: the endpoint for this transaction
`buffer`	ByteArray!: buffer for data to send or receive
`offset`	Int: the index of the first byte in the buffer to send or receive
`length`	Int: the length of the data to send or receive. Before {@value android.os.Build.VERSION_CODES#P Build.VERSION_CODES#P}, a value larger than 16384 bytes would be truncated down to 16384. In API {@value android.os.Build.VERSION_CODES#P Build.VERSION_CODES#P} and after, any value of length is valid.
`timeout`	Int: in milliseconds, 0 is infinite

Return
`Int`	length of data transferred (or zero) for success, or negative value for failure

claimInterface

Added in API level 12

open fun claimInterface(
    intf: UsbInterface!, 
    force: Boolean
): Boolean

Claims exclusive access to a android.hardware.usb.UsbInterface. This must be done before sending or receiving data on any android.hardware.usb.UsbEndpoints belonging to the interface.

Parameters
`intf`	UsbInterface!: the interface to claim
`force`	Boolean: true to disconnect kernel driver if necessary

Return
`Boolean`	true if the interface was successfully claimed

close

Added in API level 12

open fun close(): Unit

Releases all system resources related to the device. Once the object is closed it cannot be used again. The client must call UsbManager#openDevice again to retrieve a new instance to reestablish communication with the device.

controlTransfer

Added in API level 12

open fun controlTransfer(
    requestType: Int, 
    request: Int, 
    value: Int, 
    index: Int, 
    buffer: ByteArray?, 
    length: Int, 
    timeout: Int
): Int

Performs a control transaction on endpoint zero for this device. The direction of the transfer is determined by the request type. If requestType & UsbConstants#USB_ENDPOINT_DIR_MASK is UsbConstants#USB_DIR_OUT, then the transfer is a write, and if it is UsbConstants#USB_DIR_IN, then the transfer is a read.

This method transfers data starting from index 0 in the buffer. To specify a different offset, use controlTransfer(int,int,int,int,byte[],int,int,int).

Parameters
`requestType`	Int: request type for this transaction
`request`	Int: request ID for this transaction
`value`	Int: value field for this transaction
`index`	Int: index field for this transaction
`buffer`	ByteArray?: buffer for data portion of transaction, or null if no data needs to be sent or received
`length`	Int: the length of the data to send or receive
`timeout`	Int: in milliseconds

Return
`Int`	length of data transferred (or zero) for success, or negative value for failure

controlTransfer

Added in API level 18

open fun controlTransfer(
    requestType: Int, 
    request: Int, 
    value: Int, 
    index: Int, 
    buffer: ByteArray?, 
    offset: Int, 
    length: Int, 
    timeout: Int
): Int

Parameters
`requestType`	Int: request type for this transaction
`request`	Int: request ID for this transaction
`value`	Int: value field for this transaction
`index`	Int: index field for this transaction
`buffer`	ByteArray?: buffer for data portion of transaction, or null if no data needs to be sent or received
`offset`	Int: the index of the first byte in the buffer to send or receive
`length`	Int: the length of the data to send or receive
`timeout`	Int: in milliseconds

Return
`Int`	length of data transferred (or zero) for success, or negative value for failure

getFileDescriptor

Added in API level 12

open fun getFileDescriptor(): Int

Returns the native file descriptor for the device, or -1 if the device is not opened. This is intended for passing to native code to access the device.

Return
`Int`	the native file descriptor

getRawDescriptors

Added in API level 13

open fun getRawDescriptors(): ByteArray!

Returns the raw USB descriptors for the device. This can be used to access descriptors not supported directly via the higher level APIs.

Return
`ByteArray!`	raw USB descriptors

getSerial

Added in API level 12

open fun getSerial(): String!

Returns the serial number for the device. This will return null if the device has not been opened.

Return
`String!`	the device serial number

releaseInterface

Added in API level 12

open fun releaseInterface(intf: UsbInterface!): Boolean

Releases exclusive access to a android.hardware.usb.UsbInterface.

Return
`Boolean`	true if the interface was successfully released

requestWait

Added in API level 12

open fun requestWait(): UsbRequest!

Waits for the result of a android.hardware.usb.UsbRequest#queue operation

Note that this may return requests queued on multiple android.hardware.usb.UsbEndpoints. When multiple endpoints are in use, android.hardware.usb.UsbRequest#getEndpoint and android.hardware.usb.UsbRequest#getClientData can be useful in determining how to process the result of this function.

Return
`UsbRequest!`	a completed USB request, or null if an error occurred

Exceptions
`java.lang.IllegalArgumentException`	Before API {@value android.os.Build.VERSION_CODES#O Build.VERSION_CODES#O}: if the number of bytes read or written is more than the limit of the request's buffer. The number of bytes is determined by the `length` parameter of `UsbRequest#queue(ByteBuffer, int)`
`java.nio.BufferOverflowException`	In API {@value android.os.Build.VERSION_CODES#O Build.VERSION_CODES#O} and after: if the number of bytes read or written is more than the limit of the request's buffer. The number of bytes is determined by the `length` parameter of `UsbRequest#queue(ByteBuffer, int)`

requestWait

Added in API level 26

open fun requestWait(timeout: Long): UsbRequest!

Waits for the result of a android.hardware.usb.UsbRequest#queue operation

Android processes UsbRequests asynchronously. Hence it is not guaranteed that requestWait(0) returns a request that has been queued right before even if the request could have been processed immediately.

Parameters
`timeout`	Long: timeout in milliseconds. If 0 this method does not wait.

Return
`UsbRequest!`	a completed USB request, or `null` if an error occurred

Exceptions
`java.nio.BufferOverflowException`	if the number of bytes read or written is more than the limit of the request's buffer. The number of bytes is determined by the `length` parameter of `UsbRequest#queue(ByteBuffer, int)`
`java.util.concurrent.TimeoutException`	if no request was received in `timeout` milliseconds.

setConfiguration

Added in API level 21

open fun setConfiguration(configuration: UsbConfiguration!): Boolean

Sets the device's current android.hardware.usb.UsbConfiguration.

Return
`Boolean`	true if the configuration was successfully set

setInterface

Added in API level 21

open fun setInterface(intf: UsbInterface!): Boolean

Sets the current android.hardware.usb.UsbInterface. Used to select between two interfaces with the same ID but different alternate setting.

Return
`Boolean`	true if the interface was successfully selected

Protected methods

finalize

Added in API level 12

protected open fun finalize(): Unit

Exceptions
`java.lang.Throwable`	the `Exception` raised by this method