drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve Javadoc for USB Manager and MTP/PTP support.

Browse Source 
Bug: 4091519

Change-Id: Ida79593d5a984f7ffd0934ae7bded23b8faf9eef
Signed-off-by: Mike Lockwood <lockwood@android.com>
This commit is contained in:
Mike Lockwood
2011-04-01 14:00:08 -04:00
parent 1ccdc23571
commit 11dd5ae97b
10 changed files with 236 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
core/java/android/hardware/usb/UsbAccessory.java
View File

@ -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
*/

137
core/java/android/hardware/usb/UsbConstants.java
View File

@ -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;
}

20
core/java/android/hardware/usb/UsbDevice.java
View File

@ -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
*/

15
core/java/android/hardware/usb/UsbDeviceConnection.java
View File

@ -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

27
core/java/android/hardware/usb/UsbEndpoint.java
View File

@ -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

10
core/java/android/hardware/usb/UsbInterface.java
View File

@ -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
*/

3
core/java/android/hardware/usb/UsbManager.java
View File

@ -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()}.

9
core/java/android/hardware/usb/UsbRequest.java
View File

@ -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 {

34
media/java/android/mtp/MtpDevice.java
View File

@ -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.

7
media/java/android/mtp/MtpStorageInfo.java
View File

@ -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
*/