usb.windows
Class DeviceImpl

java.lang.Object
  |
  +--usb.core.Device
        |
        +--usb.windows.DeviceImpl

All Implemented Interfaces:

DeviceSPI, java.io.Serializable

public final class DeviceImpl

extends Device

implements DeviceSPI

Provides access to a USB device. To use a device, first make sure that you can use the selected configuration. (Don't use the change-configuration functionality yet.)

See Also:

Serialized Form

Fields inherited from class usb.core.Device

DEVICE_REMOTE_WAKEUP, DEVICE_SELFPOWERED

Method Summary

void	claimInterface(int ifno) Claims this interface, so that no other driver can.
int	clearHalt(byte ep) Clears halt/stall status on an endpoint.
int	cyclePort()
boolean	cyclePortWorks()
protected void	finalize() Releases any unreleased system resources.
Device	getChild(int port) Returns children of a hub device.
java.lang.String	getClaimer(int ifno) Returns a system-specific string providing information about the driver claiming this interface, or null.
byte[]	getConfigBuf(int n) Returns a buffer holding the entire set of configuration descriptors for the specified configuration.
Configuration	getConfiguration() Returns the current device configuration's descriptor.
Configuration	getConfiguration(int index) Returns the specified configuration.
DeviceDescriptor	getDeviceDescriptor() Returns the device descriptor.
Device	getHub() Returns the hub to which this device is connected, or null if this device is disconnected or is the root hub for its bus.
int	getHubPortNum() Returns the number of the hub port to which this device is connected.
int[]	getLanguages()
int	getNumPorts() Returns the number of ports in this hub; or zero.
java.lang.String	getPath() Returns the filesystem name for this file.
java.lang.String	getSpeed() Returns the speed of the connection the device is using.
java.lang.String	getString(int id) Returns the string indexed with the specified ID in the default language, or null if there is no such string.
java.lang.String	getString(int id, int language) Implementation of Device.getString which can cache strings in the device's default language.
int	readBulk(int ep, byte[] buf, int off, int length)
byte[]	readBulk(int ep, int length) Assigns the specified configuration as current.
byte[]	readControl(byte type, byte request, short value, short index, short length) Issues a control IN request with an optional data READ phase.
byte[]	readIntr(int ep, int length) Reads a specified number of bytes from a INTERRUPT IN endpoint.
void	releaseInterface(int ifno) Releases an interface claim.
void	setConfiguration(int index) Deprecated. Consider this dangerous.
void	setInterface(int ifno, int alt) Assigns an interface to an alternate setting.
java.lang.String	toString()
void	writeBulk(int ep, byte[] buf) Writes a specified number of bytes to a BULK OUT endpoint.
void	writeBulk(int ep, byte[] buf, int off, int length)
void	writeControl(byte type, byte request, short value, short index, byte[] buf) Issues a control OUT request with an optional data WRITE phase.
void	writeIntr(int ep, byte[] buf) Writes a specified number of bytes to a INTERRUPT OUT endpoint.

Methods inherited from class usb.core.Device

control, getAddress, getBus, getPortIdentifier, getSPI

Methods inherited from class java.lang.Object

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

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

finalize

protected void finalize()
                 throws usb.windows.USBException

Releases any unreleased system resources.

Overrides:

finalize in class java.lang.Object

getHub

public Device getHub()

Description copied from class: Device

Returns the hub to which this device is connected, or null if this device is disconnected or is the root hub for its bus.

Overrides:

getHub in class Device

getHubPortNum

public int getHubPortNum()

Description copied from class: Device

Returns the number of the hub port to which this device is connected.

Overrides:

getHubPortNum in class Device

getSpeed

public java.lang.String getSpeed()

Description copied from class: Device

Returns the speed of the connection the device is using. The return value is either "high", "full", or "low"; or else null. Null is used for root hubs, or indicates some error prevented determining the speed being used for the device's hub port.

Overrides:

getSpeed in class Device

getNumPorts

public int getNumPorts()

Description copied from class: Device

Returns the number of ports in this hub; or zero. This should return the same value as Hub.getNumPorts().

Overrides:

getNumPorts in class Device

getDeviceDescriptor

public DeviceDescriptor getDeviceDescriptor()

Description copied from class: Device

Returns the device descriptor.

Overrides:

getDeviceDescriptor in class Device

getConfiguration

public Configuration getConfiguration()
                               throws java.io.IOException

Description copied from class: Device

Returns the current device configuration's descriptor.

Overrides:

getConfiguration in class Device

getChild

public Device getChild(int port)

Description copied from interface: DeviceSPI

Returns children of a hub device.

Specified by:

getChild in interface DeviceSPI

Overrides:

getChild in class Device

Following copied from interface: usb.core.DeviceSPI

Parameters:

port - Number of the hub port of interest, from one to the Hub.getNumPorts().

Returns:

Device connected to that port, or null if there is no such device. Always returns null for devices that are not hubs.

getPath

public java.lang.String getPath()

Returns the filesystem name for this file.

getString

public java.lang.String getString(int id)
                           throws java.io.IOException

Returns the string indexed with the specified ID in the default language, or null if there is no such string. Use of cached values is preferred.

The default language is the one that is being cached. If this is the first request, then the language of the default locale is used if it is supported, else the first supported language is chosen as a fallback.

getString

public java.lang.String getString(int id,
                                  int language)
                           throws java.io.IOException

Implementation of Device.getString which can cache strings in the device's default language.

Overrides:

getString in class Device

getLanguages

public int[] getLanguages()
                   throws java.io.IOException

getConfiguration

public Configuration getConfiguration(int index)
                               throws java.io.IOException

Returns the specified configuration. This can need to accumulate device-specific smarts.

Overrides:

getConfiguration in class Device

setConfiguration

public void setConfiguration(int index)
                      throws usb.windows.USBException

Deprecated. Consider this dangerous.

Assigns a device configuration, which must be one of those supported by this device. The OS assigned one already.

readControl

public byte[] readControl(byte type,
                          byte request,
                          short value,
                          short index,
                          short length)
                   throws java.io.IOException

Description copied from interface: DeviceSPI

Issues a control IN request with an optional data READ phase. The request goes to the default control endpoint (CONTROL IN zero). No interface needs to be claimed in order to issue control requests.

Most of the parameters here are used to build the SETUP packet for the control request, which is always written to the device. Note an OUT control request with only a setup packet is different from the IN request with the same bits in the setup packet data; it goes to a different endpoint.

Specified by:

readControl in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

type - Masked together using three constants from ControlMessage: DIR_TO_HOST, a TYPE_*, and a RECIP_*.

request - bRequest field, either standard (from table 9-3 in the USB 2.0 specification) for TYPE_STANDARD, or else as specified in the class or vendor device type specification.

value - sixteen bit field associated with request

index - sixteen bit field associated with request

length - How much data should be read; may be zero to indicate that no READ phase follows the SETUP packet.

Returns:

The data read from the device. If this is shorter than the requested length, the caller must determine whether to treat that as an error. For example, it's typical to request a full size string descriptor, expecting to get back only the bytes that exist, rather than read a partial descriptor to learn the size, and then reading the whole thing.

writeControl

public void writeControl(byte type,
                         byte request,
                         short value,
                         short index,
                         byte[] buf)
                  throws java.io.IOException

Description copied from interface: DeviceSPI

Issues a control OUT request with an optional data WRITE phase. The request goes to the default control endpoint (CONTROL OUT zero). No interface needs to be claimed in order to issue control requests.

Most of the parameters here are used to build the SETUP packet for the control request, which is always written to the device. Note an OUT control request with only a setup packet is different from the IN request with the same bits in the setup packet data; it goes to a different endpoint.

Specified by:

writeControl in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

type - Masked together using three constants from ControlMessage: DIR_TO_DEVICE, a TYPE_*, and a RECIP_*.

request - bRequest field, either standard (from table 9-3 in the USB 2.0 specification) for TYPE_STANDARD, or else as specified in the class or vendor device type specification.

value - sixteen bit field associated with request

index - sixteen bit field associated with request

buf - The data to be written. Length may be zero to indicate that no WRITe phase follows the SETUP packet.

getConfigBuf

public byte[] getConfigBuf(int n)
                    throws java.io.IOException

Description copied from interface: DeviceSPI

Returns a buffer holding the entire set of configuration descriptors for the specified configuration. The format of those descriptors is described in the USB 2.0 specification.

Specified by:

getConfigBuf in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

config - Number of the configuration, from zero to the limit specified by DeviceDescriptor.getNumConfigurations()

cyclePortWorks

public boolean cyclePortWorks()

cyclePort

public int cyclePort()

readBulk

public byte[] readBulk(int ep,
                       int length)
                throws java.io.IOException

Assigns the specified configuration as current.

Specified by:

readBulk in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

length - How many bytes to read.

Returns:

The bytes actually read.

readBulk

public int readBulk(int ep,
                    byte[] buf,
                    int off,
                    int length)

writeBulk

public void writeBulk(int ep,
                      byte[] buf)
               throws usb.windows.USBException

Description copied from interface: DeviceSPI

Writes a specified number of bytes to a BULK OUT endpoint. If this isn't an exact multiple of Endpoint.getMaxPacketSize() then the last packet is "short". To write such an exact multiple with a "short" last packet, explicitly follow this write by another, using a buffer with length zero.

An endpoint's interface should be claimed before it is used for bulk I/O.

Specified by:

writeBulk in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

buf - The bytes to write.

writeBulk

public void writeBulk(int ep,
                      byte[] buf,
                      int off,
                      int length)
               throws usb.windows.USBException

readIntr

public byte[] readIntr(int ep,
                       int length)

Description copied from interface: DeviceSPI

Reads a specified number of bytes from a INTERRUPT IN endpoint. This may be fewer bytes than were requested; the caller must decide whether that's an error in this case.

This blocks until an interrupt transfer completes. It's the caller's responsibility to ensure that the endpoint is polled often enough to meet Endpoint.getInterval() requirements after a transfer completes.

An endpoint's interface should be claimed before it is used for interrupt I/O.

Specified by:

readIntr in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

length - How many bytes to read.

Returns:

The bytes actually read.

writeIntr

public void writeIntr(int ep,
                      byte[] buf)
               throws usb.windows.USBException

Description copied from interface: DeviceSPI

Writes a specified number of bytes to a INTERRUPT OUT endpoint. If this isn't an exact multiple of Endpoint.getMaxPacketSize() then the last packet is "short". To write such an exact multiple with a "short" last packet, explicitly follow this write with a write of a buffer with length zero.

This blocks until an interrupt transfer completes. It's the caller's responsibility to ensure that the endpoint is polled often enough to meet Endpoint.getInterval() requirements after a transfer completes.

An endpoint's interface should be claimed before it is used for interrupt I/O.

Specified by:

writeIntr in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ep - Endpoint direction and address, as specified in an endpoint descriptor by Endpoint.getEndpoint().

buf - The bytes to write.

clearHalt

public int clearHalt(byte ep)

Description copied from interface: DeviceSPI

Clears halt/stall status on an endpoint. Bulk and interrupt endpoints will stall to report some kinds of error. Clearing this status resets the "data toggle" at the USB protocol level, and re-enables I/O to the previously halted endpoint.

The endpoint's interface should be claimed before clearing its halt status.

Specified by:

clearHalt in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ep - Endpoint address and direction, as returned by Endpoint.getEndpoint().

claimInterface

public void claimInterface(int ifno)
                    throws java.io.IOException

Claims this interface, so that no other driver can.

Specified by:

claimInterface in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

See Also:

DeviceSPI.releaseInterface(int)

releaseInterface

public void releaseInterface(int ifno)
                      throws java.io.IOException

Releases an interface claim.

Specified by:

releaseInterface in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

See Also:

DeviceSPI.claimInterface(int)

setInterface

public void setInterface(int ifno,
                         int alt)
                  throws java.io.IOException

Assigns an interface to an alternate setting. Note: alternate settings probably aren't handled correctly yet.

Specified by:

setInterface in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

alt - Number from the descriptor, returned by Interface.getAlternateSetting().

getClaimer

public java.lang.String getClaimer(int ifno)

Returns a system-specific string providing information about the driver claiming this interface, or null.

Specified by:

getClaimer in interface DeviceSPI

Following copied from interface: usb.core.DeviceSPI

Parameters:

ifnum - Number from the descriptor, returned by Interface.getNumber().

Returns:

Driver name, or null to indicate the interface is not in use by any driver. Driver names are not standardized between host operating systems.