usb.core
Class Interface

java.lang.Object
  |
  +--usb.core.Descriptor
        |
        +--usb.core.Interface
All Implemented Interfaces:
java.io.Serializable

public final class Interface
extends Descriptor

USB interfaces describe sets of endpoints, and are associated with a particular device configuration. Applications must claim interfaces before they can communicate with devices using any method other than control messaging, to structure the sharing of device resources between different drivers.

Interfaces may have alternate settings, affecting issues such as bandwidth consumption. For example, a given video camera interface might use alternate settings to provide control over multiple image sizes and compression options, or to reduce USB bandwidth utilization. Applications make sure they are claiming the right alternate setting, and be aware of claims other modules may have made on the interface, before they try to claim use of a device interface.

Most fields of this descriptor are specified in section 9.6.3 of the USB 1.1 specification.

See Also:
Serialized Form

Fields inherited from class usb.core.Descriptor
CLASS_APP_SPECIFIC, CLASS_AUDIO, CLASS_COMM, CLASS_DATA, CLASS_HID, CLASS_HUB, CLASS_MASS_STORAGE, CLASS_PRINTER, CLASS_VENDOR_SPECIFIC, TYPE_CONFIGURATION, TYPE_DEVICE, TYPE_DEVICE_QUALIFIER, TYPE_ENDPOINT, TYPE_HID, TYPE_HUB, TYPE_INTERFACE, TYPE_INTERFACE_POWER, TYPE_OTHER_SPEED, TYPE_PHYSICAL, TYPE_REPORT, TYPE_STRING
 
Constructor Summary
Interface(Configuration conf, byte[] buf)
           
 
Method Summary
 boolean claim()
          Claims this interface if it is not claimed by some other module, and assigns the appropriate alternate setting.
 int getAlternateSetting()
          Used to identify alternate setting for an interface.
 java.lang.String getClaimer()
          Returns a string identifying the driver which has claimed this interface, or null.
 Configuration getConfiguration()
          Returns the configuration with which the interface is associated
 Device getDevice()
          Returns the device with which this USB object is associated.
 Endpoint getEndpoint(int index)
          Returns descriptor for an endpoint in this interface.
 java.lang.String getInterface(int language)
          Returns a string describing this interface in the specified language, or null if no such string is available.
 int getInterfaceClass()
          Returns the interface class
 java.lang.String getInterfaceClassName()
          Returns the name of interface class
 int getInterfaceProtocol()
          Returns the interface protocol
 int getInterfaceStringId()
          Returns the identifier of the string describing this interface, or zero.
 int getInterfaceSubClass()
          Returns the interface subclass
 int getNumber()
          Returns the interface number.
 int getNumEndpoints()
          Returns the number of endpoints in this interface.
 void release()
          Releases a previous claim on this interface.
 
Methods inherited from class usb.core.Descriptor
getBCD, getClassName, getDescriptorType, getDescriptorTypeName, getLength, getU16, getU32, getU8, nextDescriptor
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Interface

public Interface(Configuration conf,
                 byte[] buf)
Method Detail

getNumber

public int getNumber()
Returns the interface number.

getAlternateSetting

public int getAlternateSetting()
Used to identify alternate setting for an interface. Interfaces may have multiple alternates; only one of them may be claimed at a time.

getNumEndpoints

public int getNumEndpoints()
Returns the number of endpoints in this interface.

getInterfaceClass

public int getInterfaceClass()
Returns the interface class

getInterfaceClassName

public java.lang.String getInterfaceClassName()
Returns the name of interface class

getInterfaceSubClass

public int getInterfaceSubClass()
Returns the interface subclass

getInterfaceProtocol

public int getInterfaceProtocol()
Returns the interface protocol

getInterface

public java.lang.String getInterface(int language)
Returns a string describing this interface in the specified language, or null if no such string is available.

getInterfaceStringId

public int getInterfaceStringId()
Returns the identifier of the string describing this interface, or zero.

getDevice

public Device getDevice()
Description copied from class: Descriptor
Returns the device with which this USB object is associated.
Overrides:
getDevice in class Descriptor

getConfiguration

public Configuration getConfiguration()
Returns the configuration with which the interface is associated

getEndpoint

public Endpoint getEndpoint(int index)
                     throws java.io.IOException
Returns descriptor for an endpoint in this interface.
Throws:
java.io.IOException - if the specified descriptor is unavailable

claim

public boolean claim()
              throws java.io.IOException
Claims this interface if it is not claimed by some other module, and assigns the appropriate alternate setting.

NOTE (may be temporary): This may force a claim by some other module to be released. It may be preferable to expose an API to let that be requested. For now, applications should probably avoid claiming interfaces that another module claimed.

Throws:
java.io.IOException - if some other module claimed this interface instead; or if the alternate setting could not be assigned.
See Also:
getClaimer()

release

public void release()
             throws java.io.IOException
Releases a previous claim on this interface.
Throws:
java.lang.IllegalStateException - if it was unclaimed

getClaimer

public java.lang.String getClaimer()
                            throws java.io.IOException
Returns a string identifying the driver which has claimed this interface, or null. At this writing, this claim may be silently (to the application) be undone if this thread claims this interface. Also, these strings always identify kernel drivers (including usbdevfs).

With the addition of remote device support, it is now practical to talk with devices managed by other Java processes. That will require recording non-kernel driver claims.

See Also:
claim()


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.