javax.usb.util
Class StandardRequest

java.lang.Object
  extended by 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

Constructor Summary
StandardRequest(UsbDevice usbDevice)
          Constructor.
 
Method Summary
 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
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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:

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:

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.