javax.usb.util

Class StandardRequest

java.lang.Object

javax.usb.util.StandardRequest

public class StandardRequest
extends java.lang.Object

Utility to easily allow Standard Device Requests.

These methods are defined in the USB 1.1 specification section 9.4. The table 9.4 lists all Standard Requests.

Many of these methods have parameters whose type is short, but should never be passed more than a byte; e.g. all the interface number and endpoint address parameters have a type of short, but interface numbers and endpoint addresses are byte-sized.

Author:

Dan Streetman

Field Summary

Fields

Modifier and Type	Field and Description
protected static byte	REQUESTTYPE_CLEAR_FEATURE
protected static byte	REQUESTTYPE_GET_CONFIGURATION
protected static byte	REQUESTTYPE_GET_DESCRIPTOR
protected static byte	REQUESTTYPE_GET_INTERFACE
protected static byte	REQUESTTYPE_GET_STATUS
protected static byte	REQUESTTYPE_SET_ADDRESS
protected static byte	REQUESTTYPE_SET_CONFIGURATION
protected static byte	REQUESTTYPE_SET_DESCRIPTOR
protected static byte	REQUESTTYPE_SET_FEATURE
protected static byte	REQUESTTYPE_SET_INTERFACE
protected static byte	REQUESTTYPE_SYNCH_FRAME
protected UsbDevice	usbDevice

Constructor Summary

Constructors

Constructor and Description
StandardRequest(UsbDevice usbDevice) Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	checkRecipient(byte recipient) Check the recipient.
void	clearFeature(byte recipient, short featureSelector, short target) Clear Feature.
static void	clearFeature(UsbDevice usbDevice, byte recipient, short featureSelector, short target) Clear Feature.
byte	getConfiguration() Get Configuration.
static byte	getConfiguration(UsbDevice usbDevice) Get Configuration.
int	getDescriptor(byte type, byte index, short langid, byte[] data) Get Descriptor.
static int	getDescriptor(UsbDevice usbDevice, byte type, byte index, short langid, byte[] data) Get Descriptor.
byte	getInterface(short interfaceNumber) Get Interface.
static byte	getInterface(UsbDevice usbDevice, short interfaceNumber) Get Interface.
short	getStatus(byte recipient, short target) Get Status.
static short	getStatus(UsbDevice usbDevice, byte recipient, short target) Get Status.
void	setAddress(short deviceAddress) Set Address.
static void	setAddress(UsbDevice usbDevice, short deviceAddress) Set Address.
void	setConfiguration(short configurationValue) Set Configuration.
static void	setConfiguration(UsbDevice usbDevice, short configurationValue) Set Configuration.
int	setDescriptor(byte type, byte index, short langid, byte[] data) Set Descriptor.
static int	setDescriptor(UsbDevice usbDevice, byte type, byte index, short langid, byte[] data) Set Descriptor.
void	setFeature(byte recipient, short featureSelector, short target) Set Feature.
static void	setFeature(UsbDevice usbDevice, byte recipient, short featureSelector, short target) Set Feature.
void	setInterface(short interfaceNumber, short alternateSetting) Set Interface.
static void	setInterface(UsbDevice usbDevice, short interfaceNumber, short alternateSetting) Set Interface.
short	synchFrame(short endpointAddress) Synch Frame.
static short	synchFrame(UsbDevice usbDevice, short endpointAddress) Synch Frame.

Methods inherited from class java.lang.Object

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

Field Detail

usbDevice

protected UsbDevice usbDevice

REQUESTTYPE_CLEAR_FEATURE

protected static final byte REQUESTTYPE_CLEAR_FEATURE

See Also:

Constant Field Values

REQUESTTYPE_GET_CONFIGURATION

protected static final byte REQUESTTYPE_GET_CONFIGURATION

See Also:

Constant Field Values

REQUESTTYPE_GET_DESCRIPTOR

protected static final byte REQUESTTYPE_GET_DESCRIPTOR

See Also:

Constant Field Values

REQUESTTYPE_GET_INTERFACE

protected static final byte REQUESTTYPE_GET_INTERFACE

See Also:

Constant Field Values

REQUESTTYPE_GET_STATUS

protected static final byte REQUESTTYPE_GET_STATUS

See Also:

Constant Field Values

REQUESTTYPE_SET_ADDRESS

protected static final byte REQUESTTYPE_SET_ADDRESS

See Also:

Constant Field Values

REQUESTTYPE_SET_CONFIGURATION

protected static final byte REQUESTTYPE_SET_CONFIGURATION

See Also:

Constant Field Values

REQUESTTYPE_SET_DESCRIPTOR

protected static final byte REQUESTTYPE_SET_DESCRIPTOR

See Also:

Constant Field Values

REQUESTTYPE_SET_FEATURE

protected static final byte REQUESTTYPE_SET_FEATURE

See Also:

Constant Field Values

REQUESTTYPE_SET_INTERFACE

