New APIs for USB host support:

UsbManager:
- is now a service retrievable via Context.getSystemService(Context.USB_SERVICE).
- provides support for returning a list all connected USB devices
- broadcasts ACTION_USB_DEVICE_ATTACHED and USB_DEVICE_DETACHED when devices
  are added and removed from the USB host bus

UsbDevice:
- represents an attached USB device.

UsbInterface:
- represents an interface on a USB device
- devices may have multiple interfaces if they provide multiple
   sets of functionality (for example, android phones typically have interfaces
   for both USB mass storage and adb)

UsbEndpoint:
- represents an endpoint on a USB interface
- endpoints are used for sending or receiving data
  (only in one or the other direction)

UsbRequest:
- encapsulates a send or receive request to be sent over an endpoint

Change-Id: Ieef3e434c62760770ea839070cf5eba1a705967a
Signed-off-by: Mike Lockwood <lockwood@android.com>

1 files changed, 177 insertions, 0 deletions

diff --git a/core/java/android/hardware/UsbRequest.java b/core/java/android/hardware/UsbRequest.java
new file mode 100644
index 0000000..ae3a289
--- /dev/null
+++ b/core/java/android/hardware/UsbRequest.java
@@ -0,0 +1,177 @@
+/*
+ * Copyright (C) 2010 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware;
+
+import android.util.Log;
+
+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.UsbDevice}.
+ * UsbRequests are sent asynchronously via {@link #queue} and the results
+ * are read by {@link android.hardware.UsbDevice#requestWait}.
+ */
+public class UsbRequest {
+
+    private static final String TAG = "UsbRequest";
+
+    // used by the JNI code
+    private int mNativeContext;
+
+    private UsbEndpoint mEndpoint;
+
+    // for temporarily saving current buffer across queue and dequeue
+    private ByteBuffer mBuffer;
+    private int mLength;
+
+    // for client use
+    private Object mClientData;
+
+    public UsbRequest() {
+    }
+
+    /**
+     * Initializes the request so it can read or write data on the given endpoint.
+     * Whether the request allows reading or writing depends on the direction of the endpoint.
+     *
+     * @param endpoint the endpoint to be used for this request.
+     * @return true if the request was successfully opened.
+     */
+    public boolean initialize(UsbEndpoint endpoint) {
+        mEndpoint = endpoint;
+        return native_init(endpoint.getDevice(),
+                endpoint.getAddress(), endpoint.getAttributes(),
+                endpoint.getMaxPacketSize(), endpoint.getInterval());
+    }
+
+    /**
+     * Releases all resources related to this request.
+     */
+    public void close() {
+        mEndpoint = null;
+        native_close();
+    }
+
+    @Override
+    protected void finalize() throws Throwable {
+        try {
+            if (mEndpoint != null) {
+                Log.v(TAG, "endpoint still open in finalize(): " + this);
+                close();
+            }
+        } finally {
+            super.finalize();
+        }
+    }
+
+    /**
+     * Returns the endpoint for the request, or null if the request is not opened.
+     *
+     * @return the request's endpoint
+     */
+    public UsbEndpoint getEndpoint() {
+        return mEndpoint;
+    }
+
+    /**
+     * Returns the client data for the request.
+     * This can be used in conjunction with {@link #setClientData}
+     * to associate another object with this request, which can be useful for
+     * maintaining state between calls to {@link #queue} and
+     * {@link android.hardware.UsbDevice#requestWait}
+     *
+     * @return the client data for the request
+     */
+    public Object getClientData() {
+        return mClientData;
+    }
+
+    /**
+     * Sets the client data for the request.
+     * This can be used in conjunction with {@link #getClientData}
+     * to associate another object with this request, which can be useful for
+     * maintaining state between calls to {@link #queue} and
+     * {@link android.hardware.UsbDevice#requestWait}
+     *
+     * @param data the client data for the request
+     */
+    public void setClientData(Object data) {
+        mClientData = data;
+    }
+
+    /**
+     * Queues the request to send or receive data on its endpoint.
+     * For OUT endpoints, the given buffer data will be sent on the endpoint.
+     * For IN endpoints, the endpoint will attempt to read the given number of bytes
+     * into the specified buffer.
+     * If the queueing operation is successful, we return true and the result will be
+     * returned via {@link android.hardware.UsbDevice#requestWait}
+     *
+     * @param buffer the buffer containing the bytes to write, or location to store
+     * the results of a read
+     * @param length number of bytes to read or write
+     * @return true if the queueing operation succeeded
+     */
+    public boolean queue(ByteBuffer buffer, int length) {
+        boolean out = (mEndpoint.getDirection() == UsbConstants.USB_DIR_OUT);
+        boolean result;
+        if (buffer.isDirect()) {
+            result = native_queue_direct(buffer, length, out);
+        } else if (buffer.hasArray()) {
+            result = native_queue_array(buffer.array(), length, out);
+        } else {
+            throw new IllegalArgumentException("buffer is not direct and has no array");
+        }
+        if (result) {
+            // save our buffer for when the request has completed
+            mBuffer = buffer;
+            mLength = length;
+        }
+        return result;
+    }
+
+    /* package */ void dequeue() {
+        boolean out = (mEndpoint.getDirection() == UsbConstants.USB_DIR_OUT);
+        if (mBuffer.isDirect()) {
+            native_dequeue_direct();
+        } else {
+            native_dequeue_array(mBuffer.array(), mLength, out);
+        }
+        mBuffer = null;
+        mLength = 0;
+    }
+
+    /**
+     * Cancels a pending queue operation.
+     *
+     * @return true if cancelling succeeded
+     */
+    public boolean cancel() {
+        return native_cancel();
+    }
+
+    private native boolean native_init(UsbDevice device, int ep_address, int ep_attributes,
+            int ep_max_packet_size, int ep_interval);
+    private native void native_close();
+    private native boolean native_queue_array(byte[] buffer, int length, boolean out);
+    private native void native_dequeue_array(byte[] buffer, int length, boolean out);
+    private native boolean native_queue_direct(ByteBuffer buffer, int length, boolean out);
+    private native void native_dequeue_direct();
+    private native boolean native_cancel();
+}