usb.core
Class PortIdentifier

java.lang.Object
  |
  +--usb.core.PortIdentifier

public final class PortIdentifier

extends java.lang.Object

This class provides "stable" string identifiers for USB devices, appropriate for use in operations and troubleshooting. The names identify the path used to access a hub port (and hence implicitly identify any device connected there) on a Host.

If you control the physical cabling of a tree of USB hubs and devices, you control the devices associated with these names. If you don't rewire your USB tree, port identifiers won't change. When you do switch cables, you can figure out the new port ids by using the port numbers on your hubs (or positions, for hubs that don't label their ports).

There are three basic parts in the string representation, currently separated by single dashes (slashes are also reserved):

• Type tag: usb always. Other sorts of physical address might want to fit into a similar identifier framework.
• Bus identifier, such as 03.02:0; these are returned by Bus.getBusId(). If the port identifier only has a type tag and bus id, it's referring to the root hub for that bus.
• Path through hubs, such as 2.4. Each number identifies a port on a hub, using "1" for the first port. "2.4" would mean to use the second port from the root hub, which had better be connected to a hub; then use the fourth port on that hub.

These names are distinct from everyday user-meaningful names. A convenience method is provided to support simple mappings from user assigned names to physical port identifiers, using a Dictionary. Use Host methods to enumerate devices which are physically present, unaffected by all naming policies. The model here is direct driver-level access to devices, with security policies to be established separately.

Note that with USB 2.0 hosts, port ids change depending on what kind of device you plug into the root hub. USB 2.0 devices (high speed, 480 Mbit/s) get switched to a different controller than USB 1.1 devices (slower, at 12 Mbit/s or 1.5 Mbit/s). The identifiers are consistent and still predictable, but you know whether you're talking about a USB 2.0 device or not.

See Also:

Host

Constructor Summary

PortIdentifier(Device dev)
Constructs an identifier for the physical location of this device, scoped to the associated host.

PortIdentifier(java.lang.String path)
Constructs a port identifier using its string form.

Method Summary

Device	getDevice(Host host) Returns the appropriate device from this host, or null if the address describes a port connection that isn't available just now.
static Device	lookup(Host host, java.util.Dictionary dict, java.lang.String name) This maps names to devices, using a dictionary to associate user-meaningful names like ReceiptPrinter or RedCable with port identifier strings like usb-00:0b.0-1.3.
java.lang.String	toString() Provides a printable (and restorable) form of this path, for example usb-00:0b.0-3 identifying the device on the third port on the root hub of the USB controller on PCI slot 0:0b.0.

Methods inherited from class java.lang.Object

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

Constructor Detail

PortIdentifier

public PortIdentifier(Device dev)
               throws java.io.IOException

Constructs an identifier for the physical location of this device, scoped to the associated host.

PortIdentifier

public PortIdentifier(java.lang.String path)

Constructs a port identifier using its string form.

Throws:

java.lang.IllegalArgumentException - if the parameter isn't a valid port identifier string.

Method Detail

getDevice

public Device getDevice(Host host)
                 throws java.io.IOException

Returns the appropriate device from this host, or null if the address describes a port connection that isn't available just now. Keep in mind that it might not actually be the same device which was at that position last time; check at least the device type against what was expected, and other identifiers (serial number?) where they matter.

See Also:

Host.getDevice(java.lang.String)

toString

public java.lang.String toString()

Provides a printable (and restorable) form of this path, for example usb-00:0b.0-3 identifying the device on the third port on the root hub of the USB controller on PCI slot 0:0b.0.

Overrides:

toString in class java.lang.Object

lookup

public static Device lookup(Host host,
                            java.util.Dictionary dict,
                            java.lang.String name)

This maps names to devices, using a dictionary to associate user-meaningful names like ReceiptPrinter or RedCable with port identifier strings like usb-00:0b.0-1.3. If the name isn't found in the dictionary, but is a valid port identifier, then the device at that port is returned.

Parameters:

dict - Maps names to port identifier strings

name - Used as lookup key in the dict.

Returns:

Handle to the device with the port identifier that corresponds to the name; or null if none is present, or if the identifier was faulty, or on getDevice error.