Android Programming Press on the image to return to the main documentation page.

MtpDevice

Written by Andrew Graham

This library provides APIs that let you interact directly with connected cameras and other devices
using the PTP (Picture Transfer Protocol) subset of the MTP (Media Transfer Protocol) specification.
Your application can transfer and delete files and metadata from an MTP device. You cannot however create
or modify files or folders on the MTP device as the Android API does not implement this.

This library contains three objects
MtpDevice2 represents an MTP or PTP device connected on the USB host bus.
MtpConstants contains constants in the MTP and PTP specifications.
MtpObjectInfo encapsulates information about an object on an MTP device.

Note that the name MtpDevice2 is chosen because a non-functional MtpDevice object exists in the USB library.
This library will be merged with the USB library and replace the MtpDevice in a future release of Basic4android.

This library requires Android 3.1 or later, a device with host USB capability and an OTG cable to switch the device USB port to host mode.

List of types:

MtpConstants
MtpDevice2
MtpObjectInfo

MtpConstants

The MtpConstants object contains constants in the MTP and PTP specifications.
These are mostly self-explanatory about the format that they represent.
Associations are MPT-speak for folders and directories.
Abstract objects have no representation in the underlying file system.

Events:

None

Members:


  AsInteger (mtpconstant As String) As Int

  ASSOCIATION_TYPE_GENERIC_FOLDER As Int

  AsString (mtpconstant As Int) As String

  FORMAT_3GP_CONTAINER As Int

  FORMAT_AAC As Int

  FORMAT_ABSTRACT_AUDIO_ALBUM As Int

  FORMAT_ABSTRACT_AUDIO_PLAYLIST As Int

  FORMAT_ABSTRACT_AV_PLAYLIST As Int

  FORMAT_ABSTRACT_DOCUMENT As Int

  FORMAT_ABSTRACT_IMAGE_ALBUM As Int

  FORMAT_ABSTRACT_MEDIACAST As Int

  FORMAT_ABSTRACT_MULTIMEDIA_ALBUM As Int

  FORMAT_ABSTRACT_VIDEO_ALBUM As Int

  FORMAT_ABSTRACT_VIDEO_PLAYLIST As Int

  FORMAT_AIFF As Int

  FORMAT_ALL As Int

  FORMAT_ASF As Int

  FORMAT_ASSOCIATION As Int

  FORMAT_ASX_PLAYLIST As Int

  FORMAT_AUDIBLE As Int

  FORMAT_AVI As Int

  FORMAT_BMP As Int

  FORMAT_DPOF As Int

  FORMAT_EXECUTABLE As Int

  FORMAT_EXIF_JPEG As Int

  FORMAT_FLAC As Int

  FORMAT_GIF As Int

  FORMAT_HTML As Int

  FORMAT_JFIF As Int

  FORMAT_JP2 As Int

  FORMAT_JPX As Int

  FORMAT_M3U_PLAYLIST As Int

  FORMAT_MP2 As Int

  FORMAT_MP3 As Int

  FORMAT_MP4_CONTAINER As Int

  FORMAT_MPEG As Int

  FORMAT_MPL_PLAYLIST As Int

  FORMAT_MS_EXCEL_SPREADSHEET As Int

  FORMAT_MS_POWERPOINT_PRESENTATION As Int

  FORMAT_MS_WORD_DOCUMENT As Int

  FORMAT_OGG As Int

  FORMAT_PICT As Int

  FORMAT_PLS_PLAYLIST As Int

  FORMAT_PNG As Int

  FORMAT_SCRIPT As Int

  FORMAT_TEXT As Int

  FORMAT_TIFF As Int

  FORMAT_TIFF_EP As Int

  FORMAT_UNDEFINED As Int

  FORMAT_UNDEFINED_AUDIO As Int

  FORMAT_UNDEFINED_COLLECTION As Int

  FORMAT_UNDEFINED_DOCUMENT As Int

  FORMAT_UNDEFINED_FIRMWARE As Int

  FORMAT_UNDEFINED_VIDEO As Int

  FORMAT_WAV As Int

  FORMAT_WINDOWS_IMAGE_FORMAT As Int

  FORMAT_WMA As Int

  FORMAT_WMV As Int

  FORMAT_WPL_PLAYLIST As Int

  FORMAT_XML_DOCUMENT As Int

  IsAbstractObject (mtpformat As Int) As Boolean

  PROTECTION_STATUS_NON_TRANSFERABLE_DATA As Int

  PROTECTION_STATUS_NONE As Int

  PROTECTION_STATUS_READ_ONLY As Int

  PROTECTION_STATUS_READ_ONLY_DATA As Int

