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.