Improve Javadoc for USB Manager and MTP/PTP support. (11dd5ae9) · Commits · e / os / android_frameworks_base

core/java/android/hardware/usb/UsbAccessory.java

+16 −2

Original line number	Diff line number	Diff line
		@@ -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
		*/

core/java/android/hardware/usb/UsbConstants.java

+128 −11

Original line number	Diff line number	Diff line
		@@ -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;
		}

core/java/android/hardware/usb/UsbDevice.java

+14 −6

Original line number	Diff line number	Diff line
		@@ -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
		*/

core/java/android/hardware/usb/UsbDeviceConnection.java

+11 −4

Original line number	Diff line number	Diff line
		@@ -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

core/java/android/hardware/usb/UsbEndpoint.java

+20 −7

Original line number	Diff line number	Diff line
		@@ -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