controlmessage.java

JAVA 访问USB JAVA 访问USB JAVA 访问USB JAVA 访问USB JAVA 访问USB JAVA 访问USB

/*
 * Java USB Library
 * Copyright (C) 2000 by David Brownell
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package usb.core;

import java.io.IOException;
import java.io.Serializable;


/**
 * This class supports control messaging with convenience methods for
 * common calls, and encapsulates data for all control requests.
 *
 * <p> 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.
 *
 * <p> The convenience functions in this class, used for issuing
 * standard requests such as
 * {@link #getStandardDescriptor getStandardDescriptor}, are all
 * wrappers around {@link Device#control Device.control} which does
 * the real work.
 *
 * <p> Control messages are discussed in detail in sections 9.3 and
 * 9.4 of the USB 1.1 specification.
 *
 * <p> At this writing, the Linux implementation has some open
 * issues with its control messaging; they are reduced by effective
 * string caching.
 *
 * @see Device#control
 *
 * @version $Id: ControlMessage.java,v 1.4 2000/11/18 22:58:39 dbrownell Exp $
 */
final public class ControlMessage
{
    private byte	requestType;
    private byte	request;
    private short	value;
    private short	index;

    private byte	buf [];
    private short	len;


    /** Constructs an uninitialized control mesage */
    public ControlMessage () { }

	// 1 bit: 0x80
    /** Request type field indicating device-to-host data transfer phase. */
    public static final byte DIR_TO_HOST = (byte) 0x80;

    /** Request type field indicating host-to-device data transfer phase. */
    public static final byte DIR_TO_DEVICE = 0x00;


	// 2 bits:  0x60
    /** Request type field for standard requests */
    public static final byte TYPE_STANDARD = 0x00;

    /** Request type field for class-specific requests */
    public static final byte TYPE_CLASS = 0x20;

    /** Request type field for vendor-specific requests */
    public static final byte TYPE_VENDOR = 0x40;

	// 3 unused bits: 0x1c

	// 2 bits:  0x03
    /** Request type field for device recipient */
    public static final byte RECIPIENT_DEVICE = 0;

    /** Request type field for interface recipient */
    public static final byte RECIPIENT_INTERFACE = 1;

    /** Request type field for endpoint recipient */
    public static final byte RECIPIENT_ENDPOINT = 2;

    /** Request type field for other recipient */
    public static final byte RECIPIENT_OTHER = 3;

    /**
     * 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.
     */
    public byte getRequestType ()
	{ return requestType; }

    /**
     * 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).
     */
    public void setRequestType (byte bits)
	{ requestType = bits; }


    /**
     * 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.
     */
    public static final byte GET_STATUS = 0;

    /** Request value (1) used to clear device feature flags. */
    public static final byte CLEAR_FEATURE = 1;

    // 2 reserved

    /** Request value (3) to set device feature flags. */
    public static final byte SET_FEATURE = 3;

    // 4 reserved

    /**
     * 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.
     */
    public static final byte SET_ADDRESS = 5;

    /**
     * Request value (6) used to get configuration, interface, endpoint,
     * string, or other device descriptors.
     */
    public static final byte GET_DESCRIPTOR = 6;

    /** Request value (7) to assign a descriptor */
    public static final byte SET_DESCRIPTOR = 7;


    /** Request value (8) for the current device configuration descriptor. */
    public static final byte GET_CONFIGURATION = 8;

    /**
     * Request value (9) to choose the device configuration.
     * <em>This should interact with device claiming, power management,
     * and likely more ...</em>
     */
    public static final byte SET_CONFIGURATION = 9;


    /** Request value (10) to determine an interface alternate setting. */
    public static final byte GET_INTERFACE = 10;

    /** Request value (11) to select an interface alternate setting. */
    public static final byte SET_INTERFACE = 11;


    /** Request value (12) for synchronizing isochronous behaviors. */
    public static final byte SYNCH_FRAME = 12;


    /** Returns the request (GET_STATUS, etc) */
    public byte getRequest ()
	{ return request; }

    /** Assigns the request (GET_STATUS, etc) */
    public void setRequest (byte code)
	// could mask request type fields ..
	{ request = code; }

    
    /** Returns the "value" field of the message */
    public short getValue ()
	{ return value; }
    
    /** Assigns the "value" field of the message */
    public void setValue (short value)
	{ this.value = value; }
    
    /**
     * Returns the "index" field of the message.
     */
    public short getIndex ()
	{ return 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.
     */
    public void setIndex (short index)
	{ this.index = index; }
    
    /**
     * 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.
     */
    public void setBuffer (byte buf [])
    {
	if (buf == null || buf.length >= 0xffff)
	    throw new IllegalArgumentException ();
	this.buf = buf;
	this.len = (short) buf.length;
    }

    /** Returns the buffer used to transfer data */
    public byte [] getBuffer () { return buf; }

    /** Sets an amount of data to be read (max 64K) */
    public void setLength (int length) { len = (short) length; }

    /** Returns the size of the IO buffer (unsigned 16 bits) */
    public short getLength () { return len; }

    /**
     * Utility for working with control message results,
     * returning the Nth bit (little endian) starting from the
     * specified byte offset in the buffer.
     *
     * <p>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.
     */
    public static boolean getBit (int bitNum, byte buf [], int fieldOffset)
    {
	byte	b;

	b = buf [fieldOffset + (bitNum / 8)];
	b >>= bitNum % 8;
	return (b & 0x01) != 0;
    }

    /**
     * Returns the Nth bit (little endian) from the specified
     * byte offset in this message's result.
     *
     * @see #getStatus
     */
    public boolean getBit (int bitNum, int fieldOffset)
    {
	return getBit (bitNum, buf, fieldOffset);
    }


    /**
     * Requests a USB standard descriptor from the specified device.
     *
     * @param descriptorType a {@link Descriptor}.TYPE_* value
     */
    public static byte [] getStandardDescriptor (
	Device dev,
	byte descriptorType,