Module net.codecrete.usb

Package net.codecrete.usb

Interface UsbDevice

public interface UsbDevice

USB device.

In order to make control requests and transfer data, the device must be opened and an interface must be claimed. In the open state, this current process has exclusive access to the device.

Information about the device can be queried in both the open and the closed state.

Method Summary

Modifier and Type	Method	Description
void	abortTransfers(UsbDirection direction, int endpointNumber)	Aborts all transfers on an endpoint.
void	attachStandardDrivers()	Reattaches the standard operating-system drivers to this device.
void	claimInterface(int interfaceNumber)	Claims the specified interface for exclusive use.
void	clearHalt(UsbDirection direction, int endpointNumber)	Clears an endpoint's halt condition.
void	close()	Closes the device.
byte @NotNull []	controlTransferIn(@NotNull UsbControlTransfer transfer, int length)	Requests data from the control endpoint.
void	controlTransferOut(@NotNull UsbControlTransfer transfer, byte[] data)	Executes a control transfer request and optionally sends data.
void	detachStandardDrivers()	Detaches the standard operating-system drivers of this device.
int	getClassCode()	USB device class code (bDeviceClass from device descriptor).
byte @NotNull []	getConfigurationDescriptor()	Gets the configuration descriptor.
byte @NotNull []	getDeviceDescriptor()	Gets the device descriptor.
@NotNull Version	getDeviceVersion()	Device version (as declared by the manufacturer).
@NotNull UsbEndpoint	getEndpoint(UsbDirection direction, int endpointNumber)	Gets the endpoint with the specified number.
@NotNull UsbInterface	getInterface(int interfaceNumber)	Gets the interface with the specified number.
@NotNull @Unmodifiable List<UsbInterface>	getInterfaces()	Gets the interfaces of this device.
String	getManufacturer()	Manufacturer name
String	getProduct()	Product name.
int	getProductId()	USB product ID.
int	getProtocolCode()	USB device protocol (bDeviceProtocol from device descriptor).
String	getSerialNumber()	Serial number
int	getSubclassCode()	USB device subclass code (bDeviceSubClass from device descriptor).
@NotNull Version	getUsbVersion()	USB protocol version supported by this device.
int	getVendorId()	USB vendor ID.
boolean	isOpened()	Indicates if the device is open.
void	open()	Opens the device for communication.
default @NotNull InputStream	openInputStream(int endpointNumber)	Opens a new input stream to receive data from a bulk endpoint.
@NotNull InputStream	openInputStream(int endpointNumber, int bufferSize)	Opens a new input stream to receive data from a bulk endpoint.
default @NotNull OutputStream	openOutputStream(int endpointNumber)	Opens a new output stream to send data to a bulk endpoint.
@NotNull OutputStream	openOutputStream(int endpointNumber, int bufferSize)	Opens a new output stream to send data to a bulk endpoint.
void	releaseInterface(int interfaceNumber)	Releases the specified interface from exclusive use.
void	selectAlternateSetting(int interfaceNumber, int alternateNumber)	Selects the alternate settings for the specified interface.
byte @NotNull []	transferIn(int endpointNumber)	Receives data from this device.
byte @NotNull []	transferIn(int endpointNumber, int timeout)	Receives data from this device.
void	transferOut(int endpointNumber, byte @NotNull [] data)	Sends data to this device.
void	transferOut(int endpointNumber, byte @NotNull [] data, int timeout)	Sends data to this device.
void	transferOut(int endpointNumber, byte @NotNull [] data, int offset, int length, int timeout)	Sends data to this device.

Method Details

getProductId

int getProductId()

USB product ID.

Returns:

product ID

getVendorId

int getVendorId()

USB vendor ID.

Returns:

vendor ID

getProduct

String getProduct()

Product name.

Returns:

product name or null if not provided by the device

getManufacturer

String getManufacturer()

Manufacturer name

Returns:

manufacturer name or null if not provided by the device

getSerialNumber

String getSerialNumber()

Serial number

Even though this is supposed to be a human-readable string, some devices are known to provide binary data.

Returns:

serial number or null if not provided by the device

getClassCode

int getClassCode()

USB device class code (bDeviceClass from device descriptor).

Returns:

class code

getSubclassCode

int getSubclassCode()

USB device subclass code (bDeviceSubClass from device descriptor).

Returns:

subclass code

getProtocolCode

int getProtocolCode()

USB device protocol (bDeviceProtocol from device descriptor).

Returns:

protocol code

getUsbVersion

@NotNull
@NotNull Version getUsbVersion()

USB protocol version supported by this device.

Returns:

version

getDeviceVersion

@NotNull
@NotNull Version getDeviceVersion()

Device version (as declared by the manufacturer).

Returns:

version

detachStandardDrivers

void detachStandardDrivers()

Detaches the standard operating-system drivers of this device.

