javax.usb

Interface UsbDevice

All Known Subinterfaces:

UsbHub

All Known Implementing Classes:

UsbDeviceImp, UsbHubImp, UsbUtil.SynchronizedUsbDevice, VirtualRootUsbHubImp, WindowsHubOsImp

public interface UsbDevice

Interface for a USB device.

The submission methods contained in this UsbDevice operate on the device's Default Control Pipe. The device does not have to be configured to use the Default Control Pipe.

The implementation is not required to be Thread-safe. If a Thread-safe UsbDevice is required, use a synchronizedUsbDevice.

Author:

Dan Streetman, E. Michael Maximilien

Method Summary

Methods

Modifier and Type	Method and Description
void	addUsbDeviceListener(UsbDeviceListener listener) Add a UsbDeviceListener to this UsbDevice.
void	asyncSubmit(List list) Submit a List of UsbControlIrps asynchronously to the Default Control Pipe.
void	asyncSubmit(UsbControlIrp irp) Submit a UsbControlIrp asynchronously to the Default Control Pipe.
boolean	containsUsbConfiguration(byte number) If this UsbDevice contains the specified UsbConfiguration.
UsbControlIrp	createUsbControlIrp(byte bmRequestType, byte bRequest, short wValue, short wIndex) Create a UsbControlIrp.
UsbConfiguration	getActiveUsbConfiguration() Get the active UsbConfiguration.
byte	getActiveUsbConfigurationNumber() Get the number of the active UsbConfiguration.
String	getManufacturerString() Get the manufacturer String.
UsbPort	getParentUsbPort() Get the UsbPort on the parent UsbHub that this device is connected to.
String	getProductString() Get the product String.
String	getSerialNumberString() Get the serial number String.
Object	getSpeed() Get the speed of the device.
String	getString(byte index) Get the String from the specified string descriptor.
UsbConfiguration	getUsbConfiguration(byte number) Get the specified UsbConfiguration.
List	getUsbConfigurations() Get all UsbConfigurations for this device.
UsbDeviceDescriptor	getUsbDeviceDescriptor() Get the device descriptor.
UsbStringDescriptor	getUsbStringDescriptor(byte index) Get the specified string descriptor.
boolean	isConfigured() If this UsbDevice is configured.
boolean	isUsbHub() If this is a UsbHub.
void	removeUsbDeviceListener(UsbDeviceListener listener) Remove a UsbDeviceListener from this UsbDevice.
void	syncSubmit(List list) Submit a List of UsbControlIrps synchronously to the Default Control Pipe.
void	syncSubmit(UsbControlIrp irp) Submit a UsbControlIrp synchronously to the Default Control Pipe.

Method Detail

getParentUsbPort

UsbPort getParentUsbPort()
                         throws UsbDisconnectedException

Get the UsbPort on the parent UsbHub that this device is connected to.

Returns:

The port on the parent UsbHub that this is attached to.

Throws:

UsbDisconnectedException - If this device has been disconnected.

isUsbHub

boolean isUsbHub()

If this is a UsbHub.

Returns:

true if this is a UsbHub.

getManufacturerString

String getManufacturerString()
                             throws UsbException,
                                    UsbEncodingException,
                                    UsbDisconnectedException

Get the manufacturer String.

This is a convienence method, which uses getString.

Returns:

The manufacturer String, or null.

Throws:

UsbException - If there was an error getting the UsbStringDescriptor.

UsbEncodingException - If the string encoding is not supported.

UsbDisconnectedException - If this device has been disconnected.

getSerialNumberString

String getSerialNumberString()
                             throws UsbException,
                                    UsbEncodingException,
                                    UsbDisconnectedException

Get the serial number String.

This is a convienence method, which uses getString.

Returns:

The serial number String, or null.

Throws:

UsbException - If there was an error getting the UsbStringDescriptor.

UsbEncodingException - If the string encoding is not supported.

UsbDisconnectedException - If this device has been disconnected.

getProductString

String getProductString()
                        throws UsbException,
                               UsbEncodingException,
                               UsbDisconnectedException

Get the product String.

This is a convienence method, which uses getString.

Returns:

The product String, or null.

Throws:

UsbException - If there was an error getting the UsbStringDescriptor.

UsbEncodingException - If the string encoding is not supported.

UsbDisconnectedException - If this device has been disconnected.

getSpeed

Object getSpeed()

Get the speed of the device.

The speed will be one of:

• UsbConst.DEVICE_SPEED_UNKNOWN
• UsbConst.DEVICE_SPEED_LOW
• UsbConst.DEVICE_SPEED_FULL

Returns:

The speed of this device.

getUsbConfigurations

List getUsbConfigurations()

Get all UsbConfigurations for this device.

The List is unmodifiable.

Returns:

All UsbConfigurations for this device.

getUsbConfiguration

UsbConfiguration getUsbConfiguration(byte number)

Get the specified UsbConfiguration.

If the specified UsbConfiguration does not exist, null is returned. Config number 0 is reserved for the Not Configured state (see the USB 1.1 specification section 9.4.2). Obviously, no UsbConfiguration exists for the Not Configured state.

Returns:

The specified UsbConfiguration, or null.

containsUsbConfiguration

boolean containsUsbConfiguration(byte number)

