Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5dd4e6cf authored by Philip P. Moltmann's avatar Philip P. Moltmann
Browse files

Clarify the behavior of UsbRequest 

This is obviously just about describing a bad behavior. In the next step
these methods should be deprecated and replaced with versions that deal
with ByteBuffers appropriately.

Bug: 31050148
Test: Test that enshrines the documented behavior is submitted alongside
      this change
Change-Id: If250a8bbd636784355e839a1638d52f3bbe9b83d
parent 4b331cc1

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

+13 −6
Original line number Diff line number Diff line
@@ -24,7 +24,7 @@ import android.os.ParcelFileDescriptor; 
import dalvik.system.CloseGuard;



import java.io.FileDescriptor;



import java.nio.ByteBuffer;



/**

 * This class is used for sending and receiving data and control messages to a USB device.
@@ -257,13 +257,20 @@ public class UsbDeviceConnection { 


    /**

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

     * <p>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.</p>

     * <p>Position and array offset of the request's buffer are ignored and assumed to be 0. The

     * position will be set to the number of bytes read/written.</p>

     *

     * @return a completed USB request, or null if an error occurred

     *

     * @throws IllegalArgumentException if the number of bytes read or written is more than the

     *                                  limit of the request's buffer. The number of bytes is

     *                                  determined by the {@code length} parameter of

     *                                  {@link UsbRequest#queue(ByteBuffer, int)}

     */

    public UsbRequest requestWait() {

        UsbRequest request = native_request_wait();

core/java/android/hardware/usb/UsbRequest.java

+14 −9
Original line number Diff line number Diff line
@@ -17,6 +17,7 @@ 
package android.hardware.usb;



import android.util.Log;

import com.android.internal.util.Preconditions;

import dalvik.system.CloseGuard;



import java.nio.ByteBuffer;
@@ -66,7 +67,7 @@ public class UsbRequest { 
     */

    public boolean initialize(UsbDeviceConnection connection, UsbEndpoint endpoint) {

        mEndpoint = endpoint;

        mConnection = connection;

        mConnection = Preconditions.checkNotNull(connection);



        boolean wasInitialized = native_init(connection, endpoint.getAddress(),

                endpoint.getAttributes(), endpoint.getMaxPacketSize(), endpoint.getInterval());
@@ -137,15 +138,16 @@ public class UsbRequest { 


    /**

     * 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.usb.UsbDeviceConnection#requestWait}

     * <p>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.usb.UsbDeviceConnection#requestWait}</p>

     *

     * @param buffer the buffer containing the bytes to write, or location to store the results of a

     *               read. Position and array offset will be ignored and assumed to be 0. Limit and

     *               capacity will be ignored.

     * @param length number of bytes to read or write.

     *

     * @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) {
@@ -155,6 +157,9 @@ public class UsbRequest { 
        mBuffer = buffer;

        mLength = length;



        // Note: On a buffer slice we lost the capacity information about the underlying buffer,

        // hence we cannot check if the access would be a data leak/memory corruption.



        boolean result;

        if (buffer.isDirect()) {

            result = native_queue_direct(buffer, length, out);