Added in API level 12

MtpDevice

class MtpDevice
kotlin.Any
   ↳ android.mtp.MtpDevice

This class represents an MTP or PTP device connected on the USB host bus. An application can instantiate an object of this type, by referencing an attached and then use methods in this class to get information about the device and objects stored on it, as well as open the connection and transfer data.

Summary

Public constructors

MtpClient constructor
Public methods
Unit

Closes all resources related to the MtpDevice object.
Boolean
deleteObject(objectHandle: Int)

Deletes an object on the device.
Int

Returns the USB ID of the USB device.
MtpDeviceInfo?

Returns the MtpDeviceInfo for this device
String

Returns the name of the USB device This returns the same value as android.
ByteArray?
getObject(objectHandle: Int, objectSize: Int)

Returns the data for an object as a byte array.
IntArray?
getObjectHandles(storageId: Int, format: Int, objectHandle: Int)

Returns the list of object handles for all objects on the given storage unit, with the given format and parent.
MtpObjectInfo?
getObjectInfo(objectHandle: Int)

Retrieves the MtpObjectInfo for an object.
Long
getParent(objectHandle: Int)

Retrieves the object handle for the parent of an object on the device.
Long
getPartialObject(objectHandle: Int, offset: Long, size: Long, buffer: ByteArray)

Obtains object bytes in the specified range and writes it to an array.
Long
getPartialObject64(objectHandle: Int, offset: Long, size: Long, buffer: ByteArray)

Obtains object bytes in the specified range and writes it to an array.
Long
getStorageId(objectHandle: Int)

Retrieves the ID of the storage unit containing the given object on the device.
IntArray?

Returns the list of IDs for all storage units on this device Information about each storage unit can be accessed via getStorageInfo.
MtpStorageInfo?
getStorageInfo(storageId: Int)

Retrieves the MtpStorageInfo for a storage unit.
ByteArray?
getThumbnail(objectHandle: Int)

Returns the thumbnail data for an object as a byte array.
Boolean
importFile(objectHandle: Int, destPath: String)

Copies the data for an object to a file in external storage.
Boolean
importFile(objectHandle: Int, descriptor: ParcelFileDescriptor)

Copies the data for an object to a file descriptor.
Boolean

Opens the MTP device.
MtpEvent

Reads an event from the device.
Boolean
sendObject(objectHandle: Int, size: Long, descriptor: ParcelFileDescriptor)

Copies the data for an object from a file descriptor.
MtpObjectInfo?

Uploads an object metadata for a new entry.
String

Returns a string representation of the object.
Protected methods
Unit

Public constructors

MtpDevice

Added in API level 12
MtpDevice(device: UsbDevice)

MtpClient constructor

Parameters
device UsbDevice: the android.hardware.usb.UsbDevice for the MTP or PTP device This value cannot be null.

Public methods

close

Added in API level 12
fun close(): Unit

Closes all resources related to the MtpDevice object. After this is called, the object can not be used until open is called again with a new android.hardware.usb.UsbDeviceConnection.

deleteObject

Added in API level 12
fun deleteObject(objectHandle: Int): Boolean

Deletes an object on the device. This call may block, since deleting a directory containing many files may take a long time on some devices.

Parameters
objectHandle Int: handle of the object to delete
Return
Boolean true if the deletion succeeds

getDeviceId

Added in API level 12
fun getDeviceId(): Int

Returns the USB ID of the USB device. This returns the same value as android.hardware.usb.UsbDevice#getDeviceId for the device's android.hardware.usb.UsbDevice

Return
Int the device ID

getDeviceInfo

Added in API level 12
fun getDeviceInfo(): MtpDeviceInfo?

Returns the MtpDeviceInfo for this device

Return
MtpDeviceInfo? the device info, or null if fetching device info fails

getDeviceName

Added in API level 12
fun getDeviceName(): String

Returns the name of the USB device This returns the same value as android.hardware.usb.UsbDevice#getDeviceName for the device's android.hardware.usb.UsbDevice

Return
String the device name This value cannot be null.

getObject

Added in API level 12
fun getObject(
    objectHandle: Int, 
    objectSize: Int
): ByteArray?

Returns the data for an object as a byte array. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices.

