https://source.android.com/ 
/*
 * 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.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.SuppressLint;
import android.annotation.SystemApi;
import android.content.Context;
import android.os.Build;
import android.os.ParcelFileDescriptor;

import com.android.internal.util.Preconditions;

import dalvik.system.CloseGuard;

import java.io.FileDescriptor;
import java.nio.BufferOverflowException;
import java.nio.ByteBuffer;
import java.util.concurrent.TimeoutException;


This class is used for sending and receiving data and control messages to a USB device. Instances of this class are created by UsbManager.openDevice. 
/**
 * 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 {

    private static final String TAG = "UsbDeviceConnection";

    private final UsbDevice mDevice;

    private Context mContext;

    // used by the JNI code
    private long mNativeContext;

    private final CloseGuard mCloseGuard = CloseGuard.get();

    
UsbDevice should only be instantiated by UsbService implementation

@hide
/**
     * UsbDevice should only be instantiated by UsbService implementation
     * @hide
     */
    public UsbDeviceConnection(UsbDevice device) {
        mDevice = device;
    }

    /* package */ boolean open(String name, ParcelFileDescriptor pfd, @NonNull Context context) {
        mContext = context.getApplicationContext();
        boolean wasOpened = native_open(name, pfd.getFileDescriptor());

        if (wasOpened) {
            mCloseGuard.open("close");
        }

        return wasOpened;
    }

    
Returns:The application context the connection was created for.
@hide
/**
     * @return The application context the connection was created for.
     *
     * @hide
     */
    public @Nullable Context getContext() {
        return mContext;
    }

    
Releases all system resources related to the device. Once the object is closed it cannot be used again. The client must call UsbManager.openDevice again to retrieve a new instance to reestablish communication with the device. 
/**
     * 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() {
        if (mNativeContext != 0) {
            native_close();
            mCloseGuard.close();
        }
    }

    
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.

Returns:the native file descriptor
/**
     * 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.
     *
     * @return the native file descriptor
     */
    public int getFileDescriptor() {
        return native_get_fd();
    }

    
Returns the raw USB descriptors for the device.
This can be used to access descriptors not supported directly
via the higher level APIs.

Returns:raw USB descriptors
/**
     * Returns the raw USB descriptors for the device.
     * This can be used to access descriptors not supported directly
     * via the higher level APIs.
     *
     * @return raw USB descriptors
     */
    public byte[] getRawDescriptors() {
        return native_get_desc();
    }

    
Claims exclusive access to a UsbInterface. This must be done before sending or receiving data on any UsbEndpoints belonging to the interface. 
Params:
  • intf – the interface to claim
  • force – true to disconnect kernel driver if necessary
Returns:true if the interface was successfully claimed
/**
     * 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 UsbInterface. 
Returns:true if the interface was successfully released
/**
     * 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());
    }

    
Sets the current UsbInterface. Used to select between two interfaces with the same ID but different alternate setting. 
Returns:true if the interface was successfully selected
/**
     * Sets the current {@link android.hardware.usb.UsbInterface}.
     * Used to select between two interfaces with the same ID but different alternate setting.
     *
     * @return true if the interface was successfully selected
     */
    public boolean setInterface(UsbInterface intf) {
        return native_set_interface(intf.getId(), intf.getAlternateSetting());
    }

    
Sets the device's current UsbConfiguration. 
Returns:true if the configuration was successfully set
/**
     * Sets the device's current {@link android.hardware.usb.UsbConfiguration}.
     *
     * @return true if the configuration was successfully set
     */
    public boolean setConfiguration(UsbConfiguration configuration) {
        return native_set_configuration(configuration.getId());
    }

    
Performs a control transaction on endpoint zero for this device. The direction of the transfer is determined by the request type. If requestType & UsbConstants.USB_ENDPOINT_DIR_MASK is UsbConstants.USB_DIR_OUT, then the transfer is a write, and if it is UsbConstants.USB_DIR_IN, then the transfer is a read. 
 This method transfers data starting from index 0 in the buffer. To specify a different offset, use controlTransfer(int, int, int, int, byte[], int, int, int). 


Params:
  • requestType – request type for this transaction
  • request – request ID for this transaction
  • value – value field for this transaction
  • index – index field for this transaction
  • buffer – buffer for data portion of transaction,
or null if no data needs to be sent or received
  • length – the length of the data to send or receive
  • timeout – in milliseconds