By detaching the standard drivers, the operating system releases the exclusive access to the device and/or some or all of the device's interfaces. This allows the application to open the device and claim interfaces. It is relevant for device and interfaces implementing standard USB classes, such as HID, CDC and mass storage.

This method should be called before the device is opened. After the device has been closed, attachStandardDrivers() should be called to restore the previous state.

On macOS, all device drivers are immediately detached from the device. To execute it, the application must be run as root. Without root privileges, the method does nothing.

On Linux, this method changes the behavior of claimInterface(int) for this device. The standard drivers will be detached interface by interface when the interface is claimed.

On Windows, this method does nothing. It is not possible to temporarily change the drivers.

attachStandardDrivers

void attachStandardDrivers()

Reattaches the standard operating-system drivers to this device.

By attaching the standard drivers, the operating system claims the device and/or its interfaces if they implement standard USB classes, such as HID, CDC and mass storage. It is used to restore the state before calling detachStandardDrivers().

This method should be called after the device has been closed.

On macOS, the application must be run as root. Without root privileges, the method does nothing.

On Linux, this method changes the behavior of claimInterface(int). Standard drivers will no longer be detached when the interface is claimed. Standard drivers are automatically reattached when the interfaces are released, at the lasted when the device is closed.

On Windows, this method does nothing.

open

void open()

Opens the device for communication.

isOpened

boolean isOpened()

Indicates if the device is open.

Returns:

true if the device is open, false if it is closed.

close

void close()

Closes the device.

getInterfaces

@NotNull
@NotNull @Unmodifiable List<UsbInterface> getInterfaces()

Gets the interfaces of this device.

The returned list is sorted by interface number.

Returns:

a list of USB interfaces

getInterface

@NotNull
@NotNull UsbInterface getInterface(int interfaceNumber)

Gets the interface with the specified number.

Parameters:

interfaceNumber - the interface number

Returns:

the interface

Throws:

UsbException - if the interface does not exist

getEndpoint

@NotNull
@NotNull UsbEndpoint getEndpoint(UsbDirection direction,
 int endpointNumber)

Gets the endpoint with the specified number.

Parameters:

direction - the endpoint direction

endpointNumber - the endpoint number (between 1 and 127)

Returns:

the endpoint

Throws:

UsbException - if the endpoint does not exist

claimInterface

void claimInterface(int interfaceNumber)

Claims the specified interface for exclusive use.

Parameters:

interfaceNumber - the interface number

selectAlternateSetting

void selectAlternateSetting(int interfaceNumber,
 int alternateNumber)

Selects the alternate settings for the specified interface.

The device must be open and the interface must be claimed for exclusive access.

Parameters:

interfaceNumber - interface number

alternateNumber - alternate setting number

releaseInterface

void releaseInterface(int interfaceNumber)

Releases the specified interface from exclusive use.

Parameters:

interfaceNumber - the interface number

controlTransferIn

byte @NotNull [] controlTransferIn(@NotNull
 @NotNull UsbControlTransfer transfer,
 int length)

Requests data from the control endpoint.

This method blocks until the device has responded or an error has occurred.

The control transfer request is sent to endpoint 0. The transfer is expected to have a Data In stage.

Requests with an interface or an endpoint as recipient are expected to have the interface and endpoint number, respectively, in the lower byte of wIndex. This convention is enforced by Windows. The addressed interface or the interface of the addressed endpoint must have been claimed.

Parameters:

transfer - control transfer setup parameters

length - maximum length of expected data

Returns:

received data.

controlTransferOut

void controlTransferOut(@NotNull
 @NotNull UsbControlTransfer transfer,
 byte[] data)

Executes a control transfer request and optionally sends data.

This method blocks until the device has acknowledge the request or an error has occurred.

The control transfer request is sent to endpoint 0. The transfer is expected to either have no data stage or a Data Out stage.

Requests with an interface or an endpoint as recipient are expected to have the interface and endpoint number, respectively, in the lower byte of wIndex. This convention is enforced by Windows. The addressed interface or the interface of the addressed endpoint must have been claimed.

Parameters:

transfer - control transfer setup parameters

data - data to send, or null if the transfer has no data stage.

transferOut

void transferOut(int endpointNumber,
 byte @NotNull [] data)

Sends data to this device.

This method blocks until the data has been sent or an error has occurred.

This method can send data to bulk and interrupt endpoints.

If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

Parameters:

endpointNumber - endpoint number (in the range between 1 and 127)

data - data to send

transferOut

void transferOut(int endpointNumber,
 byte @NotNull [] data,
 int timeout)

Sends data to this device.

This method blocks until the data has been sent, the timeout period has expired or an error has occurred. If the timeout expires, a UsbTimeoutException is thrown.

This method can send data to bulk and interrupt endpoints.

If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

Parameters:

endpointNumber - the endpoint number (in the range between 1 and 127)

data - data to send

timeout - the timeout period, in milliseconds (0 for no timeout)

transferOut

