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