Returns:length of data transferred (or zero) for success,
or negative value for failure
/**
     * 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.
     * <p>
     * This method transfers data starting from index 0 in the buffer.
     * To specify a different offset, use
     * {@link #controlTransfer(int, int, int, int, byte[], int, int, int)}.
     * </p>
     *
     * @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 controlTransfer(requestType, request, value, index, buffer, 0, length, timeout);
    }

    
Performs a control transaction on endpoint zero for this device. The direction of the transfer is determined by the request type. If requestType & UsbConstants.USB_ENDPOINT_DIR_MASK is UsbConstants.USB_DIR_OUT, then the transfer is a write, and if it is UsbConstants.USB_DIR_IN, then the transfer is a read. 
Params:
  • requestType – request type for this transaction
  • request – request ID for this transaction
  • value – value field for this transaction
  • index – index field for this transaction
  • buffer – buffer for data portion of transaction,
or null if no data needs to be sent or received
  • offset – the index of the first byte in the buffer to send or receive
  • length – the length of the data to send or receive
  • timeout – in milliseconds
Returns:length of data transferred (or zero) for success,
or negative value for failure
/**
     * 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 offset the index of the first byte in the buffer 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 controlTransfer(int requestType, int request, int value, int index,
            byte[] buffer, int offset, int length, int timeout) {
        checkBounds(buffer, offset, length);
        return native_control_request(requestType, request, value, index,
                buffer, offset, length, timeout);
    }

    
Performs a bulk transaction on the given endpoint.
The direction of the transfer is determined by the direction of the endpoint.

 This method transfers data starting from index 0 in the buffer. To specify a different offset, use bulkTransfer(UsbEndpoint, byte[], int, int, int). 


Params:
  • endpoint – the endpoint for this transaction
  • buffer – buffer for data to send or receive; can be null to wait for next transaction without reading data
  • length – the length of the data to send or receive. Before 28, a value larger than 16384 bytes would be truncated down to 16384. In API 28 and after, any value of length is valid.
  • timeout – in milliseconds, 0 is infinite
Returns:length of data transferred (or zero) for success,
or negative value for failure
/**
     * Performs a bulk transaction on the given endpoint.
     * The direction of the transfer is determined by the direction of the endpoint.
     * <p>
     * This method transfers data starting from index 0 in the buffer.
     * To specify a different offset, use
     * {@link #bulkTransfer(UsbEndpoint, byte[], int, int, int)}.
     * </p>
     *
     * @param endpoint the endpoint for this transaction
     * @param buffer buffer for data to send or receive; can be {@code null} to wait for next
     *               transaction without reading data
     * @param length the length of the data to send or receive. Before
     *               {@value Build.VERSION_CODES#P}, a value larger than 16384 bytes
     *               would be truncated down to 16384. In API {@value Build.VERSION_CODES#P}
     *               and after, any value of length is valid.
     * @param timeout in milliseconds, 0 is infinite
     * @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 bulkTransfer(endpoint, buffer, 0, length, timeout);
    }

    
Performs a bulk transaction on the given endpoint.
The direction of the transfer is determined by the direction of the endpoint.

Params:
  • endpoint – the endpoint for this transaction
  • buffer – buffer for data to send or receive
  • offset – the index of the first byte in the buffer to send or receive
  • length – the length of the data to send or receive. Before 28, a value larger than 16384 bytes would be truncated down to 16384. In API 28 and after, any value of length is valid.
  • timeout – in milliseconds, 0 is infinite
Returns:length of data transferred (or zero) for success,
or negative value for failure
/**
     * 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 offset the index of the first byte in the buffer to send or receive
     * @param length the length of the data to send or receive. Before
     *               {@value Build.VERSION_CODES#P}, a value larger than 16384 bytes
     *               would be truncated down to 16384. In API {@value Build.VERSION_CODES#P}
     *               and after, any value of length is valid.
     * @param timeout in milliseconds, 0 is infinite
     * @return length of data transferred (or zero) for success,
     * or negative value for failure
     */
    public int bulkTransfer(UsbEndpoint endpoint,
            byte[] buffer, int offset, int length, int timeout) {
        checkBounds(buffer, offset, length);
        if (mContext.getApplicationInfo().targetSdkVersion < Build.VERSION_CODES.P
                && length > UsbRequest.MAX_USBFS_BUFFER_SIZE) {
            length = UsbRequest.MAX_USBFS_BUFFER_SIZE;
        }
        return native_bulk_request(endpoint.getAddress(), buffer, offset, length, timeout);
    }

    
