javax.usb
Interface UsbDevice

All Known Subinterfaces:
UsbHub
All Known Implementing Classes:
UsbDeviceImp, UsbHubImp, UsbUtil.SynchronizedUsbDevice, VirtualRootUsbHubImp

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
 void addUsbDeviceListener(UsbDeviceListener listener)
          Add a UsbDeviceListener to this UsbDevice.
 void asyncSubmit(java.util.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.
 java.lang.String getManufacturerString()
          Get the manufacturer String.
 UsbPort getParentUsbPort()
          Get the UsbPort on the parent UsbHub that this device is connected to.
 java.lang.String getProductString()
          Get the product String.
 java.lang.String getSerialNumberString()
          Get the serial number String.
 java.lang.Object getSpeed()
          Get the speed of the device.
 java.lang.String getString(byte index)
          Get the String from the specified string descriptor.
 UsbConfiguration getUsbConfiguration(byte number)
          Get the specified UsbConfiguration.
 java.util.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(java.util.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

java.lang.String getManufacturerString()
                                       throws UsbException,
                                              java.io.UnsupportedEncodingException,
                                              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.
java.io.UnsupportedEncodingException - If the string encoding is not supported.
UsbDisconnectedException - If this device has been disconnected.

getSerialNumberString

java.lang.String getSerialNumberString()
                                       throws UsbException,
                                              java.io.UnsupportedEncodingException,
                                              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.
java.io.UnsupportedEncodingException - If the string encoding is not supported.
UsbDisconnectedException - If this device has been disconnected.

getProductString

java.lang.String getProductString()
                                  throws UsbException,
                                         java.io.UnsupportedEncodingException,
                                         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.
java.io.UnsupportedEncodingException - If the string encoding is not supported.
UsbDisconnectedException - If this device has been disconnected.

getSpeed

java.lang.Object getSpeed()
Get the speed of the device.

The speed will be one of:

Returns:
The speed of this device.

getUsbConfigurations

java.util.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

java.lang.String getString(byte index)
                           throws UsbException,
                                  java.io.UnsupportedEncodingException,
                                  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.
java.io.UnsupportedEncodingException - If the string encoding is not supported.
UsbDisconnectedException - If this device has been disconnected.

syncSubmit

void syncSubmit(UsbControlIrp irp)
                throws UsbException,
                       java.lang.IllegalArgumentException,
                       UsbDisconnectedException
Submit a UsbControlIrp synchronously to the Default Control Pipe.

Parameters:
irp - The UsbControlIrp.
Throws:
UsbException - If an error occurrs.
java.lang.IllegalArgumentException - If the UsbControlIrp is not valid.
UsbDisconnectedException - If this device has been disconnected.

asyncSubmit

void asyncSubmit(UsbControlIrp irp)
                 throws UsbException,
                        java.lang.IllegalArgumentException,
                        UsbDisconnectedException
Submit a UsbControlIrp asynchronously to the Default Control Pipe.

Parameters:
irp - The UsbControlIrp.
Throws:
UsbException - If an error occurrs.
java.lang.IllegalArgumentException - If the UsbControlIrp is not valid.
UsbDisconnectedException - If this device has been disconnected.

syncSubmit

void syncSubmit(java.util.List list)
                throws UsbException,
                       java.lang.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.
java.lang.IllegalArgumentException - If the List contains non-UsbControlIrp objects or those UsbIrp(s) are invalid.
UsbDisconnectedException - If this device has been disconnected.

asyncSubmit

void asyncSubmit(java.util.List list)
                 throws UsbException,
                        java.lang.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.
java.lang.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.