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;
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 */
28public 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