Members description:

AsInteger (mtpconstant As String) As Int
Returns the MtpConstant integer value given its name as a String.
ASSOCIATION_TYPE_GENERIC_FOLDER As Int
Association type for objects representing file system directories.
AsString (mtpconstant As Int) As String
Returns the MtpConstant name as a String given its integer value.
FORMAT_3GP_CONTAINER As Int
FORMAT_AAC As Int
FORMAT_ABSTRACT_AUDIO_ALBUM As Int
FORMAT_ABSTRACT_AUDIO_PLAYLIST As Int
FORMAT_ABSTRACT_AV_PLAYLIST As Int
FORMAT_ABSTRACT_DOCUMENT As Int
FORMAT_ABSTRACT_IMAGE_ALBUM As Int
FORMAT_ABSTRACT_MEDIACAST As Int
FORMAT_ABSTRACT_MULTIMEDIA_ALBUM As Int
FORMAT_ABSTRACT_VIDEO_ALBUM As Int
FORMAT_ABSTRACT_VIDEO_PLAYLIST As Int
FORMAT_AIFF As Int
FORMAT_ALL As Int
FORMAT_ASF As Int
FORMAT_ASSOCIATION As Int
Format code for associations (folders and directories)
FORMAT_ASX_PLAYLIST As Int
FORMAT_AUDIBLE As Int
FORMAT_AVI As Int
FORMAT_BMP As Int
FORMAT_DPOF As Int
FORMAT_EXECUTABLE As Int
FORMAT_EXIF_JPEG As Int
FORMAT_FLAC As Int
FORMAT_GIF As Int
FORMAT_HTML As Int
FORMAT_JFIF As Int
FORMAT_JP2 As Int
FORMAT_JPX As Int
FORMAT_M3U_PLAYLIST As Int
FORMAT_MP2 As Int
FORMAT_MP3 As Int
FORMAT_MP4_CONTAINER As Int
FORMAT_MPEG As Int
FORMAT_MPL_PLAYLIST As Int
FORMAT_MS_EXCEL_SPREADSHEET As Int
FORMAT_MS_POWERPOINT_PRESENTATION As Int
FORMAT_MS_WORD_DOCUMENT As Int
FORMAT_OGG As Int
FORMAT_PICT As Int
FORMAT_PLS_PLAYLIST As Int
FORMAT_PNG As Int
FORMAT_SCRIPT As Int
FORMAT_TEXT As Int
FORMAT_TIFF As Int
FORMAT_TIFF_EP As Int
FORMAT_UNDEFINED As Int
FORMAT_UNDEFINED_AUDIO As Int
FORMAT_UNDEFINED_COLLECTION As Int
FORMAT_UNDEFINED_DOCUMENT As Int
FORMAT_UNDEFINED_FIRMWARE As Int
FORMAT_UNDEFINED_VIDEO As Int
FORMAT_WAV As Int
FORMAT_WINDOWS_IMAGE_FORMAT As Int
FORMAT_WMA As Int
FORMAT_WMV As Int
FORMAT_WPL_PLAYLIST As Int
FORMAT_XML_DOCUMENT As Int
IsAbstractObject (mtpformat As Int) As Boolean
Returns true if the object of this format is abstract (that is, it has no representation in the underlying file system).
PROTECTION_STATUS_NON_TRANSFERABLE_DATA As Int
Object's contents can not be transfered from the device, but the object may be moved or deleted
and its properties may be modified.
PROTECTION_STATUS_NONE As Int
Object is not protected.
PROTECTION_STATUS_READ_ONLY As Int
Object can not be modified or deleted and its properties can not be modified.
PROTECTION_STATUS_READ_ONLY_DATA As Int
Object can not be modified or deleted but its properties are modifiable.

MtpDevice2

The MtpDevice object represents a USB device that supports the Media Transfer Protocol (MTP)
or the Picture Transfer Protocol (PTP). Methods in this class get information about the device
and objects stored on it and enable transferring data and deleting objects from the device.

