UsbDevice: Move IO related methods to new UsbDeviceConnection class

UsbDevice is now just an immutable parcelable object like UsbInterface and
UsbEndpoint.
All IO related functionality is now contained in UsbDeviceConnection
and UsbRequest.

Bug: 4067029

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

6 files changed, 203 insertions, 219 deletions

diff --git a/core/java/android/hardware/usb/UsbDevice.java b/core/java/android/hardware/usb/UsbDevice.java
index 39254b38..9e536a7 100644
--- a/core/java/android/hardware/usb/UsbDevice.java
+++ b/core/java/android/hardware/usb/UsbDevice.java
@@ -19,33 +19,24 @@ package android.hardware.usb;
 import android.os.Bundle;
 import android.os.Parcel;
 import android.os.Parcelable;
-import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
 import java.io.FileDescriptor;
 
-
 /**
  * A class representing a USB device.
  */
-public final class UsbDevice implements Parcelable {
+public class UsbDevice implements Parcelable {
 
     private static final String TAG = "UsbDevice";
 
-    private String mName;
-    private int mVendorId;
-    private int mProductId;
-    private int mClass;
-    private int mSubclass;
-    private int mProtocol;
-    private Parcelable[] mInterfaces;
-
-    // used by the JNI code
-    private int mNativeContext;
-
-    private UsbDevice() {
-    }
-
+    private final String mName;
+    private final int mVendorId;
+    private final int mProductId;
+    private final int mClass;
+    private final int mSubclass;
+    private final int mProtocol;
+    private final Parcelable[] mInterfaces;
 
     /**
      * UsbDevice should only be instantiated by UsbService implementation
@@ -150,114 +141,6 @@ public final class UsbDevice implements Parcelable {
         return (UsbInterface)mInterfaces[index];
     }
 
-    /* package */ boolean open(ParcelFileDescriptor pfd) {
-        return native_open(mName, pfd.getFileDescriptor());
-    }
-
-    /**
-     * Releases all system resources related to the device.
-     */
-    public void close() {
-        native_close();
-    }
-
-    /**
-     * Returns an integer 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
-     */
-    public int getFileDescriptor() {
-        return native_get_fd();
-    }
-
-    /**
-     * 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
-     * @param intf the interface to claim
-     * @param force true to disconnect kernel driver if necessary
-     * @return true if the interface was successfully claimed
-     */
-    public boolean claimInterface(UsbInterface intf, boolean force) {
-        return native_claim_interface(intf.getId(), force);
-    }
-
-    /**
-     * Releases exclusive access to a {@link android.hardware.usb.UsbInterface}.
-     *
-     * @return true if the interface was successfully released
-     */
-    public boolean releaseInterface(UsbInterface intf) {
-        return native_release_interface(intf.getId());
-    }
-
-    /**
-     * Performs a control transaction on endpoint zero for this device.
-     * The direction of the transfer is determined by the request type.
-     * If requestType & {@link UsbConstants#USB_ENDPOINT_DIR_MASK} is
-     * {@link UsbConstants#USB_DIR_OUT}, then the transfer is a write,
-     * and if it is {@link UsbConstants#USB_DIR_IN}, then the transfer
-     * is a read.
-     *
-     * @param requestType request type for this transaction
-     * @param request request ID for this transaction
-     * @param value value field for this transaction
-     * @param index index field for this transaction
-     * @param buffer buffer for data portion of transaction,
-     * or null if no data needs to be sent or received
-     * @param length the length of the data to send or receive
-     * @param timeout in milliseconds
-     * @return length of data transferred (or zero) for success,
-     * or negative value for failure
-     */
-    public int controlTransfer(int requestType, int request, int value,
-            int index, byte[] buffer, int length, int timeout) {
-        return native_control_request(requestType, request, value, index, buffer, length, timeout);
-    }
-
-    /**
-     * Performs a bulk transaction on the given endpoint.
-     * The direction of the transfer is determined by the direction of the endpoint
-     *
-     * @param endpoint the endpoint for this transaction
-     * @param buffer buffer for data to send or receive,
-     * @param length the length of the data to send or receive
-     * @param timeout in milliseconds
-     * @return length of data transferred (or zero) for success,
-     * or negative value for failure
-     */
-    public int bulkTransfer(UsbEndpoint endpoint, byte[] buffer, int length, int timeout) {
-        return native_bulk_request(endpoint.getAddress(), buffer, length, timeout);
-    }
-
-    /**
-     * Waits for the result of a {@link android.hardware.usb.UsbRequest#queue} operation
-     * Note that this may return requests queued on multiple 
-     * {@link android.hardware.usb.UsbEndpoint}s.
-     * When multiple endpoints are in use, {@link android.hardware.usb.UsbRequest#getEndpoint} and
-     * {@link android.hardware.usb.UsbRequest#getClientData} can be useful in determining
-     * how to process the result of this function.
-     *
-     * @return a completed USB request, or null if an error occurred
-     */
-    public UsbRequest requestWait() {
-        UsbRequest request = native_request_wait();
-        if (request != null) {
-            request.dequeue();
-        }
-        return request;
-    }
-
-    /**
-     * Returns the serial number for the device.
-     * This will return null if the device has not been opened.
-     *
-     * @return the device serial number
-     */
-    public String getSerial() {
-        return native_get_serial();
-    }
-
     @Override
     public boolean equals(Object o) {
         if (o instanceof UsbDevice) {
@@ -292,11 +175,7 @@ public final class UsbDevice implements Parcelable {
             int subClass = in.readInt();
             int protocol = in.readInt();
             Parcelable[] interfaces = in.readParcelableArray(UsbInterface.class.getClassLoader());
-            UsbDevice result = new UsbDevice(name, vendorId, productId, clasz, subClass, protocol, interfaces);
-            for (int i = 0; i < interfaces.length; i++) {
-                ((UsbInterface)interfaces[i]).setDevice(result);
-            }
-            return result;
+            return new UsbDevice(name, vendorId, productId, clasz, subClass, protocol, interfaces);
         }
 
         public UsbDevice[] newArray(int size) {
@@ -326,17 +205,6 @@ public final class UsbDevice implements Parcelable {
         return native_get_device_name(id);
     }
 
-    private native boolean native_open(String deviceName, FileDescriptor pfd);
-    private native void native_close();
-    private native int native_get_fd();
-    private native boolean native_claim_interface(int interfaceID, boolean force);
-    private native boolean native_release_interface(int interfaceID);
-    private native int native_control_request(int requestType, int request, int value,
-            int index, byte[] buffer, int length, int timeout);
-    private native int native_bulk_request(int endpoint, byte[] buffer, int length, int timeout);
-    private native UsbRequest native_request_wait();
-    private native String native_get_serial();
-
     private static native int native_get_device_id(String name);
     private static native String native_get_device_name(int id);
 }
diff --git a/core/java/android/hardware/usb/UsbDeviceConnection.java b/core/java/android/hardware/usb/UsbDeviceConnection.java
new file mode 100644
index 0000000..876287c
--- /dev/null
+++ b/core/java/android/hardware/usb/UsbDeviceConnection.java
@@ -0,0 +1,163 @@
+/*
+ * Copyright (C) 2011 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.usb;
+
+import android.os.ParcelFileDescriptor;
+import android.util.Log;
+
+import java.io.FileDescriptor;
+
+
+/**
+ * A class representing a USB device.
+ */
+public class UsbDeviceConnection {
+
+    private static final String TAG = "UsbDeviceConnection";
+
+    private final UsbDevice mDevice;
+
+    // used by the JNI code
+    private int mNativeContext;
+
+    /**
+     * UsbDevice should only be instantiated by UsbService implementation
+     * @hide
+     */
+    public UsbDeviceConnection(UsbDevice device) {
+        mDevice = device;
+    }
+
+    /* package */ boolean open(String name, ParcelFileDescriptor pfd) {
+        return native_open(name, pfd.getFileDescriptor());
+    }
+
+    /**
+     * Releases all system resources related to the device.
+     */
+    public void close() {
+        native_close();
+    }
+
+    /**
+     * Returns an integer 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
+     */
+    public int getFileDescriptor() {
+        return native_get_fd();
+    }
+
+    /**
+     * 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
+     * @param intf the interface to claim
+     * @param force true to disconnect kernel driver if necessary
+     * @return true if the interface was successfully claimed
+     */
+    public boolean claimInterface(UsbInterface intf, boolean force) {
+        return native_claim_interface(intf.getId(), force);
+    }
+
+    /**
+     * Releases exclusive access to a {@link android.hardware.usb.UsbInterface}.
+     *
+     * @return true if the interface was successfully released
+     */
+    public boolean releaseInterface(UsbInterface intf) {
+        return native_release_interface(intf.getId());
+    }
+
+    /**
+     * Performs a control transaction on endpoint zero for this device.
+     * The direction of the transfer is determined by the request type.
+     * If requestType & {@link UsbConstants#USB_ENDPOINT_DIR_MASK} is
+     * {@link UsbConstants#USB_DIR_OUT}, then the transfer is a write,
+     * and if it is {@link UsbConstants#USB_DIR_IN}, then the transfer
+     * is a read.
+     *
+     * @param requestType request type for this transaction
+     * @param request request ID for this transaction
+     * @param value value field for this transaction
+     * @param index index field for this transaction
+     * @param buffer buffer for data portion of transaction,
+     * or null if no data needs to be sent or received
+     * @param length the length of the data to send or receive
+     * @param timeout in milliseconds
+     * @return length of data transferred (or zero) for success,
+     * or negative value for failure
+     */
+    public int controlTransfer(int requestType, int request, int value,
+            int index, byte[] buffer, int length, int timeout) {
+        return native_control_request(requestType, request, value, index, buffer, length, timeout);
+    }
+
+    /**
+     * Performs a bulk transaction on the given endpoint.
+     * The direction of the transfer is determined by the direction of the endpoint
+     *
+     * @param endpoint the endpoint for this transaction
+     * @param buffer buffer for data to send or receive,
+     * @param length the length of the data to send or receive
+     * @param timeout in milliseconds
+     * @return length of data transferred (or zero) for success,
+     * or negative value for failure
+     */
+    public int bulkTransfer(UsbEndpoint endpoint, byte[] buffer, int length, int timeout) {
+        return native_bulk_request(endpoint.getAddress(), buffer, length, timeout);
+    }
+
+    /**
+     * Waits for the result of a {@link android.hardware.usb.UsbRequest#queue} operation
+     * Note that this may return requests queued on multiple 
+     * {@link android.hardware.usb.UsbEndpoint}s.
+     * When multiple endpoints are in use, {@link android.hardware.usb.UsbRequest#getEndpoint} and
+     * {@link android.hardware.usb.UsbRequest#getClientData} can be useful in determining
+     * how to process the result of this function.
+     *
+     * @return a completed USB request, or null if an error occurred
+     */
+    public UsbRequest requestWait() {
+        UsbRequest request = native_request_wait();
+        if (request != null) {
+            request.dequeue();
+        }
+        return request;
+    }
+
+    /**
+     * Returns the serial number for the device.
+     * This will return null if the device has not been opened.
+     *
+     * @return the device serial number
+     */
+    public String getSerial() {
+        return native_get_serial();
+    }
+
+    private native boolean native_open(String deviceName, FileDescriptor pfd);
+    private native void native_close();
+    private native int native_get_fd();
+    private native boolean native_claim_interface(int interfaceID, boolean force);
+    private native boolean native_release_interface(int interfaceID);
+    private native int native_control_request(int requestType, int request, int value,
+            int index, byte[] buffer, int length, int timeout);
+    private native int native_bulk_request(int endpoint, byte[] buffer, int length, int timeout);
+    private native UsbRequest native_request_wait();
+    private native String native_get_serial();
+}
diff --git a/core/java/android/hardware/usb/UsbEndpoint.java b/core/java/android/hardware/usb/UsbEndpoint.java
index a48d88f..bc2c2c1 100644
--- a/core/java/android/hardware/usb/UsbEndpoint.java
+++ b/core/java/android/hardware/usb/UsbEndpoint.java
@@ -23,16 +23,12 @@ import android.os.Parcelable;
 /**
  * A class representing an endpoint on a {@link android.hardware.usb.UsbInterface}.
  */
-public final class UsbEndpoint implements Parcelable {
+public class UsbEndpoint implements Parcelable {
 
-    private int mAddress;
-    private int mAttributes;
-    private int mMaxPacketSize;
-    private int mInterval;
-    private UsbInterface mInterface;
-
-    private UsbEndpoint() {
-    }
+    private final int mAddress;
+    private final int mAttributes;
+    private final int mMaxPacketSize;
+    private final int mInterval;
 
     /**
      * UsbEndpoint should only be instantiated by UsbService implementation
@@ -119,29 +115,6 @@ public final class UsbEndpoint implements Parcelable {
         return mInterval;
     }
 
-    /**
-     * Returns the {@link android.hardware.usb.UsbInterface} this endpoint belongs to.
-     *
-     * @return the endpoint's interface
-     */
-    public UsbInterface getInterface() {
-        return mInterface;
-    }
-
-    /**
-     * Returns the {@link android.hardware.usb.UsbDevice} this endpoint belongs to.
-     *
-     * @return the endpoint's device
-     */
-    public UsbDevice getDevice() {
-        return mInterface.getDevice();
-    }
-
-    // only used for parcelling
-    /* package */ void setInterface(UsbInterface intf) {
-        mInterface = intf;
-    }
-
     @Override
     public String toString() {
         return "UsbEndpoint[mAddress=" + mAddress + ",mAttributes=" + mAttributes +
diff --git a/core/java/android/hardware/usb/UsbInterface.java b/core/java/android/hardware/usb/UsbInterface.java
index b3b0e81..2b4c7c0 100644
--- a/core/java/android/hardware/usb/UsbInterface.java
+++ b/core/java/android/hardware/usb/UsbInterface.java
@@ -25,15 +25,11 @@ import android.os.Parcelable;
  */
 public class UsbInterface implements Parcelable {
 
-    private int mId;
-    private int mClass;
-    private int mSubclass;
-    private int mProtocol;
-    private UsbDevice mDevice;
-    private Parcelable[] mEndpoints;
-
-    private UsbInterface() {
-    }
+    private final int mId;
+    private final int mClass;
+    private final int mSubclass;
+    private final int mProtocol;
+    private final Parcelable[] mEndpoints;
 
     /**
      * UsbInterface should only be instantiated by UsbService implementation
@@ -104,20 +100,6 @@ public class UsbInterface implements Parcelable {
         return (UsbEndpoint)mEndpoints[index];
     }
 
-    /**
-     * Returns the {@link android.hardware.usb.UsbDevice} this interface belongs to.
-     *
-     * @return the interface's device
-     */
-    public UsbDevice getDevice() {
-        return mDevice;
-    }
-
-    // only used for parcelling
-    /* package */ void setDevice(UsbDevice device) {
-        mDevice = device;
-    }
-
     @Override
     public String toString() {
         return "UsbInterface[mId=" + mId + ",mClass=" + mClass +
@@ -133,11 +115,7 @@ public class UsbInterface implements Parcelable {
             int subClass = in.readInt();
             int protocol = in.readInt();
             Parcelable[] endpoints = in.readParcelableArray(UsbEndpoint.class.getClassLoader());
-            UsbInterface result = new UsbInterface(id, Class, subClass, protocol, endpoints);
-            for (int i = 0; i < endpoints.length; i++) {
-                ((UsbEndpoint)endpoints[i]).setInterface(result);
-            }
-            return result;
+            return new UsbInterface(id, Class, subClass, protocol, endpoints);
         }
 
         public UsbInterface[] newArray(int size) {
diff --git a/core/java/android/hardware/usb/UsbManager.java b/core/java/android/hardware/usb/UsbManager.java
index e80c744..41ede14 100644
--- a/core/java/android/hardware/usb/UsbManager.java
+++ b/core/java/android/hardware/usb/UsbManager.java
@@ -227,19 +227,22 @@ public class UsbManager {
      * @param device the device to open
      * @return true if we successfully opened the device
      */
-    public boolean openDevice(UsbDevice device) {
+    public UsbDeviceConnection openDevice(UsbDevice device) {
         try {
-            ParcelFileDescriptor pfd = mService.openDevice(device.getDeviceName());
-            if (pfd == null) {
-                return false;
+            String deviceName = device.getDeviceName();
+            ParcelFileDescriptor pfd = mService.openDevice(deviceName);
+            if (pfd != null) {
+                UsbDeviceConnection connection = new UsbDeviceConnection(device);
+                boolean result = connection.open(deviceName, pfd);
+                pfd.close();
+                if (result) {
+                    return connection;
+                }
             }
-            boolean result = device.open(pfd);
-            pfd.close();
-            return result;
         } catch (Exception e) {
             Log.e(TAG, "exception in UsbManager.openDevice", e);
-            return false;
         }
+        return null;
     }
 
     /**
diff --git a/core/java/android/hardware/usb/UsbRequest.java b/core/java/android/hardware/usb/UsbRequest.java
index 80085c1..5fe6c8c 100644
--- a/core/java/android/hardware/usb/UsbRequest.java
+++ b/core/java/android/hardware/usb/UsbRequest.java
@@ -23,9 +23,9 @@ 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.UsbDevice}.
+ * {@link android.hardware.usb.UsbDeviceConnection}.
  * UsbRequests are sent asynchronously via {@link #queue} and the results
- * are read by {@link android.hardware.usb.UsbDevice#requestWait}.
+ * are read by {@link android.hardware.usb.UsbDeviceConnection#requestWait}.
  */
 public class UsbRequest {
 
@@ -53,10 +53,9 @@ public class UsbRequest {
      * @param endpoint the endpoint to be used for this request.
      * @return true if the request was successfully opened.
      */
-    public boolean initialize(UsbEndpoint endpoint) {
+    public boolean initialize(UsbDeviceConnection connection, UsbEndpoint endpoint) {
         mEndpoint = endpoint;
-        return native_init(endpoint.getDevice(),
-                endpoint.getAddress(), endpoint.getAttributes(),
+        return native_init(connection, endpoint.getAddress(), endpoint.getAttributes(),
                 endpoint.getMaxPacketSize(), endpoint.getInterval());
     }
 
@@ -94,7 +93,7 @@ public class UsbRequest {
      * 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.usb.UsbDevice#requestWait}
+     * {@link android.hardware.usb.UsbDeviceConnection#requestWait}
      *
      * @return the client data for the request
      */
@@ -107,7 +106,7 @@ public class UsbRequest {
      * 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.usb.UsbDevice#requestWait}
+     * {@link android.hardware.usb.UsbDeviceConnection#requestWait}
      *
      * @param data the client data for the request
      */
@@ -121,7 +120,7 @@ public class UsbRequest {
      * 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.usb.UsbDevice#requestWait}
+     * returned via {@link android.hardware.usb.UsbDeviceConnection#requestWait}
      *
      * @param buffer the buffer containing the bytes to write, or location to store
      * the results of a read
@@ -166,8 +165,8 @@ public class UsbRequest {
         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 boolean native_init(UsbDeviceConnection connection, 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);