Reset USB port for the connected device.

Returns:true if reset succeeds.
@hide
/**
     * Reset USB port for the connected device.
     *
     * @return true if reset succeeds.
     *
     * @hide
     */
    @SystemApi
    @SuppressLint("Doclava125")
    public boolean resetDevice() {
        return native_reset_device();
    }

    
Waits for the result of a UsbRequest.queue operation 
Note that this may return requests queued on multiple UsbEndpoints. When multiple endpoints are in use, UsbRequest.getEndpoint and UsbRequest.getClientData can be useful in determining how to process the result of this function.


Throws:
Returns:a completed USB request, or null if an error occurred
/**
     * Waits for the result of a {@link android.hardware.usb.UsbRequest#queue} operation
     * <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>
     *
     * @return a completed USB request, or null if an error occurred
     *
     * @throws IllegalArgumentException Before API {@value Build.VERSION_CODES#O}: 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)}
     * @throws BufferOverflowException In API {@value Build.VERSION_CODES#O} and after: 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 = null;
        try {
            // -1 is special value indicating infinite wait
            request = native_request_wait(-1);
        } catch (TimeoutException e) {
            // Does not happen, infinite timeout
        }

        if (request != null) {
            request.dequeue(
                    mContext.getApplicationInfo().targetSdkVersion >= Build.VERSION_CODES.O);
        }
        return request;
    }

    
Waits for the result of a UsbRequest.queue operation 
Note that this may return requests queued on multiple UsbEndpoints. When multiple endpoints are in use, UsbRequest.getEndpoint and UsbRequest.getClientData can be useful in determining how to process the result of this function.


Android processes UsbRequests asynchronously. Hence it is not guaranteed that requestWait(0) returns a request that has been queued right before even if the request could have been processed immediately.


Params:
  • timeout – timeout in milliseconds. If 0 this method does not wait.
Throws:
Returns:a completed USB request, or null if an error occurred
/**
     * Waits for the result of a {@link android.hardware.usb.UsbRequest#queue} operation
     * <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>Android processes {@link UsbRequest UsbRequests} asynchronously. Hence it is not
     * guaranteed that {@link #requestWait(long) requestWait(0)} returns a request that has been
     * queued right before even if the request could have been processed immediately.</p>
     *
     * @param timeout timeout in milliseconds. If 0 this method does not wait.
     *
     * @return a completed USB request, or {@code null} if an error occurred
     *
     * @throws BufferOverflowException 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)}
     * @throws TimeoutException if no request was received in {@code timeout} milliseconds.
     */
    public UsbRequest requestWait(long timeout) throws TimeoutException {
        timeout = Preconditions.checkArgumentNonnegative(timeout, "timeout");

        UsbRequest request = native_request_wait(timeout);
        if (request != null) {
            request.dequeue(true);
        }
        return request;
    }

    
Returns the serial number for the device.
This will return null if the device has not been opened.

Returns:the device serial number
/**
     * 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 static void checkBounds(byte[] buffer, int start, int length) {
        final int bufferLength = (buffer != null ? buffer.length : 0);
        if (length < 0 || start < 0 || start + length > bufferLength) {
            throw new IllegalArgumentException("Buffer start or length out of bounds.");
        }
    }

    @Override
    protected void finalize() throws Throwable {
        try {
            if (mCloseGuard != null) {
                mCloseGuard.warnIfOpen();
            }
        } finally {
            super.finalize();
        }
    }

    private native boolean native_open(String deviceName, FileDescriptor pfd);
    private native void native_close();
    private native int native_get_fd();
    private native byte[] native_get_desc();
    private native boolean native_claim_interface(int interfaceID, boolean force);
    private native boolean native_release_interface(int interfaceID);
    private native boolean native_set_interface(int interfaceID, int alternateSetting);
    private native boolean native_set_configuration(int configurationID);
    private native int native_control_request(int requestType, int request, int value,
            int index, byte[] buffer, int offset, int length, int timeout);
    private native int native_bulk_request(int endpoint, byte[] buffer,
            int offset, int length, int timeout);
    private native UsbRequest native_request_wait(long timeout) throws TimeoutException;
    private native String native_get_serial();
    private native boolean native_reset_device();
}