am 11dd5ae9: Improve Javadoc for USB Manager and MTP/PTP support.

* commit '11dd5ae97b1cd5889bb66862fd12718da62a9c75':
  Improve Javadoc for USB Manager and MTP/PTP support.

8 files changed, 205 insertions, 36 deletions

diff --git a/core/java/android/hardware/usb/UsbAccessory.java b/core/java/android/hardware/usb/UsbAccessory.java
index 5e9ead0..c8ea825 100644
--- a/core/java/android/hardware/usb/UsbAccessory.java
+++ b/core/java/android/hardware/usb/UsbAccessory.java
@@ -22,7 +22,21 @@ import android.os.Parcelable;
 import android.util.Log;
 
 /**
- * A class representing a USB accessory.
+ * A class representing a USB accessory, which is an external hardware component
+ * that communicates with an android application over USB.
+ * The accessory is the USB host and android the device side of the USB connection.
+ *
+ * <p>When the accessory connects, it reports its manufacturer and model names,
+ * the version of the accessory, and a user visible description of the accessory to the device.
+ * The manufacturer, model and version strings are used by the USB Manager to choose
+ * an appropriate application for the accessory.
+ * The accessory may optionally provide a unique serial number
+ * and a URL to for the accessory's website to the device as well.
+ *
+ * <p>An instance of this class is sent to the application via the
+ * {@link UsbManager#ACTION_USB_ACCESSORY_ATTACHED} Intent.
+ * The application can then call {@link UsbManager#openAccessory} to open a file descriptor
+ * for reading and writing data to and from the accessory.
  */
 public class UsbAccessory implements Parcelable {
 
@@ -63,7 +77,7 @@ public class UsbAccessory implements Parcelable {
     }
 
     /**
-     * Returns the manufacturer of the accessory.
+     * Returns the manufacturer name of the accessory.
      *
      * @return the accessory manufacturer
      */
diff --git a/core/java/android/hardware/usb/UsbConstants.java b/core/java/android/hardware/usb/UsbConstants.java
index 6626c9f..0e8d47c 100644
--- a/core/java/android/hardware/usb/UsbConstants.java
+++ b/core/java/android/hardware/usb/UsbConstants.java
@@ -22,45 +22,162 @@ package android.hardware.usb;
  */
 public final class UsbConstants {
 
+    /**
+     * Bitmask used for extracting the {@link UsbEndpoint} direction from its address field.
+     * @see UsbEndpoint#getAddress
+     * @see UsbEndpoint#getDirection
+     * @see #USB_DIR_OUT
+     * @see #USB_DIR_IN
+     *
+     */
     public static final int USB_ENDPOINT_DIR_MASK = 0x80;
+    /**
+     * Used to signify direction of data for a {@link UsbEndpoint} is OUT (host to device)
+     * @see UsbEndpoint#getDirection
+     */
     public static final int USB_DIR_OUT = 0;
+    /**
+     * Used to signify direction of data for a {@link UsbEndpoint} is IN (device to host)
+     * @see UsbEndpoint#getDirection
+     */
     public static final int USB_DIR_IN = 0x80;
 
-    public static final int USB_TYPE_MASK = (0x03 << 5);
-    public static final int USB_TYPE_STANDARD = (0x00 << 5);
-    public static final int USB_TYPE_CLASS = (0x01 << 5);
-    public static final int USB_TYPE_VENDOR = (0x02 << 5);
-    public static final int USB_TYPE_RESERVED = (0x03 << 5);
-
+    /**
+     * Bitmask used for extracting the {@link UsbEndpoint} number its address field.
+     * @see UsbEndpoint#getAddress
+     * @see UsbEndpoint#getEndpointNumber
+     */
     public static final int USB_ENDPOINT_NUMBER_MASK = 0x0f;
 
-    // flags for endpoint attributes
+    /**
+     * Bitmask used for extracting the {@link UsbEndpoint} type from its address field.
+     * @see UsbEndpoint#getAddress
+     * @see UsbEndpoint#getType
+     * @see #USB_ENDPOINT_XFER_CONTROL
+     * @see #USB_ENDPOINT_XFER_ISOC
+     * @see #USB_ENDPOINT_XFER_BULK
+     * @see #USB_ENDPOINT_XFER_INT
+     */
     public static final int USB_ENDPOINT_XFERTYPE_MASK = 0x03;
+    /**
+     * Control endpoint type (endpoint zero)
+     * @see UsbEndpoint#getType
+     */
     public static final int USB_ENDPOINT_XFER_CONTROL = 0;
+    /**
+     * Isochronous endpoint type (currently not supported)
+     * @see UsbEndpoint#getType
+     */
     public static final int USB_ENDPOINT_XFER_ISOC = 1;
+    /**
+     * Bulk endpoint type
+     * @see UsbEndpoint#getType
+     */
     public static final int USB_ENDPOINT_XFER_BULK = 2;
+    /**
+     * Interrupt endpoint type
+     * @see UsbEndpoint#getType
+     */
     public static final int USB_ENDPOINT_XFER_INT = 3;
 
-    // USB classes
+
+    /**
+     * Bitmask used for encoding the request type for a control request on endpoint zero.
+     */
+    public static final int USB_TYPE_MASK = (0x03 << 5);
+    /**
+     * Used to specify that an endpoint zero control request is a standard request.
+     */
+    public static final int USB_TYPE_STANDARD = (0x00 << 5);
+    /**
+     * Used to specify that an endpoint zero control request is a class specific request.
+     */
+    public static final int USB_TYPE_CLASS = (0x01 << 5);
+    /**
+     * Used to specify that an endpoint zero control request is a vendor specific request.
+     */
+    public static final int USB_TYPE_VENDOR = (0x02 << 5);
+    /**
+     * Reserved endpoint zero control request type (currently unused).
+     */
+    public static final int USB_TYPE_RESERVED = (0x03 << 5);
+
+
+    /**
+     * USB class indicating that the class is determined on a per-interface basis.
+     */
     public static final int USB_CLASS_PER_INTERFACE = 0;
+    /**
+     * USB class for audio devices.
+     */
     public static final int USB_CLASS_AUDIO = 1;
+    /**
+     * USB class for communication devices.
+     */
     public static final int USB_CLASS_COMM = 2;
+    /**
+     * USB class for human interface devices (for example, mice and keyboards).
+     */
     public static final int USB_CLASS_HID = 3;
+    /**
+     * USB class for physical devices.
+     */
     public static final int USB_CLASS_PHYSICA = 5;
+    /**
+     * USB class for still image devices (digital cameras).
+     */
     public static final int USB_CLASS_STILL_IMAGE = 6;
+    /**
+     * USB class for printers.
+     */
     public static final int USB_CLASS_PRINTER = 7;
+    /**
+     * USB class for mass storage devices.
+     */
     public static final int USB_CLASS_MASS_STORAGE = 8;
+    /**
+     * USB class for USB hubs.
+     */
     public static final int USB_CLASS_HUB = 9;
+    /**
+     * USB class for CDC devices (communications device class).
+     */
     public static final int USB_CLASS_CDC_DATA = 0x0a;
+    /**
+     * USB class for content smart card devices.
+     */
     public static final int USB_CLASS_CSCID = 0x0b;
+    /**
+     * USB class for content security devices.
+     */
     public static final int USB_CLASS_CONTENT_SEC = 0x0d;
+    /**
+     * USB class for video devices.
+     */
     public static final int USB_CLASS_VIDEO = 0x0e;
+    /**
+     * USB class for wireless controller devices.
+     */
     public static final int USB_CLASS_WIRELESS_CONTROLLER = 0xe0;
+    /**
+     * USB class for wireless miscellaneous devices.
+     */
     public static final int USB_CLASS_MISC = 0xef;
+    /**
+     * Application specific USB class.
+     */
     public static final int USB_CLASS_APP_SPEC = 0xfe;
+    /**
+     * Vendor specific USB class.
+     */
     public static final int USB_CLASS_VENDOR_SPEC = 0xff;
 
-    // USB subclasses
-    public static final int USB_INTERFACE_SUBCLASS_BOOT = 1;    // for HID class
+    /**
+     * Boot subclass for HID devices.
+     */
+    public static final int USB_INTERFACE_SUBCLASS_BOOT = 1;
+    /**
+     * Vendor specific USB subclass.
+     */
     public static final int USB_SUBCLASS_VENDOR_SPEC = 0xff;
-}
\ No newline at end of file
+}
diff --git a/core/java/android/hardware/usb/UsbDevice.java b/core/java/android/hardware/usb/UsbDevice.java
index 9e536a7..af3f7f0 100644
--- a/core/java/android/hardware/usb/UsbDevice.java
+++ b/core/java/android/hardware/usb/UsbDevice.java
@@ -24,7 +24,16 @@ import android.util.Log;
 import java.io.FileDescriptor;
 
 /**
- * A class representing a USB device.
+ * This class represents a USB device attached to the android device with the android device
+ * acting as the USB host.
+ * Each device contains one or more {@link UsbInterface}s, each of which contains a number of
+ * {@link UsbEndpoint}s (the channels via which data is transmitted over USB).
+ *
+ * <p> This class contains information (along with {@link UsbInterface} and {@link UsbEndpoint})
+ * that describes the capabilities of the USB device.
+ * To communicate with the device, you open a {@link UsbDeviceConnection} for the device
+ * and use {@link UsbRequest} to send and receive data on an endpoint.
+ * {@link UsbDeviceConnection#controlTransfer} is used for control requests on endpoint zero.
  */
 public class UsbDevice implements Parcelable {
 
@@ -96,8 +105,7 @@ public class UsbDevice implements Parcelable {
 
     /**
      * Returns the devices's class field.
-     * Some useful constants for USB device classes can be found in
-     * {@link android.hardware.usb.UsbConstants}
+     * Some useful constants for USB device classes can be found in {@link UsbConstants}.
      *
      * @return the devices's class
      */
@@ -115,7 +123,7 @@ public class UsbDevice implements Parcelable {
     }
 
     /**
-     * Returns the device's subclass field.
+     * Returns the device's protocol field.
      *
      * @return the device's protocol
      */
@@ -124,7 +132,7 @@ public class UsbDevice implements Parcelable {
     }
 
     /**
-     * Returns the number of {@link android.hardware.usb.UsbInterface}s this device contains.
+     * Returns the number of {@link UsbInterface}s this device contains.
      *
      * @return the number of interfaces
      */
@@ -133,7 +141,7 @@ public class UsbDevice implements Parcelable {
     }
 
     /**
-     * Returns the {@link android.hardware.usb.UsbInterface} at the given index.
+     * Returns the {@link UsbInterface} at the given index.
      *
      * @return the interface
      */
diff --git a/core/java/android/hardware/usb/UsbDeviceConnection.java b/core/java/android/hardware/usb/UsbDeviceConnection.java
index 876287c..a153c0b 100644
--- a/core/java/android/hardware/usb/UsbDeviceConnection.java
+++ b/core/java/android/hardware/usb/UsbDeviceConnection.java
@@ -23,7 +23,8 @@ import java.io.FileDescriptor;
 
 
 /**
- * A class representing a USB device.
+ * This class is used for sending and receiving data and control messages to a USB device.
+ * Instances of this class are created by {@link UsbManager#openDevice}.
  */
 public class UsbDeviceConnection {
 
@@ -48,15 +49,20 @@ public class UsbDeviceConnection {
 
     /**
      * Releases all system resources related to the device.
+     * Once the object is closed it cannot be used again.
+     * The client must call {@link UsbManager#openDevice} again
+     * to retrieve a new instance to reestablish communication with the device.
      */
     public void close() {
         native_close();
     }
 
     /**
-     * Returns an integer file descriptor for the device, or
+     * Returns the native file descriptor for the device, or
      * -1 if the device is not opened.
-     * This is intended for passing to native code to access the device
+     * This is intended for passing to native code to access the device.
+     *
+     * @return the native file descriptor
      */
     public int getFileDescriptor() {
         return native_get_fd();
@@ -65,7 +71,8 @@ public class UsbDeviceConnection {
     /**
      * Claims exclusive access to a {@link android.hardware.usb.UsbInterface}.
      * This must be done before sending or receiving data on any
-     * {@link android.hardware.usb.UsbEndpoint}s belonging to the interface
+     * {@link android.hardware.usb.UsbEndpoint}s belonging to the interface.
+     *
      * @param intf the interface to claim
      * @param force true to disconnect kernel driver if necessary
      * @return true if the interface was successfully claimed
diff --git a/core/java/android/hardware/usb/UsbEndpoint.java b/core/java/android/hardware/usb/UsbEndpoint.java
index bc2c2c1..753a447 100644
--- a/core/java/android/hardware/usb/UsbEndpoint.java
+++ b/core/java/android/hardware/usb/UsbEndpoint.java
@@ -21,7 +21,14 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * A class representing an endpoint on a {@link android.hardware.usb.UsbInterface}.
+ * A class representing an endpoint on a {@link UsbInterface}.
+ * Endpoints are the channels for sending and receiving data over USB.
+ * Typically bulk endpoints are used for sending non-trivial amounts of data.
+ * Interrupt endpoints are used for sending small amounts of data, typically events,
+ * separately from the main data streams.
+ * The endpoint zero is a special endpoint for control messages sent from the host
+ * to device.
+ * Isochronous endpoints are currently unsupported.
  */
 public class UsbEndpoint implements Parcelable {
 
@@ -43,6 +50,10 @@ public class UsbEndpoint implements Parcelable {
 
     /**
      * Returns the endpoint's address field.
+     * The address is a bitfield containing both the endpoint number
+     * as well as the data direction of the endpoint.
+     * the endpoint number and direction can also be accessed via
+     * {@link #getEndpointNumber} and {@link #getDirection}.
      *
      * @return the endpoint's address
      */
@@ -61,10 +72,12 @@ public class UsbEndpoint implements Parcelable {
 
     /**
      * Returns the endpoint's direction.
-     * Returns {@link android.hardware.usb.UsbConstants#USB_DIR_OUT}
+     * Returns {@link UsbConstants#USB_DIR_OUT}
      * if the direction is host to device, and
-     * {@link android.hardware.usb.UsbConstants#USB_DIR_IN} if the
+     * {@link UsbConstants#USB_DIR_IN} if the
      * direction is device to host.
+     * @see {@link UsbConstants#USB_DIR_IN}
+     * @see {@link UsbConstants#USB_DIR_OUT}
      *
      * @return the endpoint's direction
      */
@@ -85,10 +98,10 @@ public class UsbEndpoint implements Parcelable {
      * Returns the endpoint's type.
      * Possible results are:
      * <ul>
-     * <li>{@link android.hardware.usb.UsbConstants#USB_ENDPOINT_XFER_CONTROL} (endpoint zero)
-     * <li>{@link android.hardware.usb.UsbConstants#USB_ENDPOINT_XFER_ISOC} (isochronous endpoint)
-     * <li>{@link android.hardware.usb.UsbConstants#USB_ENDPOINT_XFER_BULK} (bulk endpoint)
-     * <li>{@link android.hardware.usb.UsbConstants#USB_ENDPOINT_XFER_INT} (interrupt endpoint)
+     * <li>{@link UsbConstants#USB_ENDPOINT_XFER_CONTROL} (endpoint zero)
+     * <li>{@link UsbConstants#USB_ENDPOINT_XFER_ISOC} (isochronous endpoint)
+     * <li>{@link UsbConstants#USB_ENDPOINT_XFER_BULK} (bulk endpoint)
+     * <li>{@link UsbConstants#USB_ENDPOINT_XFER_INT} (interrupt endpoint)
      * </ul>
      *
      * @return the endpoint's type
diff --git a/core/java/android/hardware/usb/UsbInterface.java b/core/java/android/hardware/usb/UsbInterface.java
index 2b4c7c0..3b51063 100644
--- a/core/java/android/hardware/usb/UsbInterface.java
+++ b/core/java/android/hardware/usb/UsbInterface.java
@@ -21,7 +21,11 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * A class representing an interface on a {@link android.hardware.usb.UsbDevice}.
+ * A class representing an interface on a {@link UsbDevice}.
+ * USB devices can have one or more interfaces, each one providing a different
+ * piece of functionality, separate from the other interfaces.
+ * An interface will have one or more {@link UsbEndpoint}s, which are the
+ * channels by which the host transfers data with the device.
  */
 public class UsbInterface implements Parcelable {
 
@@ -46,6 +50,7 @@ public class UsbInterface implements Parcelable {
 
     /**
      * Returns the interface's ID field.
+     * This is an integer that uniquely identifies the interface on the device.
      *
      * @return the interface's ID
      */
@@ -55,8 +60,7 @@ public class UsbInterface implements Parcelable {
 
     /**
      * Returns the interface's class field.
-     * Some useful constants for USB classes can be found in
-     * {@link android.hardware.usb.UsbConstants}
+     * Some useful constants for USB classes can be found in {@link UsbConstants}
      *
      * @return the interface's class
      */
diff --git a/core/java/android/hardware/usb/UsbManager.java b/core/java/android/hardware/usb/UsbManager.java
index 7bf278a..60b37a1 100644
--- a/core/java/android/hardware/usb/UsbManager.java
+++ b/core/java/android/hardware/usb/UsbManager.java
@@ -31,7 +31,8 @@ import java.io.IOException;
 import java.util.HashMap;
 
 /**
- * This class allows you to access the state of USB, both in host and device mode.
+ * This class allows you to access the state of USB and communicate with USB devices.
+ * Currently only host mode is supported in the public API.
  *
  * <p>You can obtain an instance of this class by calling
  * {@link android.content.Context#getSystemService(java.lang.String) Context.getSystemService()}.
diff --git a/core/java/android/hardware/usb/UsbRequest.java b/core/java/android/hardware/usb/UsbRequest.java
index 5fe6c8c..2252248 100644
--- a/core/java/android/hardware/usb/UsbRequest.java
+++ b/core/java/android/hardware/usb/UsbRequest.java
@@ -24,8 +24,13 @@ import java.nio.ByteBuffer;
  * A class representing USB request packet.
  * This can be used for both reading and writing data to or from a
  * {@link android.hardware.usb.UsbDeviceConnection}.
- * UsbRequests are sent asynchronously via {@link #queue} and the results
- * are read by {@link android.hardware.usb.UsbDeviceConnection#requestWait}.
+ * UsbRequests can be used to transfer data on bulk and interrupt endpoints.
+ * Requests on bulk endpoints can be sent synchronously via {@link UsbDeviceConnection#bulkTransfer}
+ * or asynchronously via {@link #queue} and {@link UsbDeviceConnection#requestWait}.
+ * Requests on interrupt endpoints are only send and received asynchronously.
+ *
+ * <p>Requests on endpoint zero are not supported by this class;
+ * use {@link UsbDeviceConnection#controlTransfer} for endpoint zero requests instead.
  */
 public class UsbRequest {