Parameters
objectHandle Int: handle of the object to read
objectSize Int: the size of the object (this should match MtpObjectInfo#getCompressedSize)
Return
ByteArray? the object's data, or null if reading fails

getObjectHandles

Added in API level 12
fun getObjectHandles(
    storageId: Int, 
    format: Int, 
    objectHandle: Int
): IntArray?

Returns the list of object handles for all objects on the given storage unit, with the given format and parent. Information about each object can be accessed via getObjectInfo.

Parameters
storageId Int: the storage unit to query
format Int: the format of the object to return, or zero for all formats
objectHandle Int: the parent object to query, -1 for the storage root, or zero for all objects
Return
IntArray? the object handles, or null if fetching object handles fails

getObjectInfo

Added in API level 12
fun getObjectInfo(objectHandle: Int): MtpObjectInfo?

Retrieves the MtpObjectInfo for an object.

Parameters
objectHandle Int: the handle of the object
Return
MtpObjectInfo? the MtpObjectInfo, or null if fetching object info fails

getParent

Added in API level 12
fun getParent(objectHandle: Int): Long

Retrieves the object handle for the parent of an object on the device.

Parameters
objectHandle Int: handle of the object to query
Return
Long the parent's handle, or zero if it is in the root of the storage

getPartialObject

Added in API level 24
fun getPartialObject(
    objectHandle: Int, 
    offset: Long, 
    size: Long, 
    buffer: ByteArray
): Long

Obtains object bytes in the specified range and writes it to an array. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices.

Parameters
objectHandle Int: handle of the object to read
offset Long: Start index of reading range. It must be a non-negative value at most 0xffffffff.
size Long: Size of reading range. It must be a non-negative value at most Integer.MAX_VALUE or 0xffffffff. If 0xffffffff is specified, the method obtains the full bytes of object.
buffer ByteArray: Array to write data. This value cannot be null.
Return
Long Size of bytes that are actually read.

getPartialObject64

Added in API level 24
fun getPartialObject64(
    objectHandle: Int, 
    offset: Long, 
    size: Long, 
    buffer: ByteArray
): Long

Obtains object bytes in the specified range and writes it to an array. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices. This is a vender-extended operation supported by Android that enables us to pass unsigned 64-bit offset. Check if the MTP device supports the operation by using MtpDeviceInfo#getOperationsSupported().

Parameters
objectHandle Int: handle of the object to read
offset Long: Start index of reading range. It must be a non-negative value.
size Long: Size of reading range. It must be a non-negative value at most Integer.MAX_VALUE.
buffer ByteArray: Array to write data. This value cannot be null.
Return
Long Size of bytes that are actually read.

getStorageId

Added in API level 12
fun getStorageId(objectHandle: Int): Long

Retrieves the ID of the storage unit containing the given object on the device.

Parameters
objectHandle Int: handle of the object to query
Return
Long the object's storage unit ID

getStorageIds

Added in API level 12
fun getStorageIds(): IntArray?

Returns the list of IDs for all storage units on this device Information about each storage unit can be accessed via getStorageInfo.

Return
IntArray? the list of storage IDs, or null if fetching storage IDs fails

getStorageInfo

Added in API level 12
fun getStorageInfo(storageId: Int): MtpStorageInfo?

Retrieves the MtpStorageInfo for a storage unit.

Parameters
storageId Int: the ID of the storage unit
Return
MtpStorageInfo? the MtpStorageInfo, or null if fetching storage info fails

getThumbnail

Added in API level 12
fun getThumbnail(objectHandle: Int): ByteArray?

Returns the thumbnail data for an object as a byte array. The size and format of the thumbnail data can be determined via MtpObjectInfo#getThumbCompressedSize and MtpObjectInfo#getThumbFormat. For typical devices the format is JPEG.

Parameters
objectHandle Int: handle of the object to read
Return
ByteArray? the object's thumbnail, or null if reading fails

importFile

Added in API level 12
fun importFile(
    objectHandle: Int, 
    destPath: String
): Boolean

Copies the data for an object to a file in external storage. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices.

Parameters
objectHandle Int: handle of the object to read
destPath String: path to destination for the file transfer. This path should be in the external storage as defined by android.os.Environment#getExternalStorageDirectory This value cannot be null.
Return
Boolean true if the file transfer succeeds

importFile

Added in API level 24
fun importFile(
    objectHandle: Int, 
    descriptor: ParcelFileDescriptor
): Boolean

Copies the data for an object to a file descriptor. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices. The file descriptor is not closed on completion, and must be done by the caller.

Parameters
objectHandle Int: handle of the object to read
descriptor ParcelFileDescriptor: file descriptor to write the data to for the file transfer. This value cannot be null.
Return
Boolean true if the file transfer succeeds

open

Added in API level 12
fun open(connection: UsbDeviceConnection): Boolean

Opens the MTP device. Once the device is open it takes ownership of the android.hardware.usb.UsbDeviceConnection. The connection will be closed when you call close() The connection will also be closed if this method fails.

Parameters
connection UsbDeviceConnection: an open android.hardware.usb.UsbDeviceConnection for the device This value cannot be null.
Return
Boolean true if the device was successfully opened.

readEvent

Added in API level 24
fun readEvent(signal: CancellationSignal?): MtpEvent

Reads an event from the device. It blocks the current thread until it gets an event. It throws OperationCanceledException if it is cancelled by signal.

Parameters
signal CancellationSignal?: signal for cancellation This value may be null.
Return
MtpEvent obtained event This value cannot be null.
Exceptions
java.io.IOException

sendObject

Added in API level 24
fun sendObject(
    objectHandle: Int, 
    size: Long, 
    descriptor: ParcelFileDescriptor
): Boolean

Copies the data for an object from a file descriptor. This call may block for an arbitrary amount of time depending on the size of the data and speed of the devices. The file descriptor is not closed on completion, and must be done by the caller.

Parameters
objectHandle Int: handle of the target file
size Long: size of the file in bytes
descriptor ParcelFileDescriptor: file descriptor to read the data from. This value cannot be null.
Return
Boolean true if the file transfer succeeds

sendObjectInfo

Added in API level 24
fun sendObjectInfo(info: MtpObjectInfo): MtpObjectInfo?

Uploads an object metadata for a new entry. The MtpObjectInfo can be created with the MtpObjectInfo.Builder class. The returned MtpObjectInfo has the new object handle field filled in.

Parameters
info MtpObjectInfo: metadata of the entry This value cannot be null.
Return
MtpObjectInfo? object info of the created entry, or null if sending object info fails

toString

Added in API level 12
fun toString(): String

Returns a string representation of the object.

Return
String This value cannot be null.

Protected methods

finalize

Added in API level 12
protected fun finalize(): Unit
Exceptions
java.lang.Throwable the Exception raised by this method