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, -1 for the storage root, 136 * or zero for all objects 137 * @return the object handles 138 */ 139 public int[] getObjectHandles(int storageId, int format, int objectHandle) { 140 return native_get_object_handles(storageId, format, objectHandle); 141 } 142 143 /** 144 * Returns the data for an object as a byte array. 145 * This call may block for an arbitrary amount of time depending on the size 146 * of the data and speed of the devices. 147 * 148 * @param objectHandle handle of the object to read 149 * @param objectSize the size of the object (this should match 150 * {@link MtpObjectInfo#getCompressedSize} 151 * @return the object's data, or null if reading fails 152 */ 153 public byte[] getObject(int objectHandle, int objectSize) { 154 return native_get_object(objectHandle, objectSize); 155 } 156 157 /** 158 * Returns the thumbnail data for an object as a byte array. 159 * The size and format of the thumbnail data can be determined via 160 * {@link MtpObjectInfo#getThumbCompressedSize} and 161 * {@link MtpObjectInfo#getThumbFormat}. 162 * For typical devices the format is JPEG. 163 * 164 * @param objectHandle handle of the object to read 165 * @return the object's thumbnail, or null if reading fails 166 */ 167 public byte[] getThumbnail(int objectHandle) { 168 return native_get_thumbnail(objectHandle); 169 } 170 171 /** 172 * Retrieves the {@link MtpStorageInfo} for a storage unit. 173 * 174 * @param storageId the ID of the storage unit 175 * @return the MtpStorageInfo 176 */ 177 public MtpStorageInfo getStorageInfo(int storageId) { 178 return native_get_storage_info(storageId); 179 } 180 181 /** 182 * Retrieves the {@link MtpObjectInfo} for an object. 183 * 184 * @param objectHandle the handle of the object 185 * @return the MtpObjectInfo 186 */ 187 public MtpObjectInfo getObjectInfo(int objectHandle) { 188 return native_get_object_info(objectHandle); 189 } 190 191 /** 192 * Deletes an object on the device. This call may block, since 193 * deleting a directory containing many files may take a long time 194 * on some devices. 195 * 196 * @param objectHandle handle of the object to delete 197 * @return true if the deletion succeeds 198 */ 199 public boolean deleteObject(int objectHandle) { 200 return native_delete_object(objectHandle); 201 } 202 203 /** 204 * Retrieves the object handle for the parent of an object on the device. 205 * 206 * @param objectHandle handle of the object to query 207 * @return the parent's handle, or zero if it is in the root of the storage 208 */ 209 public long getParent(int objectHandle) { 210 return native_get_parent(objectHandle); 211 } 212 213 /** 214 * Retrieves the ID of the storage unit containing the given object on the device. 215 * 216 * @param objectHandle handle of the object to query 217 * @return the object's storage unit ID 218 */ 219 public long getStorageId(int objectHandle) { 220 return native_get_storage_id(objectHandle); 221 } 222 223 /** 224 * Copies the data for an object to a file in external storage. 225 * This call may block for an arbitrary amount of time depending on the size 226 * of the data and speed of the devices. 227 * 228 * @param objectHandle handle of the object to read 229 * @param destPath path to destination for the file transfer. 230 * This path should be in the external storage as defined by 231 * {@link android.os.Environment#getExternalStorageDirectory} 232 * @return true if the file transfer succeeds 233 */ 234 public boolean importFile(int objectHandle, String destPath) { 235 return native_import_file(objectHandle, destPath); 236 } 237 238 // used by the JNI code 239 private long mNativeContext; 240 241 private native boolean native_open(String deviceName, int fd); 242 private native void native_close(); 243 private native MtpDeviceInfo native_get_device_info(); 244 private native int[] native_get_storage_ids(); 245 private native MtpStorageInfo native_get_storage_info(int storageId); 246 private native int[] native_get_object_handles(int storageId, int format, int objectHandle); 247 private native MtpObjectInfo native_get_object_info(int objectHandle); 248 private native byte[] native_get_object(int objectHandle, int objectSize); 249 private native byte[] native_get_thumbnail(int objectHandle); 250 private native boolean native_delete_object(int objectHandle); 251 private native long native_get_parent(int objectHandle); 252 private native long native_get_storage_id(int objectHandle); 253 private native boolean native_import_file(int objectHandle, String destPath); 254 } 255