For operations that are likely to take some time and block the main thread both synchronous and asynchronous
versions are available. The synchronous versions are simpler to use and may be appropriate for testing or
for simple applications for use by a few users. Production quality applications that will be used in unknown
conditions by many users should be structured to use the asynchronous versions which, while more difficult to use,
will provide a better user experience when MTP devices with large numbers of objects are used.

Note that the name MtpDevice2 is chosen because a non-functional MtpDevice object exists in the USB library.
This library will be merged with the USB library and replace the MtpDevice in a future release of Basic4android.

Events:

DeleteFinished(TaskID As Int, Result As Boolean) ' Result is True if the delete was successful
DeleteError(TaskID As Int, ExceptionMessage As String)
GetFinished(TaskID As Int, Data() As Byte) ' data is a Byte array containing the Object
GetError(TaskID As Int, ExceptionMessage As String)
GetHandlesFinished(TaskID As Int, Data() As Int) ' data is an Int array containing the Object handles
GetHandlesError(TaskID As Int, ExceptionMessage As String)
ImportFinished(TaskID As Int, Result As Boolean) ' Result is True if the delete was successful
ImportError(TaskID As Int, ExceptionMessage As String)

Members:


  Close

  DeleteObject (objecthandle As Int) As Boolean

  DeleteObjectAsync (objecthandle As Int, taskid As Int)

  GetDeviceId As Int

  GetDeviceManufacturer As String

  GetDeviceName As String

  GetDeviceSerialNumber As String

  GetDeviceVersion As String

  GetObject (objecthandle As Int, objectsize As Int) As Byte()

  GetObjectAsync (objecthandle As Int, objectsize As Int, taskid As Int)

  GetObjectHandles (storageid As Int, format As Int, objecthandle As Int) As Int()

  GetObjectHandlesAsync (storageid As Int, format As Int, objecthandle As Int, taskid As Int)

  GetObjectInfo (objecthandle As Int) As android.mtp.MtpObjectInfo

  GetParent (objecthandle As Int) As Long

  GetStorageDescription (storageid As Int) As String

  GetStorageFreeSpace (storageid As Int) As Long

  GetStorageId (objecthandle As Int) As Long

  GetStorageIds As Int()

  GetStorageMaxCapacity (storageid As Int) As Long

  GetStorageVolumeIdentifier (storageid As Int) As String

  Getthumbnail (objecthandle As Int) As Byte()

  ImportFile (objecthandle As Int, destpath As String) As Boolean

  ImportFileAsync (objecthandle As Int, destpath As String, taskid As Int)

  Initialize (eventname As String, usbdevice As android.hardware.usb.UsbDevice)

  Open (connection As UsbDeviceConnectionWrapper) As Boolean

  Version As Double [read only]

Members description:

Close
Closes all resources related to the MtpDevice object.
After this is called, this object can not be used until Open(UsbDeviceConnection) is called again
with a new UsbDeviceConnection
DeleteObject (objecthandle As Int) As Boolean
Deletes an object on the device returning True on success.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this DeleteObjectAsync is available to do the deletion on a separate thread.
This synchronous version is made available for convenience and use in known predictable situations.
Production quality applications should use the asynchronous version.
DeleteObjectAsync (objecthandle As Int, taskid As Int)
Deletes an object on the device returning True on success.
This call may block, since deleting a directory containing many files may take a long time on some devices.
Because of this the deletion is done on a separate thread.

If several deletes are running concurrently they will not necessarily terminate in same order as they were started.
The TaskID parameter enables different deletes to be individually identified if required.
Some devices may have limitations on the number of concurrent operations supported.

When the deletion ends the DeleteFinished event is raised returning the TaskID and True if the delete succeeded.
If an Exception occurs the DeleteError event is raised returning the TaskID and exception message.
The Exception is saved in LastException.
GetDeviceId As Int
Returns the USB ID of the USB device.
This returns the same value as GetDeviceId for the device's UsbDevice object
GetDeviceManufacturer As String
Returns the manufacturers name of the USB device.
GetDeviceName As String
Returns the model name of the USB device.
GetDeviceSerialNumber As String
Returns the serial number of the USB device.
GetDeviceVersion As String
Returns the version string of the USB device.
GetObject (objecthandle As Int, objectsize As Int) As Byte()
Copies the data for an object to a Byte array and returns the array or null if the read fails.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this GetObjectAsync is available to do the copying on a separate thread.
This synchronous version is made available for convenience and use in known predictable situations.
Production quality applications should use the asynchronous version.
GetObjectAsync (objecthandle As Int, objectsize As Int, taskid As Int)
Copies the data for an object to a Byte array and returns the array or null if the read fails.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this the import is done on a separate thread.

