usb.core
Class ControlMessage

java.lang.Object
  |
  +--usb.core.ControlMessage

public final class ControlMessage

extends java.lang.Object

This class supports control messaging with convenience methods for common calls, and encapsulates data for all control requests.

It may be useful to think of USB control messaging as a simple RPC facility. They may be directed to several types of recipient on the USB device (RECIPIENT_DEVICE for the device itself; also endpoints, interfaces, and "other"). They may be classified (TYPE_STANDARD for requests found in the USB specification; also class requests and vendor-specific requests). All requests may send thirty-two bits of data, in two sixteen bit fields: "value" and "index". Requests may optionally send or receive data. USB places a limit of 64 KBytes on the size of that data, but most control requests involve much less data than that.

The convenience functions in this class, used for issuing standard requests such as getStandardDescriptor, are all wrappers around Device.control which does the real work.

Control messages are discussed in detail in sections 9.3 and 9.4 of the USB 1.1 specification.

At this writing, the Linux kernel implementation has some open issues with its control messaging. They are reduced by effective string caching (done by this jUSB package) and other techniques to avoid drivers needing to synchronize their control messaging.

See Also:

Device.control(usb.core.ControlMessage)

Field Summary

static byte	CLEAR_FEATURE Request value (1) used to clear device feature flags.
static byte	DIR_TO_DEVICE Request type field indicating host-to-device data transfer phase.
static byte	DIR_TO_HOST Request type field indicating device-to-host data transfer phase.
static byte	GET_CONFIGURATION Request value (8) for the current device configuration descriptor.
static byte	GET_DESCRIPTOR Request value (6) used to get configuration, interface, endpoint, string, or other device descriptors.
static byte	GET_INTERFACE Request value (10) to determine an interface alternate setting.
static byte	GET_STATUS Request value (0) used to determine state.
static byte	RECIPIENT_DEVICE Request type field for device recipient
static byte	RECIPIENT_ENDPOINT Request type field for endpoint recipient
static byte	RECIPIENT_INTERFACE Request type field for interface recipient
static byte	RECIPIENT_OTHER Request type field for other recipient
static byte	SET_ADDRESS Request value (5) used by the host controller driver to assign device numbers during device enumeration.
static byte	SET_CONFIGURATION Request value (9) to choose the device configuration.
static byte	SET_DESCRIPTOR Request value (7) to assign a descriptor
static byte	SET_FEATURE Request value (3) to set device feature flags.
static byte	SET_INTERFACE Request value (11) to select an interface alternate setting.
static byte	SYNCH_FRAME Request value (12) for synchronizing isochronous behaviors.
static byte	TYPE_CLASS Request type field for class-specific requests
static byte	TYPE_STANDARD Request type field for standard requests
static byte	TYPE_VENDOR Request type field for vendor-specific requests

Constructor Summary

ControlMessage()
Constructs an uninitialized control mesage

Method Summary

static void	clearFeature(Device dev, int dest, int feature, int index) Clears the identified feature flag to false.
static boolean	getBit(int bitNum, byte[] buf, int fieldOffset) Utility for working with control message results, returning the Nth bit (little endian) starting from the specified byte offset in the buffer.
boolean	getBit(int bitNum, int fieldOffset) Returns the Nth bit (little endian) from the specified byte offset in this message's result.
byte[]	getBuffer() Returns the buffer used to transfer data
static byte[]	getClassDescriptor(Device dev, byte descriptorType, byte id, int index, int len) Requests a USB class descriptor from the specified device.
short	getIndex() Returns the "index" field of the message.
static int[]	getLanguages(Device dev) Returns an array of languages supported by this device for its string descriptors, or null if no string descriptors are provided.
short	getLength() Returns the size of the IO buffer (unsigned 16 bits)
byte	getRequest() Returns the request (GET_STATUS, etc)
byte	getRequestType() Returns the request type, which masks a DIR, TYPE, and RECIPIENT.
static byte[]	getStandardDescriptor(Device dev, byte descriptorType, byte id, int index, int len) Requests a USB standard descriptor from the specified device.
static byte[]	getStatus(Device dev, int dest, int value, int index, int len) Returns the specified type of status.
static java.lang.String	getString(Device dev, byte id, int language) Gets the specified string descriptor from the device.
short	getValue() Returns the "value" field of the message
static byte[]	getVendorDescriptor(Device dev, byte descriptorType, byte id, int index, int len) Requests a USB vendor descriptor from the specified device.
void	setBuffer(byte[] buf) Assigns the buffer used in any data transfer stage of this control operation; used before sending data.
static void	setDescriptor(Device dev, byte descriptorClass, byte descriptorType, byte id, int index, byte[] buf) Sets a descriptor on the specified device.
static void	setFeature(Device dev, int dest, int feature, int index) Sets the identified feature flag to true.
void	setIndex(short index) Assigns the "index" field of the message.
void	setLength(int length) Sets an amount of data to be read (max 64K)
void	setRequest(byte code) Assigns the request (GET_STATUS, etc)
void	setRequestType(byte bits) Assigns bits in the request type.
void	setValue(short value) Assigns the "value" field of the message

