javax.usb
Interface UsbInterface


public interface UsbInterface

Interface for a USB interface.

This object actually represents a specific 'alternate' setting for a USB interface. Interfaces must have at least one alternate setting, and one and only one setting is active per interface. All settings share the same interface number. If this interface setting is not active, it cannot be claimed or released; the active interface setting should be used for claiming and releasing ownership of the interface; also no action may be taken on any parts of this interface setting, if the setting is not active. Any attempt to perform action on objects belonging to an inactive interface setting will throw a UsbNotActiveException.

Author:
Dan Streetman

Method Summary
 void claim()
          Claim this interface.
 void claim(UsbInterfacePolicy policy)
          Claim this interface using a UsbInterfacePolicy.
 boolean containsSetting(byte number)
          If the specified alternate setting exists.
 boolean containsUsbEndpoint(byte address)
          If the specified UsbEndpoint is contained in this UsbInterface.
 UsbInterface getActiveSetting()
          Get the active alternate setting.
 byte getActiveSettingNumber()
          Get the number of the active alternate setting.
 java.lang.String getInterfaceString()
          Get the interface String.
 int getNumSettings()
          Get the number of alternate settings for this interface.
 UsbInterface getSetting(byte number)
          Get the specified alternate setting.
 java.util.List getSettings()
          Get all alternate settings for this interface.
 UsbConfiguration getUsbConfiguration()
          Get the parent UsbConfiguration that this UsbInterface belongs to.
 UsbEndpoint getUsbEndpoint(byte address)
          Get a specific UsbEndpoint.
 java.util.List getUsbEndpoints()
          Get all endpoints for this interface setting.
 UsbInterfaceDescriptor getUsbInterfaceDescriptor()
          Get the interface descriptor.
 boolean isActive()
          If this interface alternate setting is active.
 boolean isClaimed()
          If this interface is claimed.
 void release()
          Release this interface.
 

Method Detail

claim

public void claim()
           throws UsbClaimException,
                  UsbException,
                  UsbNotActiveException,
                  UsbDisconnectedException
Claim this interface.

This will attempt whatever claiming the native implementation provides, if any. If the interface is already claimed, or the native claim fails, this will fail.

This must be done before opening and/or using any UsbPipes.

Throws:
UsbClaimException - If the interface is already claimed.
UsbException - If the interface could not be claimed.
UsbNotActiveException - If this interface setting is not active.
UsbDisconnectedException - If this interface (device) has been disconnected.

claim

public void claim(UsbInterfacePolicy policy)
           throws UsbClaimException,
                  UsbException,
                  UsbNotActiveException,
                  UsbDisconnectedException
Claim this interface using a UsbInterfacePolicy.

This will attempt whatever claiming the native implementation provides, if any. If the native claim fails, this will fail. If the interface is already claimed, this may fail depending on the value of the UsbInterfacePolicy.forceClaim().

Parameters:
policy - The UsbInterfacePolicy to use.
Throws:
UsbClaimException - If the interface is already claimed.
UsbException - If the interface could not be claimed.
UsbNotActiveException - If this interface setting is not active.
UsbDisconnectedException - If this interface (device) has been disconnected.

release

public void release()
             throws UsbClaimException,
                    UsbException,
                    UsbNotActiveException,
                    UsbDisconnectedException
Release this interface.

This will only succeed if the interface has been properly claimed. If the native release fails, this will fail.

This should be done after the interface is no longer being used. All pipes must be closed before this can be released.

Throws:
UsbClaimException - If the interface is not claimed.
UsbException - If the interface could not be released.
UsbNotActiveException - If this interface setting is not active.
UsbDisconnectedException - If this interface (device) has been disconnected.

isClaimed

public boolean isClaimed()
If this interface is claimed.

This will return true if claimed in Java. This may, depending on implementation, return true if claimed natively (outside of Java)

If this UsbInterface is not active, this will return if the active alternate setting is active.

Returns:
If this interface is claimed (in Java).

isActive

public boolean isActive()
If this interface alternate setting is active.

The interface itself is active if and only if its parent configuration is active. If the interface itself is not active, none of its alternate settings are active.

Returns:
if this interface alternate setting is active.

getNumSettings

public int getNumSettings()
Get the number of alternate settings for this interface.

Returns:
the number of alternate settings for this interface.

getActiveSettingNumber

public byte getActiveSettingNumber()
                            throws UsbNotActiveException
Get the number of the active alternate setting.

Returns:
The active setting number for this interface.
Throws:
UsbNotActiveException - If the interface (and parent config) is not active.

getActiveSetting

public UsbInterface getActiveSetting()
                              throws UsbNotActiveException
Get the active alternate setting.

Returns:
The active setting for this interface.
Throws:
UsbNotActiveException - If this interface (and parent config) is not active.

getSetting

public UsbInterface getSetting(byte number)
Get the specified alternate setting.

If the specified setting does not exist, this returns null.

Returns:
The specified alternate setting, or null.

containsSetting

public boolean containsSetting(byte number)
If the specified alternate setting exists.

Parameters:
number - The alternate setting number.
Returns:
If the alternate setting exists.

getSettings

public java.util.List getSettings()
Get all alternate settings for this interface.

This returns all alternate settings, including this one.

Returns:
All alternate settings for this interface.

getUsbEndpoints

public java.util.List getUsbEndpoints()
Get all endpoints for this interface setting.

Returns:
All endpoints for this setting.

getUsbEndpoint

public UsbEndpoint getUsbEndpoint(byte address)
Get a specific UsbEndpoint.

If this does not contain the specified endpoint, this returns null.

Parameters:
address - The address of the UsbEndpoint to get.
Returns:
The specified UsbEndpoint, or null.

containsUsbEndpoint

public boolean containsUsbEndpoint(byte address)
If the specified UsbEndpoint is contained in this UsbInterface.

Parameters:
address - The endpoint address.
Returns:
If this UsbInterface contains the specified UsbEndpoint.

getUsbConfiguration

public UsbConfiguration getUsbConfiguration()
Get the parent UsbConfiguration that this UsbInterface belongs to.

Returns:
The UsbConfiguration that this interface belongs to.

getUsbInterfaceDescriptor

public UsbInterfaceDescriptor getUsbInterfaceDescriptor()
Get the interface descriptor.

The descriptor may be cached.

Returns:
The interface descriptor.

getInterfaceString

public java.lang.String getInterfaceString()
                                    throws UsbException,
                                           java.io.UnsupportedEncodingException,
                                           UsbDisconnectedException
Get the interface String.

This is a convienence method. The String may be cached. If the device does not support strings or does not define the interface string, this returns null.

Returns:
The interface String, or null.
Throws:
UsbException - If there was an error getting the UsbStringDescriptor.
java.io.UnsupportedEncodingException - If the string encoding is not supported.
UsbDisconnectedException - If this interface (device) has been disconnected.