If this UsbDevice contains the specified UsbConfiguration.

This will return false for zero (the Not Configured state).

Returns:

If the specified UsbConfiguration is contained in this UsbDevice.

getActiveUsbConfigurationNumber

byte getActiveUsbConfigurationNumber()

Get the number of the active UsbConfiguration.

If the device is in a Not Configured state, this will return zero.

Returns:

The active config number.

getActiveUsbConfiguration

UsbConfiguration getActiveUsbConfiguration()

Get the active UsbConfiguration.

If this device is Not Configured, this returns null.

Returns:

The active UsbConfiguration, or null.

isConfigured

boolean isConfigured()

If this UsbDevice is configured.

This returns true if the device is in the configured state as shown in the USB 1.1 specification table 9.1.

Returns:

If this is in the Configured state.

getUsbDeviceDescriptor

UsbDeviceDescriptor getUsbDeviceDescriptor()

Get the device descriptor.

The descriptor may be cached.

Returns:

The device descriptor.

getUsbStringDescriptor

UsbStringDescriptor getUsbStringDescriptor(byte index)
                                           throws UsbException,
                                                  UsbDisconnectedException

Get the specified string descriptor.

This is a convienence method. The UsbStringDescriptor may be cached. If the device does not support strings or does not define the specified string descriptor, this returns null.

Parameters:

index - The index of the string descriptor to get.

Returns:

The specified string descriptor.

Throws:

UsbException - If an error occurred while getting the string descriptor.

UsbDisconnectedException - If this device has been disconnected.

getString

String getString(byte index)
                 throws UsbException,
                        UsbEncodingException,
                        UsbDisconnectedException

Get the String from the specified string descriptor.

This is a convienence method, which uses getUsbStringDescriptor(). getString().

Parameters:

index - The index of the string to get.

Returns:

The specified String.

Throws:

UsbException - If an error occurred while getting the String.

UsbEncodingException - If the string encoding is not supported.

UsbDisconnectedException - If this device has been disconnected.

syncSubmit

void syncSubmit(UsbControlIrp irp)
                throws UsbException,
                       IllegalArgumentException,
                       UsbDisconnectedException

Submit a UsbControlIrp synchronously to the Default Control Pipe.

Parameters:

irp - The UsbControlIrp.

Throws:

UsbException - If an error occurrs.

IllegalArgumentException - If the UsbControlIrp is not valid.

UsbDisconnectedException - If this device has been disconnected.

asyncSubmit

void asyncSubmit(UsbControlIrp irp)
                 throws UsbException,
                        IllegalArgumentException,
                        UsbDisconnectedException

Submit a UsbControlIrp asynchronously to the Default Control Pipe.

Parameters:

irp - The UsbControlIrp.

Throws:

UsbException - If an error occurrs.

IllegalArgumentException - If the UsbControlIrp is not valid.

UsbDisconnectedException - If this device has been disconnected.

syncSubmit

void syncSubmit(List list)
                throws UsbException,
                       IllegalArgumentException,
                       UsbDisconnectedException

Submit a List of UsbControlIrps synchronously to the Default Control Pipe.

All UsbControlIrps are guaranteed to be atomically (with respect to other clients of this API) submitted to the Default Control Pipe. Atomicity on a native level is implementation-dependent.

Parameters:

list - The List of UsbControlIrps.

Throws:

UsbException - If an error occurrs.

IllegalArgumentException - If the List contains non-UsbControlIrp objects or those UsbIrp(s) are invalid.

UsbDisconnectedException - If this device has been disconnected.

asyncSubmit

void asyncSubmit(List list)
                 throws UsbException,
                        IllegalArgumentException,
                        UsbDisconnectedException

Submit a List of UsbControlIrps asynchronously to the Default Control Pipe.

All UsbControlIrps are guaranteed to be atomically (with respect to other clients of this API) submitted to the Default Control Pipe. Atomicity on a native level is implementation-dependent.

Parameters:

list - The List of UsbControlIrps.

Throws:

UsbException - If an error occurrs.

IllegalArgumentException - If the List contains non-UsbControlIrp objects or those UsbIrp(s) are invalid.

UsbDisconnectedException - If this device has been disconnected.

createUsbControlIrp

UsbControlIrp createUsbControlIrp(byte bmRequestType,
                                byte bRequest,
                                short wValue,
                                short wIndex)

Create a UsbControlIrp.

This creates a UsbControlIrp that may be optimized for use on this UsbDevice. Using this UsbIrp instead of a DefaultUsbControlIrp may increase performance or decrease memory requirements.

The UsbDevice cannot require this UsbControlIrp to be used, all submit methods must accept any UsbControlIrp implementation.

Parameters:

bmRequestType - The bmRequestType.

bRequest - The bRequest.

wValue - The wValue.

wIndex - The wIndex.

Returns:

A UsbControlIrp ready for use.

addUsbDeviceListener

void addUsbDeviceListener(UsbDeviceListener listener)

Add a UsbDeviceListener to this UsbDevice.

Parameters:

listener - The UsbDeviceListener to add.

removeUsbDeviceListener

void removeUsbDeviceListener(UsbDeviceListener listener)

Remove a UsbDeviceListener from this UsbDevice.

Parameters:

listener - The listener to remove.