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.


Associated source code is licenced under the LGPL.
See http://jusb.sourceforge.net
This documentation was derived from that source code on 24-Jul-2002.