void transferOut(int endpointNumber,
 byte @NotNull [] data,
 int offset,
 int length,
 int timeout)

Sends data to this device.

This method blocks until the data has been sent, the timeout period has expired or an error has occurred. If the timeout expires, a UsbTimeoutException is thrown.

This method can send data to bulk and interrupt endpoints.

If the sent data length is a multiple of the packet size, it is often required to send an additional zero-length packet (ZLP) for the device to actually process the data. This method will not do it automatically.

Parameters:

endpointNumber - the endpoint number (in the range between 1 and 127)

data - buffer containing data to send

offset - offset of the first byte to send

length - number of bytes to send

timeout - the timeout period, in milliseconds (0 for no timeout)

transferIn

byte @NotNull [] transferIn(int endpointNumber)

Receives data from this device.

This method blocks until at least a packet has been received or an error has occurred.

The returned data is the payload of a packet. It can have a length of 0 if the USB device sends zero-length packets to indicate the end of a data unit.

This method can receive data from bulk and interrupt endpoints.

Parameters:

endpointNumber - endpoint number (in the range between 1 and 127, i.e. without the direction bit)

Returns:

received data

transferIn

byte @NotNull [] transferIn(int endpointNumber,
 int timeout)

Receives data from this device.

This method blocks until at least a packet has been received, the timeout period has expired or an error has occurred. If the timeout expired, a UsbTimeoutException is thrown.

The returned data is the payload of a packet. It can have a length of 0 if the USB device sends zero-length packets to indicate the end of a data unit.

This method can receive data from bulk and interrupt endpoints.

Parameters:

endpointNumber - the endpoint number (in the range between 1 and 127, i.e. without the direction bit)

timeout - the timeout period, in milliseconds (0 for no timeout)

Returns:

received data

openOutputStream

@NotNull
@NotNull OutputStream openOutputStream(int endpointNumber,
 int bufferSize)

Opens a new output stream to send data to a bulk endpoint.

All data written to this output stream is sent to the specified bulk endpoint. Buffering and concurrent IO requests are used to achieve a high throughput.

The stream will insert zero-length packets if OutputStream.flush() is called and the last packet size was equal to maximum packet size of the endpoint.

If transferOut(int, byte[]) and a output stream or multiple output streams are used concurrently for the same endpoint, the behavior is unpredictable.

Parameters:

endpointNumber - bulk endpoint number (in the range between 1 and 127)

bufferSize - approximate buffer size (in bytes)

Returns:

the new output stream

openOutputStream

@NotNull
default @NotNull OutputStream openOutputStream(int endpointNumber)

Opens a new output stream to send data to a bulk endpoint.

The buffer is configured with minimal size. In all other aspects, this method works like openOutputStream(int, int).

Parameters:

endpointNumber - bulk endpoint number (in the range between 1 and 127)

Returns:

the new output stream

openInputStream

@NotNull
@NotNull InputStream openInputStream(int endpointNumber,
 int bufferSize)

Opens a new input stream to receive data from a bulk endpoint.

All data received from the specified bulk endpoint can be read using this input stream. Buffering and concurrent IO requests are used to achieve a high throughput.

If the buffers contain data when the stream is closed, this data will be discarded. If transferIn(int) and an input stream or multiple input streams are used concurrently for the same endpoint, the behavior is unpredictable.

Parameters:

endpointNumber - bulk endpoint number (in the range between 1 and 127, i.e. without the direction bit)

bufferSize - approximate buffer size (in bytes)

Returns:

the new input stream

openInputStream

@NotNull
default @NotNull InputStream openInputStream(int endpointNumber)

Opens a new input stream to receive data from a bulk endpoint.

The buffer is configured with minimal size. In all other aspects, this method works like openInputStream(int, int).

Parameters:

endpointNumber - bulk endpoint number (in the range between 1 and 127, i.e. without the direction bit)

Returns:

the new input stream

abortTransfers

void abortTransfers(UsbDirection direction,
 int endpointNumber)

Aborts all transfers on an endpoint.

This operation is not valid on the control endpoint 0.

Parameters:

direction - endpoint direction

endpointNumber - endpoint number (in the range between 1 and 127)

clearHalt

void clearHalt(UsbDirection direction,
 int endpointNumber)

Clears an endpoint's halt condition.

An endpoint is halted (aka stalled) if an error occurs in the communication. Before the communication can resume, the halt condition must be cleared. A halt condition can exist in a single direction only.

Control endpoint 0 will never be halted.

Parameters:

direction - endpoint direction

endpointNumber - endpoint number (in the range between 1 and 127)

getDeviceDescriptor

byte @NotNull [] getDeviceDescriptor()

Gets the device descriptor.

Returns:

the device descriptor (as a byte array)

getConfigurationDescriptor

byte @NotNull [] getConfigurationDescriptor()

Gets the configuration descriptor.

Returns:

the configuration descriptor (as a byte array)