1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.usb; 18 19 import android.os.ParcelFileDescriptor; 20 import android.util.Log; 21 22 import java.io.FileDescriptor; 23 24 25 /** 26 * This class is used for sending and receiving data and control messages to a USB device. 27 * Instances of this class are created by {@link UsbManager#openDevice}. 28 */ 29 public class UsbDeviceConnection { 30 31 private static final String TAG = "UsbDeviceConnection"; 32 33 private final UsbDevice mDevice; 34 35 // used by the JNI code 36 private int mNativeContext; 37 38 /** 39 * UsbDevice should only be instantiated by UsbService implementation 40 * @hide 41 */ 42 public UsbDeviceConnection(UsbDevice device) { 43 mDevice = device; 44 } 45 46 /* package */ boolean open(String name, ParcelFileDescriptor pfd) { 47 return native_open(name, pfd.getFileDescriptor()); 48 } 49 50 /** 51 * Releases all system resources related to the device. 52 * Once the object is closed it cannot be used again. 53 * The client must call {@link UsbManager#openDevice} again 54 * to retrieve a new instance to reestablish communication with the device. 55 */ 56 public void close() { 57 native_close(); 58 } 59 60 /** 61 * Returns the native file descriptor for the device, or 62 * -1 if the device is not opened. 63 * This is intended for passing to native code to access the device. 64 * 65 * @return the native file descriptor 66 */ 67 public int getFileDescriptor() { 68 return native_get_fd(); 69 } 70 71 /** 72 * Returns the raw USB descriptors for the device. 73 * This can be used to access descriptors not supported directly 74 * via the higher level APIs. 75 * 76 * @return raw USB descriptors 77 */ 78 public byte[] getRawDescriptors() { 79 return native_get_desc(); 80 } 81 82 /** 83 * Claims exclusive access to a {@link android.hardware.usb.UsbInterface}. 84 * This must be done before sending or receiving data on any 85 * {@link android.hardware.usb.UsbEndpoint}s belonging to the interface. 86 * 87 * @param intf the interface to claim 88 * @param force true to disconnect kernel driver if necessary 89 * @return true if the interface was successfully claimed 90 */ 91 public boolean claimInterface(UsbInterface intf, boolean force) { 92 return native_claim_interface(intf.getId(), force); 93 } 94 95 /** 96 * Releases exclusive access to a {@link android.hardware.usb.UsbInterface}. 97 * 98 * @return true if the interface was successfully released 99 */ 100 public boolean releaseInterface(UsbInterface intf) { 101 return native_release_interface(intf.getId()); 102 } 103 104 /** 105 * Performs a control transaction on endpoint zero for this device. 106 * The direction of the transfer is determined by the request type. 107 * If requestType & {@link UsbConstants#USB_ENDPOINT_DIR_MASK} is 108 * {@link UsbConstants#USB_DIR_OUT}, then the transfer is a write, 109 * and if it is {@link UsbConstants#USB_DIR_IN}, then the transfer 110 * is a read. 111 * 112 * @param requestType request type for this transaction 113 * @param request request ID for this transaction 114 * @param value value field for this transaction 115 * @param index index field for this transaction 116 * @param buffer buffer for data portion of transaction, 117 * or null if no data needs to be sent or received 118 * @param length the length of the data to send or receive 119 * @param timeout in milliseconds 120 * @return length of data transferred (or zero) for success, 121 * or negative value for failure 122 */ 123 public int controlTransfer(int requestType, int request, int value, 124 int index, byte[] buffer, int length, int timeout) { 125 return native_control_request(requestType, request, value, index, buffer, length, timeout); 126 } 127 128 /** 129 * Performs a bulk transaction on the given endpoint. 130 * The direction of the transfer is determined by the direction of the endpoint 131 * 132 * @param endpoint the endpoint for this transaction 133 * @param buffer buffer for data to send or receive, 134 * @param length the length of the data to send or receive 135 * @param timeout in milliseconds 136 * @return length of data transferred (or zero) for success, 137 * or negative value for failure 138 */ 139 public int bulkTransfer(UsbEndpoint endpoint, byte[] buffer, int length, int timeout) { 140 return native_bulk_request(endpoint.getAddress(), buffer, length, timeout); 141 } 142 143 /** 144 * Waits for the result of a {@link android.hardware.usb.UsbRequest#queue} operation 145 * Note that this may return requests queued on multiple 146 * {@link android.hardware.usb.UsbEndpoint}s. 147 * When multiple endpoints are in use, {@link android.hardware.usb.UsbRequest#getEndpoint} and 148 * {@link android.hardware.usb.UsbRequest#getClientData} can be useful in determining 149 * how to process the result of this function. 150 * 151 * @return a completed USB request, or null if an error occurred 152 */ 153 public UsbRequest requestWait() { 154 UsbRequest request = native_request_wait(); 155 if (request != null) { 156 request.dequeue(); 157 } 158 return request; 159 } 160 161 /** 162 * Returns the serial number for the device. 163 * This will return null if the device has not been opened. 164 * 165 * @return the device serial number 166 */ 167 public String getSerial() { 168 return native_get_serial(); 169 } 170 171 private native boolean native_open(String deviceName, FileDescriptor pfd); 172 private native void native_close(); 173 private native int native_get_fd(); 174 private native byte[] native_get_desc(); 175 private native boolean native_claim_interface(int interfaceID, boolean force); 176 private native boolean native_release_interface(int interfaceID); 177 private native int native_control_request(int requestType, int request, int value, 178 int index, byte[] buffer, int length, int timeout); 179 private native int native_bulk_request(int endpoint, byte[] buffer, int length, int timeout); 180 private native UsbRequest native_request_wait(); 181 private native String native_get_serial(); 182 } 183