If several imports are running concurrently they will not necessarily terminate in same order as they were started.
The TaskID parameter enables different imports to be individually identified if required.
Some devices may have limitations on the number of concurrent operations supported.

When the import ends the GetFinished event is raised returning the TaskID and the Byte array or null.
If an Exception occurs the GetError event is raised returning the TaskID and exception message.
The Exception is saved in LastException.
GetObjectHandles (storageid As Int, format As Int, objecthandle As Int) As Int()
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 by passing the return of GetObjectInfo(int) to the Initialize of an MtpObjectInfo.

This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this GetObjectHandlesAsync is available to do the reading on a separate thread.
This synchronous version is made available for convenience and use in known predictable situations.
Production quality applications should use the asynchronous version.

storageId - the storage unit to query
format - the format from MtpConstants of the object to return, or zero for all formats.
objectHandle - the parent object to query, or zero for the storage root.

When the storage root is specified all objects on the device seem to be returned.
For any other parent only the direct children of that parent seem to be returned.
GetObjectHandlesAsync (storageid As Int, format As Int, objecthandle As Int, taskid As Int)
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 by passing the return of GetObjectInfo(int) to the Initialize of an MtpObjectInfo.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this the reading is done on a separate thread.

If several imports are running concurrently they will not necessarily terminate in same order as they were started.
The TaskID parameter enables different imports to be individually identified if required.
Some devices may have limitations on the number of concurrent operations supported.

storageId - the storage unit to query
format - the format from MtpConstants of the object to return, or FORMAT_ALL (zero) for all formats.
objectHandle - the handle of the parent object to query, or zero for the storage root.

When the storage root is specified all objects on the device seem to be returned.
For any other parent only the direct children of that parent seem to be returned.

When the import ends the GetHandlesFinished event is raised returning the TaskID and the Int array or null.
If an Exception occurs the GetHandlesError event is raised returning the TaskID and exception message.
The Exception is saved in LastException.
GetObjectInfo (objecthandle As Int) As android.mtp.MtpObjectInfo
Retrieves the MtpObjectInfo for an object. Pass the return to the Initialize method of an MtpObjectInfo.
GetParent (objecthandle As Int) As Long
Retrieves the object handle for the parent of an object on the device.
GetStorageDescription (storageid As Int) As String
Returns the description string for the storage unit specified.
GetStorageFreeSpace (storageid As Int) As Long
Returns the free space in bytes for the storage unit specified.
GetStorageId (objecthandle As Int) As Long
Retrieves the ID of the storage unit containing the given object on the device.
GetStorageIds As Int()
Returns the list of IDs for all storage units on this device.
GetStorageMaxCapacity (storageid As Int) As Long
Returns the maximum storage capacity in bytes for the storage unit specified.
GetStorageVolumeIdentifier (storageid As Int) As String
Returns the version string for the storage unit specified.
Getthumbnail (objecthandle As Int) As Byte()
Returns the thumbnail data for an object as a byte array.
The size and format of the thumbnail data can be determined using MtpObjectInfo GetThumbCompressedSize and GetThumbFormat.
For typical devices the format is JPEG.
ImportFile (objecthandle As Int, destpath As String) As Boolean
Copies the data for an object to a file in the Android device external storage.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this ImportFileAsync is available to do the copying on a separate thread.
This synchronous version is made available for convenience and use in known predictable situations.
Production quality applications should use the asynchronous version.
ImportFileAsync (objecthandle As Int, destpath As String, taskid As Int)
Copies the data for an object to a file in the Android device external storage.
This may take an arbitrary amount of time depending on the size of the data and speed of the devices.
Because of this the import is done on a separate thread.

If several imports are running concurrently they will not necessarily terminate in same order as they were started.
The TaskID parameter enables different imports to be individually identified if required.
Some devices may have limitations on the number of concurrent operations supported.

