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
17package android.mtp;
18
19import android.hardware.usb.UsbDevice;
20import android.hardware.usb.UsbDeviceConnection;
21import android.os.ParcelFileDescriptor;
22import 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 */
30public 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     */
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     */
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     */
71    public void close() {
72        native_close();
73    }
74
75    @Override
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     */
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     */
102    public int getDeviceId() {
103        return mDevice.getDeviceId();
104    }
105
106    @Override
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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
242    private native boolean native_open(String deviceName, int fd);
243    private native void native_close();
244    private native MtpDeviceInfo native_get_device_info();
245    private native int[] native_get_storage_ids();
246    private native MtpStorageInfo native_get_storage_info(int storageId);
247    private native int[] native_get_object_handles(int storageId, int format, int objectHandle);
248    private native MtpObjectInfo native_get_object_info(int objectHandle);
249    private native byte[] native_get_object(int objectHandle, int objectSize);
250    private native byte[] native_get_thumbnail(int objectHandle);
251    private native boolean native_delete_object(int objectHandle);
252    private native long native_get_parent(int objectHandle);
253    private native long native_get_storage_id(int objectHandle);
254    private native boolean native_import_file(int objectHandle, String destPath);
255}
256