Tizen Native API  4.0
MTP Manager

The MTP Manager API provides functions for establish connection to access MTP responder device, and to Get/Delete files.

Required Header

#include <mtp.h>

Overview

The MTP manager api provides following functions :

Related Features

This API is related with the following features:

It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions

int mtp_initialize (void)
 Initializes for using MTP.
int mtp_get_devices (mtp_device_h **mtp_devices, int *device_count)
 Gets the mtp devices.
int mtp_get_storages (mtp_device_h mtp_device, mtp_storage_h **mtp_storages, int *storage_count)
 Gets mtp storages from the given device.
int mtp_get_object_handles (mtp_device_h mtp_device, mtp_storage_h mtp_storage, mtp_filetype_e file_type, mtp_object_h parent, mtp_object_h **object_handles, int *object_count)
 Gets object handles from the given device and storage.
int mtp_get_object (mtp_device_h mtp_device, mtp_object_h object_handle, char *dest_path)
 Gets object for a given path from object handle.
int mtp_get_thumbnail (mtp_device_h mtp_device, mtp_object_h object_handle, char *dest_path)
 Gets thumbnail from the given object handle.
int mtp_add_mtp_event_cb (mtp_event_cb event_cb, void *user_data)
 Adds a callback function for receiving MTP event.
int mtp_remove_mtp_event_cb (mtp_event_cb event_cb)
 Removes the callback function.
int mtp_deinitialize (void)
 Deinitializes MTP operation.

Typedefs

typedef int mtp_device_h
 The handle to the mtp device.
typedef int mtp_storage_h
 The handle to the mtp storage.
typedef int mtp_object_h
 The handle to the mtp object.
typedef void(* mtp_event_cb )(mtp_event_e event, int event_parameter, void *user_data)
 Called when mtp event is occured.

Typedef Documentation

typedef int mtp_device_h

The handle to the mtp device.

Since :
3.0
typedef void(* mtp_event_cb)(mtp_event_e event, int event_parameter, void *user_data)

Called when mtp event is occured.

Since :
3.0
Remarks:
Depending on the type of event, the meaning of event parameter is different.
  • If event is device event, then event_parameter type is mtp_device_h.
  • If event is storage event, then event_parameter type is mtp_storage_h.
  • If event is object event, then event_parameter type is mtp_object_h.
  • If event is MTP_EVENT_TURNED_OFF, then event_parameter is 0.
Parameters:
[in]eventThe event
[in]event_parameterThe event parameter
[in]user_dataThe user data passed from the callback registration function
See also:
mtp_set_mtp_event_cb()
mtp_unset_mtp_event_cb()
typedef int mtp_object_h

The handle to the mtp object.

Since :
3.0
typedef int mtp_storage_h

The handle to the mtp storage.

Since :
3.0

Enumeration Type Documentation

Error codes reported by the MTP API.

Since :
3.0
Enumerator:
MTP_ERROR_NONE 

Successful

MTP_ERROR_IO_ERROR 

I/O error

MTP_ERROR_INVALID_PARAMETER 

Invalid parameter

MTP_ERROR_OUT_OF_MEMORY 

Out of memory

MTP_ERROR_PERMISSION_DENIED 

Permission denied

MTP_ERROR_NOT_SUPPORTED 

Not supported

MTP_ERROR_COMM_ERROR 

MTP communication error

MTP_ERROR_CONTROLLER 

MTP controller error

MTP_ERROR_NO_DEVICE 

MTP have not any device

MTP_ERROR_NOT_INITIALIZED 

MTP is not initialized

MTP_ERROR_NOT_ACTIVATED 

MTP is not activated

MTP_ERROR_NOT_COMM_INITIALIZED 

MTP communication is not initialized

MTP_ERROR_PLUGIN_FAIL 

MTP Plugin failed

Enumerations for MTP event type.

Since :
3.0
Enumerator:
MTP_EVENT_UNKNOWN 

Unknown event type

MTP_EVENT_STORAGE_ADDED 

Storage is added

MTP_EVENT_STORAGE_REMOVED 

Storage is removed

MTP_EVENT_OBJECT_ADDED 

Object is added

MTP_EVENT_OBJECT_REMOVED 

Object is removed

MTP_EVENT_DEVICE_ADDED 

Device is added

MTP_EVENT_DEVICE_REMOVED 

Device is removed

MTP_EVENT_TURNED_OFF 

MTP is turned off

Enumerations for MTP file type.

