Added in API level 12

UsbDeviceConnection

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

Claims exclusive access to a android.hardware.usb.UsbInterface.
open Unit

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

Returns the native file descriptor for the device, or -1 if the device is not opened.
open ByteArray!

Returns the raw USB descriptors for the device.
open String!

Returns the serial number for the device.
open Boolean

Releases exclusive access to a android.hardware.usb.UsbInterface.
open UsbRequest!

Waits for the result of a android.
open UsbRequest!
requestWait(timeout: Long)

Waits for the result of a android.
open Boolean

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

Sets the current android.hardware.usb.UsbInterface.
Protected methods
open Unit

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

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.

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

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.

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