Methods inherited from class java.lang.Object

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

Field Detail

DIR_TO_HOST

public static final byte DIR_TO_HOST

Request type field indicating device-to-host data transfer phase.

DIR_TO_DEVICE

public static final byte DIR_TO_DEVICE

Request type field indicating host-to-device data transfer phase.

TYPE_STANDARD

public static final byte TYPE_STANDARD

Request type field for standard requests

TYPE_CLASS

public static final byte TYPE_CLASS

Request type field for class-specific requests

TYPE_VENDOR

public static final byte TYPE_VENDOR

Request type field for vendor-specific requests

RECIPIENT_DEVICE

public static final byte RECIPIENT_DEVICE

Request type field for device recipient

RECIPIENT_INTERFACE

public static final byte RECIPIENT_INTERFACE

Request type field for interface recipient

RECIPIENT_ENDPOINT

public static final byte RECIPIENT_ENDPOINT

Request type field for endpoint recipient

RECIPIENT_OTHER

public static final byte RECIPIENT_OTHER

Request type field for other recipient

GET_STATUS

public static final byte GET_STATUS

Request value (0) used to determine state. For devices, that state includes whether remote wakeup is enabled, and whether the device is self powered. For endpoints, status includes whether it is halted.

CLEAR_FEATURE

public static final byte CLEAR_FEATURE

Request value (1) used to clear device feature flags.

SET_FEATURE

public static final byte SET_FEATURE

Request value (3) to set device feature flags.

SET_ADDRESS

public static final byte SET_ADDRESS

Request value (5) used by the host controller driver to assign device numbers during device enumeration. Currently user mode code does not have access to USB when addresses are not assigned; you shouldn't need to use this value.

GET_DESCRIPTOR

public static final byte GET_DESCRIPTOR

Request value (6) used to get configuration, interface, endpoint, string, or other device descriptors.

SET_DESCRIPTOR

public static final byte SET_DESCRIPTOR

Request value (7) to assign a descriptor

GET_CONFIGURATION

public static final byte GET_CONFIGURATION

Request value (8) for the current device configuration descriptor.

SET_CONFIGURATION

public static final byte SET_CONFIGURATION

Request value (9) to choose the device configuration. This should interact with device claiming, power management, and likely more ...

GET_INTERFACE

public static final byte GET_INTERFACE

Request value (10) to determine an interface alternate setting.

SET_INTERFACE

public static final byte SET_INTERFACE

Request value (11) to select an interface alternate setting.

SYNCH_FRAME

public static final byte SYNCH_FRAME

Request value (12) for synchronizing isochronous behaviors.

Constructor Detail

ControlMessage

public ControlMessage()

Constructs an uninitialized control mesage

Method Detail

getRequestType

public byte getRequestType()

Returns the request type, which masks a DIR, TYPE, and RECIPIENT. For example, DIR_TO_HOST, TYPE_STANDARD, and RECIPIENT_DEVICE would be used in a USB standard request returning device data to the host.

setRequestType

public void setRequestType(byte bits)

Assigns bits in the request type. Construct these values by ORing together three TYPE_ constants: a DIR (only if a buffer is provided with the message), a RECIPIENT (if it's not the device), and optionally one categorizing the request as being class or vendor specific (if it's not a standard request).

getRequest

public byte getRequest()

Returns the request (GET_STATUS, etc)

setRequest

public void setRequest(byte code)

Assigns the request (GET_STATUS, etc)

getValue

public short getValue()

Returns the "value" field of the message

setValue

public void setValue(short value)

Assigns the "value" field of the message

getIndex

public short getIndex()

Returns the "index" field of the message.

setIndex

public void setIndex(short index)

Assigns the "index" field of the message. Endpoints are encoded in the low four bits, with bit seven set if it is an IN endpoint. Interfaces are encoded using the low eight bits.

setBuffer