Since :
3.0
Enumerator:
MTP_FILETYPE_FOLDER 

FOLDER file type

MTP_FILETYPE_WAV 

WAV file type

MTP_FILETYPE_MP3 

MP3 file type

MTP_FILETYPE_WMA 

WMA file type

MTP_FILETYPE_OGG 

OGG file type

MTP_FILETYPE_AUDIBLE 

AUDIBLE file type

MTP_FILETYPE_MP4 

MP4 file type

MTP_FILETYPE_UNDEF_AUDIO 

UNDEF_AUDIO file type

MTP_FILETYPE_WMV 

WMV file type

MTP_FILETYPE_AVI 

AVI file type

MTP_FILETYPE_MPEG 

MPEG file type

MTP_FILETYPE_ASF 

ASF file type

MTP_FILETYPE_QT 

QT file type

MTP_FILETYPE_UNDEF_VIDEO 

UNDEF_VIDEO file type

MTP_FILETYPE_JPEG 

JPEG file type

MTP_FILETYPE_JFIF 

JFIF file type

MTP_FILETYPE_TIFF 

TIFF file type

MTP_FILETYPE_BMP 

BMP file type

MTP_FILETYPE_GIF 

GIF file type

MTP_FILETYPE_PICT 

PICT file type

MTP_FILETYPE_PNG 

PNG file type

MTP_FILETYPE_VCALENDAR1 

VCALENDAR1 file type

MTP_FILETYPE_VCALENDAR2 

VCALENDAR2 file type

MTP_FILETYPE_VCARD2 

VCARD2 file type

MTP_FILETYPE_VCARD3 

VCARD3 file type

MTP_FILETYPE_WINDOWSIMAGEFORMAT 

WINDOWSIMAGEFORMAT file type

MTP_FILETYPE_WINEXEC 

WINEXEC file type

MTP_FILETYPE_TEXT 

TEXT file type

MTP_FILETYPE_HTML 

HTML file type

MTP_FILETYPE_FIRMWARE 

FIRMWARE file type

MTP_FILETYPE_AAC 

AAC file type

MTP_FILETYPE_MEDIACARD 

MEDIACARD file type

MTP_FILETYPE_FLAC 

FLAC file type

MTP_FILETYPE_MP2 

MP2 file type

MTP_FILETYPE_M4A 

M4A file type

MTP_FILETYPE_DOC 

DOC file type

MTP_FILETYPE_XML 

XML file type

MTP_FILETYPE_XLS 

XLS file type

MTP_FILETYPE_PPT 

PPT file type

MTP_FILETYPE_MHT 

MHT file type

MTP_FILETYPE_JP2 

JP2 file type

MTP_FILETYPE_JPX 

JPX file type

MTP_FILETYPE_ALBUM 

ALBUM file type

MTP_FILETYPE_PLAYLIST 

PLAYLIST file type

MTP_FILETYPE_UNKNOWN 

Unknown file type

MTP_FILETYPE_ALL 

Helper enum value for certain function

MTP_FILETYPE_ALL_IMAGE 

Helper enum value for certain function

Enumerations for MTP Storage type.

Since :
3.0
Enumerator:
MTP_STORAGE_TYPE_UNDEFINED 

Storage type is undefined

MTP_STORAGE_TYPE_FIXED_ROM 

Storage type is fixed ROM

MTP_STORAGE_TYPE_REMOVABLE_ROM 

Storage type is removable ROM

MTP_STORAGE_TYPE_FIXED_RAM 

Storage type is fixed RAM

MTP_STORAGE_TYPE_REMOVABLE_RAM 

Storage type is Removable RAM


Function Documentation

int mtp_add_mtp_event_cb ( mtp_event_cb  event_cb,
void *  user_data 
)

Adds a callback function for receiving MTP event.

Since :
3.0
Remarks:
You can register multiple callback.
If you don't want to receive the event, then using the mtp_remove_mtp_event_cb() function to unregister a callback.
If device state is changed, MTP_EVENT_DEVICE_ADDED or MTP_EVENT_DEVICE_REMOVED event is occur.
If storage state is changed, MTP_EVENT_STORAGE_ADDED or MTP_EVENT_STORAGE_REMOVED event is occur.
If object state is changed, MTP_EVENT_OBJECT_ADDED or MTP_EVENT_OBJECT_REMOVED event is occur.
If mtp service is turned off, MTP_EVENT_TURNED_OFF event is occur.
Parameters:
[in]event_cbThe callback
[in]user_dataThe user data
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mtp_remove_mtp_event_cb()
int mtp_deinitialize ( void  )

