1 /* 2 * Copyright (C) 2010 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.mtp; 18 19 import android.hardware.usb.UsbDevice; 20 import android.hardware.usb.UsbDeviceConnection; 21 22 /** 23 * This class represents an MTP or PTP device connected on the USB host bus. An application can 24 * instantiate an object of this type, by referencing an attached {@link 25 * android.hardware.usb.UsbDevice} and then use methods in this class to get information about the 26 * device and objects stored on it, as well as open the connection and transfer data. 27 */ 28 public final class MtpDevice { 29 30 private static final String TAG = "MtpDevice"; 31 32 private final UsbDevice mDevice; 33 34 static { 35 System.loadLibrary("media_jni"); 36 } 37 38 /** 39 * MtpClient constructor 40 * 41 * @param device the {@link android.hardware.usb.UsbDevice} for the MTP or PTP device 42 */ 43 public MtpDevice(UsbDevice device) { 44 mDevice = device; 45 } 46 47 /** 48 * Opens the MTP device. Once the device is open it takes ownership of the 49 * {@link android.hardware.usb.UsbDeviceConnection}. 50 * The connection will be closed when you call {@link #close()} 51 * The connection will also be closed if this method fails. 52 * 53 * @param connection an open {@link android.hardware.usb.UsbDeviceConnection} for the device 54 * @return true if the device was successfully opened. 55 */ 56 public boolean open(UsbDeviceConnection connection) { 57 boolean result = native_open(mDevice.getDeviceName(), connection.getFileDescriptor()); 58 if (!result) { 59 connection.close(); 60 } 61 return result; 62 } 63 64 /** 65 * Closes all resources related to the MtpDevice object. 66 * After this is called, the object can not be used until {@link #open} is called again 67 * with a new {@link android.hardware.usb.UsbDeviceConnection}. 68 */ 69 public void close() { 70 native_close(); 71 } 72 73 @Override 74 protected void finalize() throws Throwable { 75 try { 76 native_close(); 77 } finally { 78 super.finalize(); 79 } 80 } 81 82 /** 83 * Returns the name of the USB device 84 * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceName} 85 * for the device's {@link android.hardware.usb.UsbDevice} 86 * 87 * @return the device name 88 */ 89 public String getDeviceName() { 90 return mDevice.getDeviceName(); 91 } 92 93 /** 94 * Returns the USB ID of the USB device. 95 * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceId} 96 * for the device's {@link android.hardware.usb.UsbDevice} 97 * 98 * @return the device ID 99 */ 100 public int getDeviceId() { 101 return mDevice.getDeviceId(); 102 } 103 104 @Override 105 public String toString() { 106 return mDevice.getDeviceName(); 107 } 108 109 /** 110 * Returns the {@link MtpDeviceInfo} for this device 111 * 112 * @return the device info 113 */ 114 public MtpDeviceInfo getDeviceInfo() { 115 return native_get_device_info(); 116 } 117 118 /** 119 * Returns the list of IDs for all storage units on this device 120 * Information about each storage unit can be accessed via {@link #getStorageInfo}. 121 * 122 * @return the list of storage IDs 123 */ 124 public int[] getStorageIds() { 125 return native_get_storage_ids(); 126 } 127 128 /** 129 * Returns the list of object handles for all objects on the given storage unit, 130 * with the given format and parent. 131 * Information about each object can be accessed via {@link #getObjectInfo}. 132 * 133 * @param storageId the storage unit to query 134 * @param format the format of the object to return, or zero for all formats 135 * @param objectHandle the parent object to query, or zero for the storage root 136 * @return the object handles 137 */ 138 public int[] getObjectHandles(int storageId, int format, int objectHandle) { 139 return native_get_object_handles(storageId, format, objectHandle); 140 } 141 142 /** 143 * Returns the data for an object as a byte array. 144 * This call may block for an arbitrary amount of time depending on the size 145 * of the data and speed of the devices. 146 * 147 * @param objectHandle handle of the object to read 148 * @param objectSize the size of the object (this should match 149 * {@link MtpObjectInfo#getCompressedSize} 150 * @return the object's data, or null if reading fails 151 */ 152 public byte[] getObject(int objectHandle, int objectSize) { 153 return native_get_object(objectHandle, objectSize); 154 } 155 156 /** 157 * Returns the thumbnail data for an object as a byte array. 158 * The size and format of the thumbnail data can be determined via 159 * {@link MtpObjectInfo#getThumbCompressedSize} and 160 * {@link MtpObjectInfo#getThumbFormat}. 161 * For typical devices the format is JPEG. 162 * 163 * @param objectHandle handle of the object to read 164 * @return the object's thumbnail, or null if reading fails 165 */ 166 public byte[] getThumbnail(int objectHandle) { 167 return native_get_thumbnail(objectHandle); 168 } 169 170 /** 171 * Retrieves the {@link MtpStorageInfo} for a storage unit. 172 * 173 * @param storageId the ID of the storage unit 174 * @return the MtpStorageInfo 175 */ 176 public MtpStorageInfo getStorageInfo(int storageId) { 177 return native_get_storage_info(storageId); 178 } 179 180 /** 181 * Retrieves the {@link MtpObjectInfo} for an object. 182 * 183 * @param objectHandle the handle of the object 184 * @return the MtpObjectInfo 185 */ 186 public MtpObjectInfo getObjectInfo(int objectHandle) { 187 return native_get_object_info(objectHandle); 188 } 189 190 /** 191 * Deletes an object on the device. This call may block, since 192 * deleting a directory containing many files may take a long time 193 * on some devices. 194 * 195 * @param objectHandle handle of the object to delete 196 * @return true if the deletion succeeds 197 */ 198 public boolean deleteObject(int objectHandle) { 199 return native_delete_object(objectHandle); 200 } 201 202 /** 203 * Retrieves the object handle for the parent of an object on the device. 204 * 205 * @param objectHandle handle of the object to query 206 * @return the parent's handle, or zero if it is in the root of the storage 207 */ 208 public long getParent(int objectHandle) { 209 return native_get_parent(objectHandle); 210 } 211 212 /** 213 * Retrieves the ID of the storage unit containing the given object on the device. 214 * 215 * @param objectHandle handle of the object to query 216 * @return the object's storage unit ID 217 */ 218 public long getStorageId(int objectHandle) { 219 return native_get_storage_id(objectHandle); 220 } 221 222 /** 223 * Copies the data for an object to a file in external storage. 224 * This call may block for an arbitrary amount of time depending on the size 225 * of the data and speed of the devices. 226 * 227 * @param objectHandle handle of the object to read 228 * @param destPath path to destination for the file transfer. 229 * This path should be in the external storage as defined by 230 * {@link android.os.Environment#getExternalStorageDirectory} 231 * @return true if the file transfer succeeds 232 */ 233 public boolean importFile(int objectHandle, String destPath) { 234 return native_import_file(objectHandle, destPath); 235 } 236 237 // used by the JNI code 238 private long mNativeContext; 239 240 private native boolean native_open(String deviceName, int fd); 241 private native void native_close(); 242 private native MtpDeviceInfo native_get_device_info(); 243 private native int[] native_get_storage_ids(); 244 private native MtpStorageInfo native_get_storage_info(int storageId); 245 private native int[] native_get_object_handles(int storageId, int format, int objectHandle); 246 private native MtpObjectInfo native_get_object_info(int objectHandle); 247 private native byte[] native_get_object(int objectHandle, int objectSize); 248 private native byte[] native_get_thumbnail(int objectHandle); 249 private native boolean native_delete_object(int objectHandle); 250 private native long native_get_parent(int objectHandle); 251 private native long native_get_storage_id(int objectHandle); 252 private native boolean native_import_file(int objectHandle, String destPath); 253 } 254