com.ibm.jusb
Class UsbDeviceImp

java.lang.Object
  com.ibm.jusb.UsbDeviceImp

All Implemented Interfaces:

UsbIrpImp.UsbIrpImpListener, java.util.EventListener, UsbDevice

Direct Known Subclasses:

UsbHubImp

public class UsbDeviceImp
extends java.lang.Object
implements UsbDevice, UsbIrpImp.UsbIrpImpListener

UsbDevice platform-independent implementation.

This must be set up before use and/or connection to the topology tree.

• The UsbDeviceDescriptor must be set, either in the constructor or by its setter.
• The UsbDeviceOsImp may optionally be set, either in the constructor or by its setter. If not set, it defaults to a DefaultUsbDeviceOsImp.
• The speed must be set by its setter.
• All UsbConfigurationImps must be added.
• The active config number must be set, if this device is configured.

After setup, this may be connected to the topology tree by using the connect method. If the connect method is not used, there are additional steps:

• Set the parent UsbPortImp by the setter.
• Set this on the UsbPortImp by its setter.

Author:

Dan Streetman

Field Summary

static java.lang.String	CREATE_SHORT_PACKET_EXCEPTION_POLICY_KEY
static java.lang.String	DCP_QUEUE_POLICY_KEY

Constructor Summary

UsbDeviceImp()
Constructor.

UsbDeviceImp(UsbDeviceDescriptor desc)
Constructor.

UsbDeviceImp(UsbDeviceDescriptor desc, UsbDeviceOsImp device)
Constructor.

UsbDeviceImp(UsbDeviceOsImp device)
Constructor.

Method Summary

void	addUsbConfigurationImp(UsbConfigurationImp configuration)
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.
void	connect(UsbHubImp hub, byte portNumber) Connect to the parent UsbHubImp.
boolean	containsUsbConfiguration(byte number) If this UsbDevice contains the specified UsbConfiguration.
UsbControlIrp	createUsbControlIrp(byte bmRequestType, byte bRequest, short wValue, short wIndex) Create a UsbControlIrp.
void	disconnect() Disconnect UsbDeviceImp.
UsbConfiguration	getActiveUsbConfiguration() Get the active UsbConfiguration.
UsbConfigurationImp	getActiveUsbConfigurationImp()
byte	getActiveUsbConfigurationNumber() Get the number of the active UsbConfiguration.
UsbStringDescriptor	getCachedUsbStringDescriptor(byte index) Get a cached UsbStringDescriptor.
java.lang.String	getManufacturerString() Get the manufacturer String.
UsbPort	getParentUsbPort() Get the UsbPort on the parent UsbHub that this device is connected to.
UsbPortImp	getParentUsbPortImp()
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.
UsbConfigurationImp	getUsbConfigurationImp(byte number)
java.util.List	getUsbConfigurations() Get all UsbConfigurations for this device.
UsbDeviceDescriptor	getUsbDeviceDescriptor() Get the device descriptor.
UsbDeviceOsImp	getUsbDeviceOsImp()
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	setActiveUsbConfigurationNumber(byte num) Sets the active configuration index.
void	setCachedUsbStringDescriptor(byte index, UsbStringDescriptor desc) Set a cached UsbStringDescriptor.
void	setParentUsbPortImp(UsbPortImp port)
void	setSpeed(java.lang.Object o) Sets the speed of this device.
void	setUsbDeviceDescriptor(UsbDeviceDescriptor desc)
void	setUsbDeviceOsImp(UsbDeviceOsImp deviceImp)
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.
void	usbIrpImpComplete(UsbIrpImp usbIrpImp) Indicate that a specific UsbIrpImp has completed.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DCP_QUEUE_POLICY_KEY

public static final java.lang.String DCP_QUEUE_POLICY_KEY

See Also:

Constant Field Values

CREATE_SHORT_PACKET_EXCEPTION_POLICY_KEY

public static final java.lang.String CREATE_SHORT_PACKET_EXCEPTION_POLICY_KEY

See Also:

Constant Field Values

Constructor Detail

UsbDeviceImp

public UsbDeviceImp()

Constructor.

UsbDeviceImp

public UsbDeviceImp(UsbDeviceDescriptor desc)

Constructor.

Parameters:

desc - This device's Descriptor.

UsbDeviceImp

public UsbDeviceImp(UsbDeviceOsImp device)

Constructor.

Parameters:

device - The UsbDeviceOsImp.

UsbDeviceImp

public UsbDeviceImp(UsbDeviceDescriptor desc,
                    UsbDeviceOsImp device)

Constructor.

Parameters:

desc - This device's Descriptor.

device - The UsbDeviceOsImp.

Method Detail

getUsbDeviceOsImp

public UsbDeviceOsImp getUsbDeviceOsImp()

Returns:

the associated UsbDeviceImp

setUsbDeviceOsImp

public void setUsbDeviceOsImp(UsbDeviceOsImp deviceImp)

Parameters:

deviceImp - the UsbDeviceOsImp to use

getParentUsbPort