Deinitializes MTP operation.

Since :
3.0
Remarks:
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_PERMISSION_DENIEDPermission Denied
See also:
mtp_initialize()
int mtp_get_devices ( mtp_device_h **  mtp_devices,
int *  device_count 
)

Gets the mtp devices.

Since :
3.0
Parameters:
[out]mtp_devicesThe MTP device list
[out]device_countLength of device list
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_NOT_ACTIVATEDMTP is not activated
MTP_ERROR_INVALID_PARAMETERInvalid parameter
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
MTP_ERROR_COMM_ERRORMTP communication error
See also:
mtp_initialize()
int mtp_get_object ( mtp_device_h  mtp_device,
mtp_object_h  object_handle,
char *  dest_path 
)

Gets object for a given path from object handle.

Since :
3.0
Remarks:
The dest_path is host storage path.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
Parameters:
[in]mtp_deviceThe MTP device
[in]object_handleThe object handle
[in]dest_pathThe dest path
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_NOT_ACTIVATEDMTP is not activated
MTP_ERROR_INVALID_PARAMETERInvalid parameter
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
MTP_ERROR_COMM_ERRORMTP communication error
MTP_ERROR_IO_ERRORI/O error
MTP_ERROR_PERMISSION_DENIEDPermission denied
See also:
mtp_get_devices()
mtp_get_object_handles()
int mtp_get_object_handles ( mtp_device_h  mtp_device,
mtp_storage_h  mtp_storage,
mtp_filetype_e  file_type,
mtp_object_h  parent,
mtp_object_h **  object_handles,
int *  object_count 
)

Gets object handles from the given device and storage.

Since :
3.0
Remarks:
The object_handles should be freed using free().
If the parent is 0, it means "root folder" of mtp storage.
Parameters:
[in]mtp_deviceThe MTP device
[in]mtp_storageThe MTP storage
[in]file_typeThe file type what you want
[in]parentThe parent object handle
[out]object_handlesThe object handle list
[out]object_countLength of object handle list
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_NOT_ACTIVATEDMTP is not activated
MTP_ERROR_INVALID_PARAMETERInvalid parameter
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
MTP_ERROR_COMM_ERRORMTP communication error
See also:
mtp_get_devices()
mtp_get_storages()
int mtp_get_storages ( mtp_device_h  mtp_device,
mtp_storage_h **  mtp_storages,
int *  storage_count 
)

Gets mtp storages from the given device.

Since :
3.0
Remarks:
The mtp_storages should be freed using free().
Parameters:
[in]mtp_deviceThe MTP device
[out]mtp_storagesCurrent mtp storage list
[out]storage_countLength of storage list
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_NOT_ACTIVATEDMTP is not activated
MTP_ERROR_INVALID_PARAMETERInvalid parameter
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
MTP_ERROR_COMM_ERRORMTP communication error
See also:
mtp_get_devices()
int mtp_get_thumbnail ( mtp_device_h  mtp_device,
mtp_object_h  object_handle,
char *  dest_path 
)

Gets thumbnail from the given object handle.

Since :
3.0
Remarks:
The dest_path is host storage path.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
Parameters:
[in]mtp_deviceThe MTP device
[in]object_handleThe object handle
[in]dest_pathThe dest path
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_NOT_ACTIVATEDMTP is not activated
MTP_ERROR_INVALID_PARAMETERInvalid parameter
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
MTP_ERROR_COMM_ERRORMTP communication error
MTP_ERROR_IO_ERRORI/O error
MTP_ERROR_PERMISSION_DENIEDPermission denied
See also:
mtp_get_devices()
mtp_get_object_handles()
int mtp_initialize ( void  )

Initializes for using MTP.

Since :
3.0
Remarks:
This function must be called before proceeding any other mtp functions.
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_PERMISSION_DENIEDPermission Denied
MTP_ERROR_NOT_COMM_INITIALIZEDMTP communication is not initialized
See also:
mtp_deinitialize()

Removes the callback function.

Since :
3.0
Parameters:
[in]event_cbThe callback
Returns:
0 on success, otherwise a negative error value.
Return values:
MTP_ERROR_NONESuccessful
MTP_ERROR_NOT_SUPPORTEDMTP is not supported
MTP_ERROR_NOT_INITIALIZEDMTP is not initialized
MTP_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mtp_add_mtp_event_cb()