When the import ends the ImportFinished event is raised returning the TaskID and True if the import succeeded.
If an Exception occurs the ImportError event is raised returning the TaskID and exception message.
The Exception is saved in LastException.
Initialize (eventname As String, usbdevice As android.hardware.usb.UsbDevice)
Open (connection As UsbDeviceConnectionWrapper) As Boolean
Opens the MTP device. Once the device is open it takes ownership of the UsbDeviceConnection.
connection must be an open UsbDeviceConnection for the device.
The connection will be closed when you call Close.
The connection will also be closed if this method fails.
Returns True of the device was successfully opened.

Unfortunately the Android MtpDevice API has no method of determining if a device supports MTP before opening it.
The behaviour of invoking this Open method on a non-MTP device varies with the device.
Some may appear to open correctly but will susequently throw NullPointerExceptions on access.
With other devices Open will hang the application until Android offers to force close it.
Version As Double [read only]
Returns the version of the library.

MtpObjectInfo

The MtpObjectInfo object encapsulates information about an object on an MTP device.
This corresponds to the ObjectInfo Dataset described in section 5.3.1 of the MTP specification.

Pass the return of MtpDevice.GetObjectInfo to the Initialize method to access details of an MTP Object.

Events:

None

Members:


  GetAssociationDesc As Int

  GetAssociationType As Int

  GetCompressedSize As Int

  GetDateCreated As Long

  GetDateModified As Long

  GetFormat As Int

  GetImagePixDepth As Int

  GetImagePixHeight As Int

  GetImagePixWidth As Int

  GetKeywords As String

  GetName As String

  GetObjectHandle As Int

  GetParent As Int

  GetProtectionStatus As Int

  GetSequenceNumber As Int

  GetStorageId As Int

  GetThumbCompressedSize As Int

  GetThumbFormat As Int

  GetThumbPixHeight As Int

  GetThumbPixWidth As Int

  Initialize (mtpobjectinfo As android.mtp.MtpObjectInfo)

Members description:

GetAssociationDesc As Int
Returns the association description for the MTP object.
Will be zero objects that are not of format FORMAT_ASSOCIATION.
GetAssociationType As Int
Returns the association type for the MTP object.
Will be zero for objects that are not of format FORMAT_ASSOCIATION.
For directories the association type is typically ASSOCIATION_TYPE_GENERIC_FOLDER.
GetCompressedSize As Int
Returns the size of the MTP object.
GetDateCreated As Long
Returns the creation date of the MTP object.
The value is represented as milliseconds since January 1, 1970.
GetDateModified As Long
Returns the modification date of the MTP object.
The value is represented as milliseconds since January 1, 1970
GetFormat As Int
Returns the format code for the MTP object.
GetImagePixDepth As Int
Returns the depth of the MTP object in bits per pixel.
Will be zero for non-image objects.
GetImagePixHeight As Int
Returns the height of the MTP object in pixels.
Will be zero for non-image objects.
GetImagePixWidth As Int
Returns the width of the MTP object in pixels.
Will be zero for non-image objects.
GetKeywords As String
Returns a comma separated list of keywords for the MTP object.
GetName As String
Returns the name of the MTP object. This will often be the file or folder name.
GetObjectHandle As Int
Returns the object handle for the MTP object.
GetParent As Int
Returns the object handle for the object's parent.
Will be zero if the parent is the root directory of a storage unit.
GetProtectionStatus As Int
Returns the protection status for the MTP object.
Possible values are:
PROTECTION_STATUS_NONE
PROTECTION_STATUS_READ_ONLY
PROTECTION_STATUS_NON_TRANSFERABLE_DATA
GetSequenceNumber As Int
Returns the sequence number for the MTP object.
This field is typically not used for MTP devices, but is sometimes used to define a sequence of photos on PTP cameras.
GetStorageId As Int
Returns the storage ID for the MTP object's storage unit.
GetThumbCompressedSize As Int
Returns the size of the MTP object's thumbnail.
Will be zero for objects with no thumbnail.
GetThumbFormat As Int
Returns the format code for the MTP object's thumbnail.
Will be zero for objects with no thumbnail.
GetThumbPixHeight As Int
Returns the height of the MTP object's thumbnail in pixels.
Will be zero for objects with no thumbnail.
GetThumbPixWidth As Int
Returns the width of the MTP object's thumbnail in pixels.
Will be zero for objects with no thumbnail.
Initialize (mtpobjectinfo As android.mtp.MtpObjectInfo)
Initialize this MtpObjectInfo with the MtpObjectInfo provided.
Top