public UsbPort getParentUsbPort()
                         throws UsbDisconnectedException

Description copied from interface: UsbDevice

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

Specified by:

getParentUsbPort in interface UsbDevice

Returns:

The port that this device is attached to

Throws:

UsbDisconnectedException - If this device has been disconnected.

getParentUsbPortImp

public UsbPortImp getParentUsbPortImp()
                               throws UsbDisconnectedException

Returns:

The port that this device is attached to

Throws:

UsbDisconnectedException

setParentUsbPortImp

public void setParentUsbPortImp(UsbPortImp port)

Parameters:

port - The parent port

isUsbHub

public boolean isUsbHub()

Description copied from interface: UsbDevice

If this is a UsbHub.

Specified by:

isUsbHub in interface UsbDevice

Returns:

true if this is a UsbHub and false otherwise

getManufacturerString

public java.lang.String getManufacturerString()
                                       throws UsbException,
                                              java.io.UnsupportedEncodingException,
                                              UsbDisconnectedException

Description copied from interface: UsbDevice

Get the manufacturer String.

This is a convienence method, which uses getString.

Specified by:

getManufacturerString in interface UsbDevice

Returns:

The manufacturer string.

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

public java.lang.String getSerialNumberString()
                                       throws UsbException,
                                              java.io.UnsupportedEncodingException,
                                              UsbDisconnectedException

Description copied from interface: UsbDevice

Get the serial number String.

This is a convienence method, which uses getString.

Specified by:

getSerialNumberString in interface UsbDevice

Returns:

The serial number string.

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

public java.lang.String getProductString()
                                  throws UsbException,
                                         java.io.UnsupportedEncodingException,
                                         UsbDisconnectedException

Description copied from interface: UsbDevice

Get the product String.

This is a convienence method, which uses getString.

Specified by:

getProductString in interface UsbDevice

Returns:

The product string.

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

public java.lang.Object getSpeed()

Description copied from interface: UsbDevice

Get the speed of the device.

The speed will be one of:

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

Specified by:

getSpeed in interface UsbDevice

Returns:

The speed of this device.

getUsbConfigurations

public java.util.List getUsbConfigurations()

Description copied from interface: UsbDevice

Get all UsbConfigurations for this device.

The List is unmodifiable.

Specified by:

getUsbConfigurations in interface UsbDevice

Returns:

the UsbConfiguration objects associated with this UsbDevice

getUsbConfiguration

public UsbConfiguration getUsbConfiguration(byte number)

Description copied from interface: UsbDevice

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.

Specified by:

getUsbConfiguration in interface UsbDevice

Returns:

the UsbConfiguration with the specified number as reported by getConfigurationNumber()

getUsbConfigurationImp

public UsbConfigurationImp getUsbConfigurationImp(byte number)

Returns:

the UsbConfigurationImp with the specified number as reported by getConfigurationNumber()

containsUsbConfiguration

public boolean containsUsbConfiguration(byte number)

Description copied from interface: UsbDevice

If this UsbDevice contains the specified UsbConfiguration.

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

Specified by:

containsUsbConfiguration in interface UsbDevice

Returns:

if the specified UsbConfiguration is contained in this UsbDevice

isConfigured

public boolean isConfigured()

Description copied from interface: UsbDevice

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.

Specified by:

isConfigured in interface UsbDevice

Returns:

if this device is configured

getActiveUsbConfigurationNumber

public byte getActiveUsbConfigurationNumber()

Description copied from interface: UsbDevice

Get the number of the active UsbConfiguration.

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

Specified by:

getActiveUsbConfigurationNumber in interface UsbDevice

Returns:

the active UsbConfiguration number

getActiveUsbConfiguration

public UsbConfiguration getActiveUsbConfiguration()

Description copied from interface: UsbDevice

Get the active UsbConfiguration.

If this device is Not Configured, this returns null.

Specified by:

getActiveUsbConfiguration in interface UsbDevice

Returns:

the active UsbConfiguration object

getActiveUsbConfigurationImp

public UsbConfigurationImp getActiveUsbConfigurationImp()

Returns:

the active UsbConfigurationImp object

getUsbDeviceDescriptor

public UsbDeviceDescriptor getUsbDeviceDescriptor()

Description copied from interface: UsbDevice

Get the device descriptor.

The descriptor may be cached.

Specified by:

getUsbDeviceDescriptor in interface UsbDevice

Returns:

the device descriptor for this device

getUsbStringDescriptor

public UsbStringDescriptor getUsbStringDescriptor(byte index)
                                           throws UsbException,
                                                  UsbDisconnectedException

Description copied from interface: UsbDevice

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.

Specified by:

getUsbStringDescriptor in interface UsbDevice

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

public java.lang.String getString(byte index)
                           throws UsbException,
                                  java.io.UnsupportedEncodingException,
                                  UsbDisconnectedException

Description copied from interface: UsbDevice

Get the String from the specified string descriptor.

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

Specified by:

getString in interface UsbDevice

Parameters:

index - The index of the string to get.

Returns:

the String from the specified STringDescriptor

Throws:

UsbException - if an error occurrs while getting the UsbStringDescriptor.

java.io.UnsupportedEncodingException - If the string encoding is not supported.

UsbDisconnectedException - If the device has been disconnected.

createUsbControlIrp

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

Create a UsbControlIrp.

Specified by:

createUsbControlIrp in interface UsbDevice

Parameters:

bmRequestType - The bmRequestType.

bRequest - The bRequest.

wValue - The wValue.

wIndex - The wIndex.

Returns:

A UsbControlIrp ready for use.

usbIrpImpComplete

public void usbIrpImpComplete(UsbIrpImp usbIrpImp)

Indicate that a specific UsbIrpImp has completed.

Specified by:

usbIrpImpComplete in interface UsbIrpImp.UsbIrpImpListener

Parameters:

usbIrpImp - The UsbIrpImp that completed.

addUsbDeviceListener

public void addUsbDeviceListener(UsbDeviceListener listener)

Description copied from interface: UsbDevice

Add a UsbDeviceListener to this UsbDevice.

Specified by:

addUsbDeviceListener in interface UsbDevice

Parameters:

listener - The listener to add

removeUsbDeviceListener

public void removeUsbDeviceListener(UsbDeviceListener listener)

Description copied from interface: UsbDevice

Remove a UsbDeviceListener from this UsbDevice.

Specified by:

removeUsbDeviceListener in interface UsbDevice

Parameters:

listener - The listener to remove

setUsbDeviceDescriptor

public void setUsbDeviceDescriptor(UsbDeviceDescriptor desc)

Parameters:

desc - The new device descriptor

getCachedUsbStringDescriptor

public UsbStringDescriptor getCachedUsbStringDescriptor(byte index)

Get a cached UsbStringDescriptor.

Parameters:

index - The index of the UsbStringDescriptor.

Returns:

The specified UsbStringDescriptor, or null.

setCachedUsbStringDescriptor

public void setCachedUsbStringDescriptor(byte index,
                                         UsbStringDescriptor desc)

Set a cached UsbStringDescriptor.

Parameters:

index - The index.

desc - The UsbStringDescriptor.

setSpeed

public void setSpeed(java.lang.Object o)

Sets the speed of this device.

Parameters:

o - The speed.

Throws:

java.lang.IllegalArgumentException - If the speed is not one of the defined speeds.

setActiveUsbConfigurationNumber

public void setActiveUsbConfigurationNumber(byte num)

Sets the active configuration index.

Since this may be called before the associated configuration is actually added, this does not check if the specified configuration index actually associates to a valid configuration; the caller must ensure that.

Parameters:

num - the active configuration number (0 if device has been unconfigured)

addUsbConfigurationImp

public void addUsbConfigurationImp(UsbConfigurationImp configuration)

Parameters:

configuration - The configuration to add

connect

public void connect(UsbHubImp hub,
                    byte portNumber)
             throws UsbException

Connect to the parent UsbHubImp.

Parameters:

hub - The parent.

portNumber - The port on the parent this is connected to.

Throws:

UsbException

disconnect

public void disconnect()

Disconnect UsbDeviceImp.

Only call this if the device was connected to the topology tree; i.e. the UsbPortImp has been set. This will fire usbDeviceDetached events to all listeners.

This method must be called when a device is disconnected.

syncSubmit

public void syncSubmit(UsbControlIrp irp)
                throws UsbException,
                       java.lang.IllegalArgumentException,
                       UsbDisconnectedException

Submit a UsbControlIrp synchronously to the Default Control Pipe.

Specified by:

syncSubmit in interface UsbDevice

Parameters:

irp - The UsbControlIrp.

Throws:

UsbException - If an error occurrs.

java.lang.IllegalArgumentException - If the UsbControlIrp is invalid.

UsbDisconnectedException - If the device has been disconnected.

asyncSubmit

public void asyncSubmit(UsbControlIrp irp)
                 throws UsbException,
                        java.lang.IllegalArgumentException,
                        UsbDisconnectedException

Submit a UsbControlIrp asynchronously to the Default Control Pipe.

Specified by:

asyncSubmit in interface UsbDevice

Parameters:

irp - The UsbControlIrp.

Throws:

UsbException - If an error occurrs.

java.lang.IllegalArgumentException - If the UsbControlIrp is invalid.

UsbDisconnectedException - If the device has been disconnected.

syncSubmit

public 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.

Specified by:

syncSubmit in interface UsbDevice

Parameters:

list - The List of UsbControlIrps.

Throws:

UsbException - If an error occurrs.

java.lang.IllegalArgumentException - If one of the UsbControlIrps is invalid.

UsbDisconnectedException - If the device has been disconnected.

asyncSubmit

public 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.

Specified by:

asyncSubmit in interface UsbDevice

Parameters:

list - The List of UsbControlIrps.

Throws:

UsbException - If an error occurrs.

java.lang.IllegalArgumentException - If one of the UsbControlIrps is invalid.

UsbDisconnectedException - If the device has been disconnected.