protected static final byte REQUESTTYPE_SET_INTERFACE

See Also:

Constant Field Values

REQUESTTYPE_SYNCH_FRAME

protected static final byte REQUESTTYPE_SYNCH_FRAME

See Also:

Constant Field Values

Constructor Detail

StandardRequest

public StandardRequest(UsbDevice usbDevice)

Constructor.

The specified UsbDevice will be used on the instance methods which do not include a UsbDevice parameter. The class methods which do include a UsbDevice parameter will use that UsbDevice.

Parameters:

usbDevice - The UsbDevice to use.

Method Detail

clearFeature

public void clearFeature(byte recipient,
                short featureSelector,
                short target)
                  throws UsbException,
                         java.lang.IllegalArgumentException

Clear Feature.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

recipient - The recipient.

featureSelector - The Feature Selector.

target - The target interface number or endpoint address.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target is invalid.

getConfiguration

public byte getConfiguration()
                      throws UsbException

Get Configuration.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Returns:

The configuration number.

Throws:

UsbException - If unsuccessful.

getDescriptor

public int getDescriptor(byte type,
                byte index,
                short langid,
                byte[] data)
                  throws UsbException

Get Descriptor.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

type - The Descriptor Type.

index - The Descriptor Index.

langid - The String Descriptor Language ID.

data - The data to fill with the Descriptor.

Returns:

The actual length of transferred data.

Throws:

UsbException - If unsuccessful.

getInterface

public byte getInterface(short interfaceNumber)
                  throws UsbException

Get Interface.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

interfaceNumber - The interface number.

Returns:

The active alternate setting for the specified interface.

Throws:

UsbException - If unsuccessful.

getStatus

public short getStatus(byte recipient,
              short target)
                throws UsbException,
                       java.lang.IllegalArgumentException

Get Status.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

recipient - The recipient.

target - The target interface number or endpoint address.

Returns:

The status of the specified recipient.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target is invalid.

setAddress

public void setAddress(short deviceAddress)
                throws UsbException

Set Address.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

deviceAddress - The new device address.

Throws:

UsbException - If unsuccessful.

setConfiguration

public void setConfiguration(short configurationValue)
                      throws UsbException

Set Configuration.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

configurationValue - The new configuration value.

Throws:

UsbException - If unsuccessful.

setDescriptor

public int setDescriptor(byte type,
                byte index,
                short langid,
                byte[] data)
                  throws UsbException

Set Descriptor.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

type - The Descriptor Type.

index - The Descriptor Index.

langid - The String Descriptor Language ID.

data - The Descriptor.

Returns:

The actual length of transferred data.

Throws:

UsbException - If unsuccessful.

setFeature

public void setFeature(byte recipient,
              short featureSelector,
              short target)
                throws UsbException,
                       java.lang.IllegalArgumentException

Set Feature.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

recipient - The recipient.

featureSelector - The Feature Selector.

target - The target interface number or endpoint address.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target is invalid.

setInterface

public void setInterface(short interfaceNumber,
                short alternateSetting)
                  throws UsbException

Set Interface.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

interfaceNumber - The interface number.

alternateSetting - The alternate setting number.

Throws:

UsbException - If unsuccessful.

synchFrame

public short synchFrame(short endpointAddress)
                 throws UsbException

Synch Frame.

This only calls the corresponding class method using the UsbDevice specified in the constructor.

Parameters:

endpointAddress - The endpoint address.

Returns:

The frame number.

Throws:

UsbException - If unsuccessful.

clearFeature

public static void clearFeature(UsbDevice usbDevice,
                byte recipient,
                short featureSelector,
                short target)
                         throws UsbException,
                                java.lang.IllegalArgumentException

Clear Feature.

Valid recipients are device, interface, and endpoint. If the recipient is device, the target must be 0. If the recipient is interface or endpoint, the target is the interface number or endpoint address, respectively.

Parameters:

usbDevice - The UsbDevice.

recipient - The recipient.

featureSelector - The Feature Selector.

target - The target interface number or endpoint address.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target is invalid.

getConfiguration

public static byte getConfiguration(UsbDevice usbDevice)
                             throws UsbException

Get Configuration.

Parameters:

usbDevice - The UsbDevice.

Returns:

The configuration number.

Throws:

UsbException - If unsuccessful.

getDescriptor

public static int getDescriptor(UsbDevice usbDevice,
                byte type,
                byte index,
                short langid,
                byte[] data)
                         throws UsbException

Get Descriptor.

The parameters correspond to the setup packet:

• type is the wValue MSB
• index is the wValue LSB
• langid is the wIndex
• data.length is the wLength

This method does not restrict the Descriptor type, but the device is only required to support those Descriptors defined in the USB 1.1 specification table 9.5, which includes device, configuration, and string descriptor types. Note that devices normally do not support requests for interface or endpoint descriptors; the configuration descriptor contains all its interface and endpoint descriptors.

