diff options
| -rw-r--r-- | core/java/android/hardware/usb/UsbAccessory.java | 18 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbConstants.java | 139 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbDevice.java | 20 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbDeviceConnection.java | 15 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbEndpoint.java | 27 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbInterface.java | 10 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbManager.java | 3 | ||||
| -rw-r--r-- | core/java/android/hardware/usb/UsbRequest.java | 9 | ||||
| -rw-r--r-- | media/java/android/mtp/MtpDevice.java | 34 | ||||
| -rw-r--r-- | media/java/android/mtp/MtpStorageInfo.java | 7 |
10 files changed, 236 insertions, 46 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 { diff --git a/media/java/android/mtp/MtpDevice.java b/media/java/android/mtp/MtpDevice.java index af37c9e..47bb8c9 100644 --- a/media/java/android/mtp/MtpDevice.java +++ b/media/java/android/mtp/MtpDevice.java @@ -61,7 +61,9 @@ public final class MtpDevice { } /** - * Closes all resources related to the MtpDevice object + * Closes all resources related to the MtpDevice object. + * After this is called, the object can not be used until {@link #open} is called again + * with a new {@link android.hardware.usb.UsbDeviceConnection}. */ public void close() { native_close(); @@ -78,6 +80,8 @@ public final class MtpDevice { /** * Returns the name of the USB device + * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceName} + * for the device's {@link android.hardware.usb.UsbDevice} * * @return the device name */ @@ -86,7 +90,9 @@ public final class MtpDevice { } /** - * Returns the ID of the USB device + * Returns the USB ID of the USB device. + * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceId} + * for the device's {@link android.hardware.usb.UsbDevice} * * @return the device ID */ @@ -100,7 +106,7 @@ public final class MtpDevice { } /** - * Returns the {@link android.mtp.MtpDeviceInfo} for this device + * Returns the {@link MtpDeviceInfo} for this device * * @return the device info */ @@ -110,8 +116,9 @@ public final class MtpDevice { /** * Returns the list of IDs for all storage units on this device + * Information about each storage unit can be accessed via {@link #getStorageInfo}. * - * @return the storage IDs + * @return the list of storage IDs */ public int[] getStorageIds() { return native_get_storage_ids(); @@ -120,6 +127,7 @@ public final class MtpDevice { /** * Returns the list of object handles for all objects on the given storage unit, * with the given format and parent. + * Information about each object can be accessed via {@link #getObjectInfo}. * * @param storageId the storage unit to query * @param format the format of the object to return, or zero for all formats @@ -132,10 +140,12 @@ public final class MtpDevice { /** * Returns the data for an object as a byte array. + * This call may block for an arbitrary amount of time depending on the size + * of the data and speed of the devices. * * @param objectHandle handle of the object to read * @param objectSize the size of the object (this should match - * {@link android.mtp.MtpObjectInfo#getCompressedSize} + * {@link MtpObjectInfo#getCompressedSize} * @return the object's data, or null if reading fails */ public byte[] getObject(int objectHandle, int objectSize) { @@ -144,6 +154,10 @@ public final class MtpDevice { /** * Returns the thumbnail data for an object as a byte array. + * The size and format of the thumbnail data can be determined via + * {@link MtpObjectInfo#getThumbCompressedSize} and + * {@link MtpObjectInfo#getThumbFormat}. + * For typical devices the format is JPEG. * * @param objectHandle handle of the object to read * @return the object's thumbnail, or null if reading fails @@ -153,7 +167,7 @@ public final class MtpDevice { } /** - * Retrieves the {@link android.mtp.MtpStorageInfo} for a storage unit. + * Retrieves the {@link MtpStorageInfo} for a storage unit. * * @param storageId the ID of the storage unit * @return the MtpStorageInfo @@ -163,7 +177,7 @@ public final class MtpDevice { } /** - * Retrieves the {@link android.mtp.MtpObjectInfo} for an object. + * Retrieves the {@link MtpObjectInfo} for an object. * * @param objectHandle the handle of the object * @return the MtpObjectInfo @@ -173,7 +187,9 @@ public final class MtpDevice { } /** - * Deletes an object on the device. + * Deletes an object on the device. This call may block, since + * deleting a directory containing many files may take a long time + * on some devices. * * @param objectHandle handle of the object to delete * @return true if the deletion succeeds @@ -204,6 +220,8 @@ public final class MtpDevice { /** * Copies the data for an object to a file in external storage. + * This call may block for an arbitrary amount of time depending on the size + * of the data and speed of the devices. * * @param objectHandle handle of the object to read * @param destPath path to destination for the file transfer. diff --git a/media/java/android/mtp/MtpStorageInfo.java b/media/java/android/mtp/MtpStorageInfo.java index 09736a8..d1b86fc 100644 --- a/media/java/android/mtp/MtpStorageInfo.java +++ b/media/java/android/mtp/MtpStorageInfo.java @@ -34,7 +34,8 @@ public final class MtpStorageInfo { } /** - * Returns the storage ID for the storage unit + * Returns the storage ID for the storage unit. + * The storage ID uniquely identifies the storage unit on the MTP device. * * @return the storage ID */ @@ -61,7 +62,9 @@ public final class MtpStorageInfo { } /** - * Returns the description string for the storage unit + * Returns the description string for the storage unit. + * This is typically displayed to the user in the user interface on the + * MTP host. * * @return the storage unit description */ |