public void setBuffer(byte[] buf)

Assigns the buffer used in any data transfer stage of this control operation; used before sending data. You are responsible for having the DIR_TO_HOST (buffer is allocated with control message) or DIR_TO_DEVICE (buffer provided before call) values set correctly in the request type.

getBuffer

public byte[] getBuffer()

Returns the buffer used to transfer data

setLength

public void setLength(int length)

Sets an amount of data to be read (max 64K)

getLength

public short getLength()

Returns the size of the IO buffer (unsigned 16 bits)

getBit

public static boolean getBit(int bitNum,
                             byte[] buf,
                             int fieldOffset)

Utility for working with control message results, returning the Nth bit (little endian) starting from the specified byte offset in the buffer.

Many standard USB data structures use feature IDs as bit numbers in status record fields ... in particular, feature flags are normally bits in device status words.

getBit

public boolean getBit(int bitNum,
                      int fieldOffset)

Returns the Nth bit (little endian) from the specified byte offset in this message's result.

See Also:

getStatus(usb.core.Device, int, int, int, int)

getStandardDescriptor

public static byte[] getStandardDescriptor(Device dev,
                                           byte descriptorType,
                                           byte id,
                                           int index,
                                           int len)
                                    throws java.io.IOException

Requests a USB standard descriptor from the specified device.

Parameters:

descriptorType - a Descriptor.TYPE_* value

getClassDescriptor

public static byte[] getClassDescriptor(Device dev,
                                        byte descriptorType,
                                        byte id,
                                        int index,
                                        int len)
                                 throws java.io.IOException

Requests a USB class descriptor from the specified device.

getVendorDescriptor

public static byte[] getVendorDescriptor(Device dev,
                                         byte descriptorType,
                                         byte id,
                                         int index,
                                         int len)
                                  throws java.io.IOException

Requests a USB vendor descriptor from the specified device.

setDescriptor

public static void setDescriptor(Device dev,
                                 byte descriptorClass,
                                 byte descriptorType,
                                 byte id,
                                 int index,
                                 byte[] buf)
                          throws java.io.IOException

Sets a descriptor on the specified device.

Parameters:

descriptorClass - TYPE_STANDARD, TYPE_CLASS, or TYPE_VENDOR

getLanguages

public static int[] getLanguages(Device dev)
                          throws java.io.IOException

Returns an array of languages supported by this device for its string descriptors, or null if no string descriptors are provided. These languages are identified by the numeric codes described in the USB 1.1 specification, which need mapping to Java locales if you intend to use them with other Java APIs.

See Also:

LangCode.getLocale(int)

getString

public static java.lang.String getString(Device dev,
                                         byte id,
                                         int language)
                                  throws java.io.IOException

Gets the specified string descriptor from the device.

Parameters:

id - Identifier for the string, any byte except zero

getStatus

public static byte[] getStatus(Device dev,
                               int dest,
                               int value,
                               int index,
                               int len)
                        throws java.io.IOException

Returns the specified type of status. Device and endpoint status are described in section 9.4.5 of the USB specification; bits are set and cleared using setFeature and clearFeature.

Parameters:

dest - includes a message type and recipient, such as masking the values TYPE_CLASS and RECIPIENT_INTERFACE.

value - typically zero

index - field for the feature, such as an endpoint (don't rely on seeing status for control endpoint zero) or hub port number

len - maximum size of returned array

Throws:

USBException - if another driver has claimed that interface or endpoint

clearFeature

public static void clearFeature(Device dev,
                                int dest,
                                int feature,
                                int index)
                         throws java.io.IOException

Clears the identified feature flag to false.

Parameters:

dest - includes a message type and recipient, such as masking the values TYPE_CLASS and RECIPIENT_OTHER.

feature - one of the device's defined feature identifiers

index - field for the feature, such as a hub port number (or zero)

Throws:

USBException - if another driver has claimed that interface or endpoint

See Also:

setFeature(usb.core.Device, int, int, int)

setFeature

public static void setFeature(Device dev,
                              int dest,
                              int feature,
                              int index)
                       throws java.io.IOException

Sets the identified feature flag to true. This will retry in the face of stalls.

Parameters:

dest - includes a message type and recipient, such as masking the values TYPE_STANDARD and RECIPIENT_DEVICE.

feature - one of the device's defined feature identifiers

index - field for the feature, such as a hub port number (or zero)

Throws:

USBException - if another driver has claimed that interface or endpoint

See Also:

clearFeature(usb.core.Device, int, int, int)