If the type is string or configuration, the index is used to select the specific descriptor; for other descriptor types is should be 0 (this implementation does not enforce this).

If the type is string, the langid indicates what language to use. For other types it should be 0 (but this is not enforced).

The data is filled with the actual descriptor.

Parameters:

usbDevice - The UsbDevice.

type - The Descriptor Type.

index - The Descriptor Index.

langid - The String Descriptor Language ID.

data - The data to fill with the Descriptor.

Returns:

The actual length of transferred data.

Throws:

UsbException - If unsuccessful.

getInterface

public static byte getInterface(UsbDevice usbDevice,
                short interfaceNumber)
                         throws UsbException

Get Interface.

Parameters:

usbDevice - The UsbDevice.

interfaceNumber - The interface number.

Returns:

The active alternate setting for the specified interface.

Throws:

UsbException - If unsuccessful.

getStatus

public static short getStatus(UsbDevice usbDevice,
              byte recipient,
              short target)
                       throws UsbException,
                              java.lang.IllegalArgumentException

Get Status.

Valid recipients are device, interface, and endpoint. If the recipient is device, the target must be 0. If the recipient is interface or endpoint, the target is the interface number or endpoint address, respectively.

Parameters:

usbDevice - The UsbDevice.

recipient - The recipient.

target - The target interface number or endpoint address.

Returns:

The status of the specified recipient.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target are invalid.

setAddress

public static void setAddress(UsbDevice usbDevice,
              short deviceAddress)
                       throws UsbException

Set Address.

Since this is normally only used by the low-level Host Controller Driver, this quite likely will either fail or cause serious problems. This should not be used unless you know what you are doing and know that the Operating System's Host Controller Driver can handle this.

Parameters:

usbDevice - The UsbDevice.

deviceAddress - The new device address.

Throws:

UsbException - If unsuccessful.

setConfiguration

public static void setConfiguration(UsbDevice usbDevice,
                    short configurationValue)
                             throws UsbException

Set Configuration.

Parameters:

usbDevice - The UsbDevice.

configurationValue - The new configuration value.

Throws:

UsbException - If unsuccessful.

setDescriptor

public static int setDescriptor(UsbDevice usbDevice,
                byte type,
                byte index,
                short langid,
                byte[] data)
                         throws UsbException

Set Descriptor.

The parameters correspond to the setup packet:

• type is the wValue MSB
• index is the wValue LSB
• langid is the wIndex
• data.length is the wLength

This method does not restrict the Descriptor type, but the device is only required to support those Descriptors defined in the USB 1.1 specification table 9.5, which includes device, configuration, and string descriptor types. Note that devices normally do not support requests for interface or endpoint descriptors; the configuration descriptor contains all its interface and endpoint descriptors.

If the type is string or configuration, the index is used to select the specific descriptor; for other descriptor types is should be 0 (this implementation does not enforce this).

If the type is string, the langid indicates what language to use. For other types it should be 0 (but this is not enforced).

The data should contain the actual Descriptor. The entire length is used, i.e. wLength is set to data.length.

Parameters:

usbDevice - The UsbDevice.

type - The Descriptor Type.

index - The Descriptor Index.

langid - The String Descriptor Language ID.

data - The Descriptor.

Returns:

The actual length of transferred data.

Throws:

UsbException - If unsuccessful.

setFeature

public static void setFeature(UsbDevice usbDevice,
              byte recipient,
              short featureSelector,
              short target)
                       throws UsbException,
                              java.lang.IllegalArgumentException

Set Feature.

Valid recipients are device, interface, and endpoint. If the recipient is device, the target is either 0 or the Test Selector. If the recipient is interface or endpoint, the target is the interface number or endpoint address, respectively.

Parameters:

usbDevice - The UsbDevice.

recipient - The recipient.

featureSelector - The Feature Selector.

target - The target interface number or endpoint address.

Throws:

UsbException - If unsuccessful.

java.lang.IllegalArgumentException - If the recipient or target is invalid.

setInterface

public static void setInterface(UsbDevice usbDevice,
                short interfaceNumber,
                short alternateSetting)
                         throws UsbException

Set Interface.

Parameters:

usbDevice - The UsbDevice.

interfaceNumber - The interface number.

alternateSetting - The alternate setting number.

Throws:

UsbException - If unsuccessful.

synchFrame

public static short synchFrame(UsbDevice usbDevice,
               short endpointAddress)
                        throws UsbException

Synch Frame.

Parameters:

usbDevice - The UsbDevice.

endpointAddress - The endpoint address.

Returns:

The frame number.

Throws:

UsbException - If unsuccessful.

checkRecipient

protected static void checkRecipient(byte recipient)
                              throws java.lang.IllegalArgumentException

Check the recipient.

Valid recipients are device, interface, and endpoint.

Parameters:

recipient - The recipient.

Throws:

java.lang.IllegalArgumentException - If the recipient is not valid.