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 :

Create / destroy connection to access MTP responder device
Get Device list
Get Storage list
Get Object handles
Get thumbnail
Get Object
Delete Object

Related Features

This API is related with the following features:

http://tizen.org/feature/network.mtp

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]	event	The event
[in]	event_parameter	The event parameter
[in]	user_data	The user data passed from the callback registration function

See also:: mtp_add_mtp_event_cb(); mtp_remove_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

enum mtp_error_e

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

enum mtp_event_e

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

enum mtp_filetype_e

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 all file types
MTP_FILETYPE_ALL_IMAGE	Helper enum value for all image files types
MTP_FILETYPE_HEIF	HEIF file type (Since 6.5)

enum mtp_storage_type_e

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.

This function registers a callback function that will be invoked whenever an MTP event occurs. By providing the callback function and optional user data as arguments, you can receive notifications regarding changes in device, storage, or object states, as well as the turning off of the MTP service.

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_cb	The callback
[in]	user_data	The user data

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
MTP_ERROR_NOT_INITIALIZED	MTP is not initialized

See also:: mtp_remove_mtp_event_cb()

int mtp_deinitialize ( void )

Deinitializes MTP operation.

This function terminates the usage of the Media Transfer Protocol (MTP) and frees up any associated resources. It is essential to call this API once you have completed all MTP operations and no longer require access to MTP devices

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_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_PERMISSION_DENIED	Permission Denied

See also:: mtp_initialize()

int mtp_get_devices	(	mtp_device_h **	mtp_devices,
		int *	device_count
	)

Gets the mtp devices.

Since :: 3.0

Remarks:: The mtp_devices should be released using free().

This function retrieves the list of available MTP (Media Transfer Protocol) devices connected to your system. By calling this API, you can explore the variety of MTP-enabled gadgets such as digital cameras, smartphones, and tablets accessible through your application.

Parameters:

[out]	mtp_devices	The MTP device list
[out]	device_count	Length of device list

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
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_COMM_ERROR	MTP 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.

This function extracts an object from a specified MTP device based on its object handle and transfers it to a destination path on the host storage. By providing the MTP device, object handle, and destination path as inputs, you can seamlessly move files and directories between the MTP device's internal or external storage and your application's local storage.

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_device	The MTP device
[in]	object_handle	The object handle
[in]	dest_path	The dest path

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_PERMISSION_DENIED	Permission denied
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
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_COMM_ERROR	MTP communication error
MTP_ERROR_IO_ERROR	I/O error

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.

This function retrieves the list of object handles associated with a specified MTP device and storage. By specifying the desired file type and parent object handle, you can navigate through the hierarchical structure of objects within the chosen storage compartment.

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_device	The MTP device
[in]	mtp_storage	The MTP storage
[in]	file_type	The file type what you want
[in]	parent	The parent object handle
[out]	object_handles	The object handle list
[out]	object_count	Length of object handle list

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
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_COMM_ERROR	MTP 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.

This function fetches the list of available MTP (Media Transfer Protocol) storages present in a specified MTP device. By invoking this API, you can explore the various storage options within the selected gadget, enabling seamless data transfer between your application and the device's internal or external storage compartments.

Since :: 3.0

Remarks:: The mtp_storages should be freed using free().

Parameters:

[in]	mtp_device	The MTP device
[out]	mtp_storages	Current mtp storage list
[out]	storage_count	Length of storage list

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
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_COMM_ERROR	MTP 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.

This function extracts a thumbnail image from a specified object handle in a MTP device and saves it to a designated location on the host storage. By providing the MTP device, object handle, and destination path as inputs, you can easily obtain thumbnails of images and videos stored within the MTP device's internal or external storage.

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_device	The MTP device
[in]	object_handle	The object handle
[in]	dest_path	The dest path

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_PERMISSION_DENIED	Permission denied
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
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_COMM_ERROR	MTP communication error
MTP_ERROR_IO_ERROR	I/O error

See also:: mtp_get_devices(); mtp_get_object_handles()

int mtp_initialize ( void )

Initializes for using MTP.

This function sets up the necessary environment for utilizing the Media Transfer Protocol (MTP). It must be called before performing any other MTP operations. By invoking this API, you enable your application to communicate with MTP devices such as digital cameras, smartphones, and tablets.

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_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_PERMISSION_DENIED	Permission Denied
MTP_ERROR_NOT_COMM_INITIALIZED	MTP communication is not initialized

See also:: mtp_deinitialize()

int mtp_remove_mtp_event_cb ( mtp_event_cb event_cb )

Removes the callback function.

This function unregisters a previously added callback function for receiving MTP events. By providing the callback function as an argument, you can stop receiving notifications regarding changes in device, storage, or object states, as well as the turning off of the MTP service.

Since :: 3.0

Parameters:

[in] event_cb The callback

Returns:: 0 on success, otherwise a negative error value.

Return values:

MTP_ERROR_NONE	Successful
MTP_ERROR_NOT_SUPPORTED	MTP is not supported
MTP_ERROR_INVALID_PARAMETER	Invalid parameter
MTP_ERROR_NOT_INITIALIZED	MTP is not initialized

See also:: mtp_add_mtp_event_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation