com.mcreations.usb.windows
Class WindowsUsbServices

java.lang.Object
  com.ibm.jusb.os.AbstractUsbServices
      com.mcreations.usb.windows.WindowsUsbServices

All Implemented Interfaces:

UsbServices

public class WindowsUsbServices
extends AbstractUsbServices
implements UsbServices

UsbServices implementation for Windows platform.

Author:

Dan Streetman, Kambiz Darabi

Field Summary

static String	COULD_NOT_ACCESS_USB_SUBSYSTEM
static int	MAX_FIRST_UPDATE_DELAY
static int	TOPOLOGY_UPDATE_DELAY
static String	TOPOLOGY_UPDATE_DELAY_KEY
static int	TOPOLOGY_UPDATE_NEW_DEVICE_DELAY
static String	TOPOLOGY_UPDATE_NEW_DEVICE_DELAY_KEY
static boolean	TOPOLOGY_UPDATE_USE_POLLING
static String	TOPOLOGY_UPDATE_USE_POLLING_KEY
protected int	topologyUpdateDelay
protected int	topologyUpdateNewDeviceDelay
protected boolean	topologyUpdateUsePolling
static String	TRACE_DEFAULT_KEY
static String	TRACE_HOTPLUG_KEY
static String	TRACE_LEVEL_KEY
static String	TRACE_URB_KEY
static String	TRACE_XFER_KEY
static String	TRACING_KEY
static String	WINDOWS_API_VERSION
static String	WINDOWS_IMP_DESCRIPTION
static String	WINDOWS_IMP_VERSION

Fields inherited from class com.ibm.jusb.os.AbstractUsbServices

listenerImp

Constructor Summary

WindowsUsbServices()

Method Summary

String	getApiVersion() Get the (minimum) version number of the javax.usb API that this UsbServices implements.
String	getImpDescription() Get a description of this UsbServices implementation.
String	getImpVersion() Get the version number of the UsbServices implementation.
UsbHub	getRootUsbHub() Get the virtual UsbHub to which all physical Host Controller UsbHubs are attached.
protected boolean	isUsbDevicesEqual(UsbDeviceImp dev1, UsbDeviceImp dev2) Return if the specified devices appear to be equal.

Methods inherited from class com.ibm.jusb.os.AbstractUsbServices

addUsbServicesListener, getRootUsbHubImp, removeUsbServicesListener

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.usb.UsbServices

addUsbServicesListener, removeUsbServicesListener

Field Detail

topologyUpdateUsePolling

protected boolean topologyUpdateUsePolling

topologyUpdateDelay

protected int topologyUpdateDelay

topologyUpdateNewDeviceDelay

protected int topologyUpdateNewDeviceDelay

COULD_NOT_ACCESS_USB_SUBSYSTEM

public static final String COULD_NOT_ACCESS_USB_SUBSYSTEM

See Also:

Constant Field Values

MAX_FIRST_UPDATE_DELAY

public static final int MAX_FIRST_UPDATE_DELAY

See Also:

Constant Field Values

TOPOLOGY_UPDATE_DELAY

public static final int TOPOLOGY_UPDATE_DELAY

See Also:

Constant Field Values

TOPOLOGY_UPDATE_DELAY_KEY

public static final String TOPOLOGY_UPDATE_DELAY_KEY

See Also:

Constant Field Values

TOPOLOGY_UPDATE_NEW_DEVICE_DELAY

public static final int TOPOLOGY_UPDATE_NEW_DEVICE_DELAY

See Also:

Constant Field Values

TOPOLOGY_UPDATE_NEW_DEVICE_DELAY_KEY

public static final String TOPOLOGY_UPDATE_NEW_DEVICE_DELAY_KEY

See Also:

Constant Field Values

TOPOLOGY_UPDATE_USE_POLLING

public static final boolean TOPOLOGY_UPDATE_USE_POLLING

See Also:

Constant Field Values

TOPOLOGY_UPDATE_USE_POLLING_KEY

public static final String TOPOLOGY_UPDATE_USE_POLLING_KEY

See Also:

Constant Field Values

TRACING_KEY

public static final String TRACING_KEY

See Also:

Constant Field Values

TRACE_LEVEL_KEY

public static final String TRACE_LEVEL_KEY

See Also:

Constant Field Values

TRACE_DEFAULT_KEY

public static final String TRACE_DEFAULT_KEY

See Also:

Constant Field Values

TRACE_HOTPLUG_KEY

public static final String TRACE_HOTPLUG_KEY

See Also:

Constant Field Values

TRACE_XFER_KEY

public static final String TRACE_XFER_KEY

See Also:

Constant Field Values

TRACE_URB_KEY

public static final String TRACE_URB_KEY

See Also:

Constant Field Values

WINDOWS_API_VERSION

public static final String WINDOWS_API_VERSION

See Also:

Constant Field Values

WINDOWS_IMP_VERSION

public static final String WINDOWS_IMP_VERSION

See Also:

Constant Field Values

WINDOWS_IMP_DESCRIPTION

public static final String WINDOWS_IMP_DESCRIPTION

See Also:

Constant Field Values

Constructor Detail

WindowsUsbServices

public WindowsUsbServices()
                   throws UsbException

Throws:

UsbException

Method Detail

getRootUsbHub

public UsbHub getRootUsbHub()
                     throws UsbException

Description copied from interface: UsbServices

Get the virtual UsbHub to which all physical Host Controller UsbHubs are attached.

The USB root hub is a special hub at the top of the topology tree. The USB 1.1 specification mentions root hubs in sec 5.2.3, where it states that 'the host includes an embedded hub called the root hub'. The implication of this seems to be that the (hardware) Host Controller device is the root hub, since the Host Controller device 'emulates' a USB hub, and in systems with only one physical Host Controller device, its emulated hub is in effect the root hub. However when multiple Host Controller devices are considered, there are two (2) options that were considered:

1. Have an array or list of the available topology trees, with each physical Host Controller's emulated root hub as the root UsbHub of that particular topology tree. This configuration could be compared to the MS-DOS/Windows decision to assign drive letters to different physical drives (partitions).
2. Have a 'virtual' root hub, which is completely virtual (not associated with any physical device) and is created and managed solely by the javax.usb implementation. This configuration could be compared to the UNIX descision to put all physical drives on 'mount points' under a single 'root' (/) directory filesystem.

The first configuration results in having to maintain a list of different and completely unconnected device topologies. This means a search for a particular device must be performed on all the device topologies. Since a UsbHub already has a list of UsbDevices, and a UsbHub is a UsbDevice, introducing a new, different list is not a desirable action, since it introduces extra unnecessary steps in performing actions, like searching.

As an example, a recursive search for a certain device in the first configuration involves getting the first root UsbHub, getting all its attached UsbDevices, and checking each device; any of those devices which are UsbHubs can be also searched recursively. Then, the entire operation must be performed on the next root UsbHub, and this is repeated for all the root UsbHubs in the array/list. In the second configuration, the virtual root UsbHub is recursively searched in a single operation.

The second configuration is what is used in this API. The implementation is responsible for creating a single root UsbHub which is completely virtual (and available through the UsbServices object). Every UsbHub attached to this virtual root UsbHub corresponds to a physical Host Controller's emulated hub. I.e., the first level of UsbDevices under the virtual root UsbHub are all UsbHubs corresponding to a particular Host Controller on the system. Note that since the root UsbHub is a virtual hub, the number of ports is not posible to specify; so all that is guaranteed is the number of ports is at least equal to the number of UsbHubs attached to the root UsbHub. The number of ports on the virtual root UsbHub may change if UsbHubs are attached or detached (e.g., if a Host Controller is physically hot-removed from the system or hot-plugged, or if its driver is dynamically loaded, or for any other reason a top-level Host Controller's hub is attached/detached). This API specification suggests that the number of ports for the root UsbHub equal the number of directly attached UsbHubs.

Specified by:

getRootUsbHub in interface UsbServices

Overrides:

getRootUsbHub in class AbstractUsbServices

Returns:

The virtual USB root hub

Throws:

UsbException - If there is an error accessing javax.usb.

getApiVersion

public String getApiVersion()

Description copied from interface: UsbServices

Get the (minimum) version number of the javax.usb API that this UsbServices implements.

This should correspond to the output of (some version of) the javax.usb.Version.

Specified by:

getApiVersion in interface UsbServices

Returns:

The minimum API version this supports.

getImpVersion

public String getImpVersion()

Description copied from interface: UsbServices

Get the version number of the UsbServices implementation.

The format should be ..

Specified by:

getImpVersion in interface UsbServices

Returns:

The version number of this implementation.

getImpDescription

public String getImpDescription()

Description copied from interface: UsbServices

Get a description of this UsbServices implementation.

The format is implementation-specific, but should include at least the following:

• The company or individual author(s).
• The license, or license header.
• Contact information.
• The minimum or expected version of Java.
• The Operating System(s) supported (usually one per implementation).
• Any other useful information.

Specified by:

getImpDescription in interface UsbServices

Returns:

Get a description of this UsbServices implementation.

isUsbDevicesEqual

protected boolean isUsbDevicesEqual(UsbDeviceImp dev1,
                                    UsbDeviceImp dev2)

Return if the specified devices appear to be equal.

If either of the device's descriptors are null, this returns false.

Parameters:

dev1 - The first device.

dev2 - The second device.

Returns:

If the devices appear to be equal.