The basic device management API.

Defines
#define	LIBMTP_STORAGE_SORTBY_NOTSORTED   0
#define	LIBMTP_STORAGE_SORTBY_FREESPACE   1
#define	LIBMTP_STORAGE_SORTBY_MAXSPACE   2
Functions
int	LIBMTP_Detect_Descriptor (uint16_t *, uint16_t *)
LIBMTP_mtpdevice_t *	LIBMTP_Get_First_Device (void)
LIBMTP_error_number_t	LIBMTP_Get_Connected_Devices (LIBMTP_mtpdevice_t **)
uint32_t	LIBMTP_Number_Devices_In_List (LIBMTP_mtpdevice_t *)
void	LIBMTP_Release_Device_List (LIBMTP_mtpdevice_t *)
void	LIBMTP_Release_Device (LIBMTP_mtpdevice_t *)
void	LIBMTP_Dump_Device_Info (LIBMTP_mtpdevice_t *)
int	LIBMTP_Reset_Device (LIBMTP_mtpdevice_t *)
char *	LIBMTP_Get_Manufacturername (LIBMTP_mtpdevice_t *)
char *	LIBMTP_Get_Modelname (LIBMTP_mtpdevice_t *)
char *	LIBMTP_Get_Serialnumber (LIBMTP_mtpdevice_t *)
char *	LIBMTP_Get_Deviceversion (LIBMTP_mtpdevice_t *)
char *	LIBMTP_Get_Friendlyname (LIBMTP_mtpdevice_t *)
int	LIBMTP_Set_Friendlyname (LIBMTP_mtpdevice_t *, char const *const)
char *	LIBMTP_Get_Syncpartner (LIBMTP_mtpdevice_t *)
int	LIBMTP_Set_Syncpartner (LIBMTP_mtpdevice_t *, char const *const)
int	LIBMTP_Get_Batterylevel (LIBMTP_mtpdevice_t *, uint8_t *const, uint8_t *const)
int	LIBMTP_Get_Secure_Time (LIBMTP_mtpdevice_t *, char **const)
int	LIBMTP_Get_Device_Certificate (LIBMTP_mtpdevice_t *, char **const)
int	LIBMTP_Get_Supported_Filetypes (LIBMTP_mtpdevice_t *, uint16_t **const, uint16_t *const)
LIBMTP_error_t *	LIBMTP_Get_Errorstack (LIBMTP_mtpdevice_t *)
void	LIBMTP_Clear_Errorstack (LIBMTP_mtpdevice_t *)
void	LIBMTP_Dump_Errorstack (LIBMTP_mtpdevice_t *)
int	LIBMTP_Get_Storage (LIBMTP_mtpdevice_t *, int const)
int	LIBMTP_Format_Storage (LIBMTP_mtpdevice_t *, LIBMTP_devicestorage_t *)

---

Function Documentation

void LIBMTP_Clear_Errorstack

(

LIBMTP_mtpdevice_t *

device

)

This function clears the error stack of a device and frees any memory used by it. Call this when you're finished with using the errors.

Parameters:

device

a pointer to the MTP device to clear the error stack for.

References LIBMTP_error_struct::error_text, LIBMTP_mtpdevice_struct::errorstack, and LIBMTP_error_struct::next.

Referenced by LIBMTP_Release_Device().

int LIBMTP_Detect_Descriptor	(	uint16_t *	vid,
		uint16_t *	pid
	)

Detect the MTP device descriptor and return the VID and PID of the first device found. This is a very low-level function which is intended for use with udev or other hotplug mechanisms. The idea is that a script may want to know if the just plugged-in device was an MTP device or not.

Parameters:

	vid	the Vendor ID (VID) of the first device found.
	pid	the Product ID (PID) of the first device found.

Returns:

the number of detected devices or -1 if the call was unsuccessful.

void LIBMTP_Dump_Device_Info

(

LIBMTP_mtpdevice_t *

device

)

This function dumps out a large chunk of textual information provided from the PTP protocol and additionally some extra MTP-specific information where applicable.

Parameters:

device

a pointer to the MTP device to report info from.

References LIBMTP_devicestorage_struct::AccessCapability, LIBMTP_mtpdevice_struct::default_album_folder, LIBMTP_mtpdevice_struct::default_music_folder, LIBMTP_mtpdevice_struct::default_organizer_folder, LIBMTP_mtpdevice_struct::default_picture_folder, LIBMTP_mtpdevice_struct::default_playlist_folder, LIBMTP_mtpdevice_struct::default_text_folder, LIBMTP_mtpdevice_struct::default_video_folder, LIBMTP_mtpdevice_struct::default_zencast_folder, LIBMTP_devicestorage_struct::FilesystemType, LIBMTP_devicestorage_struct::FreeSpaceInBytes, LIBMTP_devicestorage_struct::FreeSpaceInObjects, LIBMTP_devicestorage_struct::id, LIBMTP_devicestorage_struct::MaxCapacity, LIBMTP_devicestorage_struct::next, LIBMTP_mtpdevice_struct::object_bitsize, LIBMTP_mtpdevice_struct::params, LIBMTP_mtpdevice_struct::storage, LIBMTP_devicestorage_struct::StorageDescription, LIBMTP_devicestorage_struct::StorageType, LIBMTP_mtpdevice_struct::usbinfo, and LIBMTP_devicestorage_struct::VolumeIdentifier.

void LIBMTP_Dump_Errorstack

(

LIBMTP_mtpdevice_t *

device

)

This function dumps the error stack to stderr. (You still have to clear the stack though.)

Parameters:

device

a pointer to the MTP device to dump the error stack for.

References LIBMTP_error_struct::error_text, LIBMTP_error_struct::errornumber, LIBMTP_mtpdevice_struct::errorstack, and LIBMTP_error_struct::next.

int LIBMTP_Format_Storage	(	LIBMTP_mtpdevice_t *	device,
		LIBMTP_devicestorage_t *	storage
	)

Formats device storage (if the device supports the operation). WARNING: This WILL delete all data from the device. Make sure you've got confirmation from the user BEFORE you call this function.

Parameters:

	device	a pointer to the device containing the storage to format.
	storage	the actual storage to format.

Returns:

0 on success, any other value means failure.

References LIBMTP_devicestorage_struct::id, and LIBMTP_mtpdevice_struct::params.

int LIBMTP_Get_Batterylevel	(	LIBMTP_mtpdevice_t *	device,
		uint8_t *const	maximum_level,
		uint8_t *const	current_level
	)

This function retrieves the current battery level on the device.

Parameters:

	device	a pointer to the device to get the battery level for.
	maximum_level	a pointer to a variable that will hold the maximum level of the battery if the call was successful.
	current_level	a pointer to a variable that will hold the current level of the battery if the call was successful. A value of 0 means that the device is on external power.

Returns:

0 if the storage info was successfully retrieved, any other means failure. A typical cause of failure is that the device does not support the battery level property.

References LIBMTP_mtpdevice_struct::maximum_battery_level, and LIBMTP_mtpdevice_struct::params.

LIBMTP_error_number_t LIBMTP_Get_Connected_Devices

(

LIBMTP_mtpdevice_t **

device_list

)

Get the first connected MTP device node in the linked list of devices. Currently this only provides access to USB devices

Parameters:

device_list

A list of devices ready to be used by the caller. You need to know how many there are.

Returns:

Any error information gathered from device connections

See also:

LIBMTP_Number_Devices_In_List()

Referenced by LIBMTP_Get_First_Device().

int LIBMTP_Get_Device_Certificate	(	LIBMTP_mtpdevice_t *	device,
		char **const	devcert
	)

This function returns the device (public key) certificate as an XML document string from the device.

Parameters:

	device	a pointer to the device to get the device certificate for.
	devcert	the device certificate as an XML string or NULL if the call failed or the device certificate property is not supported. This string must be free():ed by the caller after use.

Returns:

0 on success, any other value means failure.

char* LIBMTP_Get_Deviceversion

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the device version (hardware and firmware version) of an MTP device.

Parameters:

device

a pointer to the device to get the device version for.

Returns:

a newly allocated UTF-8 string representing the device version. The string must be freed by the caller after use. If the call was unsuccessful this will contain NULL.

References LIBMTP_mtpdevice_struct::params.

LIBMTP_error_t* LIBMTP_Get_Errorstack

(

LIBMTP_mtpdevice_t *

device

)

This returns the error stack for a device in case you need to either reference the error numbers (e.g. when creating multilingual apps with multiple-language text representations for each error number) or when you need to build a multi-line error text widget or something like that. You need to call the LIBMTP_Clear_Errorstack to clear it when you're finished with it.

Parameters:

device

a pointer to the MTP device to get the error stack for.

Returns:

the error stack or NULL if there are no errors on the stack.

See also:

LIBMTP_Clear_Errorstack()

LIBMTP_Dump_Errorstack()

References LIBMTP_mtpdevice_struct::errorstack.

LIBMTP_mtpdevice_t* LIBMTP_Get_First_Device

(

void

)

Get the first (as in "first in the list of") connected MTP device.

Returns:

a device pointer.

See also:

LIBMTP_Get_Connected_Devices()

References LIBMTP_Get_Connected_Devices(), LIBMTP_Release_Device_List(), and LIBMTP_mtpdevice_struct::next.

char* LIBMTP_Get_Friendlyname

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the "friendly name" of an MTP device. Usually this is simply the name of the owner or something like "John Doe's Digital Audio Player". This property should be supported by all MTP devices.

Parameters:

device

a pointer to the device to get the friendly name for.

Returns:

a newly allocated UTF-8 string representing the friendly name. The string must be freed by the caller after use.

See also:

LIBMTP_Set_Friendlyname()

References LIBMTP_mtpdevice_struct::params.

char* LIBMTP_Get_Manufacturername

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the manufacturer name of an MTP device.

Parameters:

device

a pointer to the device to get the manufacturer name for.

Returns:

a newly allocated UTF-8 string representing the manufacturer name. The string must be freed by the caller after use. If the call was unsuccessful this will contain NULL.

References LIBMTP_mtpdevice_struct::params.

char* LIBMTP_Get_Modelname

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the model name (often equal to product name) of an MTP device.

Parameters:

device

a pointer to the device to get the model name for.

Returns:

a newly allocated UTF-8 string representing the model name. The string must be freed by the caller after use. If the call was unsuccessful this will contain NULL.

References LIBMTP_mtpdevice_struct::params.

int LIBMTP_Get_Secure_Time	(	LIBMTP_mtpdevice_t *	device,
		char **const	sectime
	)

This function returns the secure time as an XML document string from the device.

Parameters:

	device	a pointer to the device to get the secure time for.
	sectime	the secure time string as an XML document or NULL if the call failed or the secure time property is not supported. This string must be free():ed by the caller after use.

Returns:

0 on success, any other value means failure.

char* LIBMTP_Get_Serialnumber

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the serial number of an MTP device.

Parameters:

device

a pointer to the device to get the serial number for.

Returns:

a newly allocated UTF-8 string representing the serial number. The string must be freed by the caller after use. If the call was unsuccessful this will contain NULL.

References LIBMTP_mtpdevice_struct::params.

int LIBMTP_Get_Storage	(	LIBMTP_mtpdevice_t *	device,
		int const	sortby
	)

This function updates all the storage id's of a device and their properties, then creates a linked list and puts the list head into the device struct. It also optionally sorts this list. If you want to display storage information in your application you should call this function, then dereference the device struct (device->storage) to get out information on the storage.

You need to call this everytime you want to update the device->storage list, for example anytime you need to check available storage somewhere.

WARNING: since this list is dynamically updated, do not reference its fields in external applications by pointer! E.g do not put a reference to any char * field. instead strncpy() it!

Parameters:

	device	a pointer to the device to get the filetype capabilities for.
	sortby	an integer that determines the sorting of the storage list. Valid sort methods are defined in libmtp.h with beginning with LIBMTP_STORAGE_SORTBY_. 0 or LIBMTP_STORAGE_SORTBY_NOTSORTED to not sort.

Returns:

0 on success, 1 success but only with storage id's, storage properities could not be retrieved and -1 means failure.

See also:

LIBMTP_Get_Filetype_Description()

References LIBMTP_devicestorage_struct::AccessCapability, LIBMTP_devicestorage_struct::FilesystemType, LIBMTP_devicestorage_struct::FreeSpaceInBytes, LIBMTP_devicestorage_struct::FreeSpaceInObjects, LIBMTP_devicestorage_struct::id, LIBMTP_devicestorage_struct::MaxCapacity, LIBMTP_devicestorage_struct::next, LIBMTP_mtpdevice_struct::params, LIBMTP_devicestorage_struct::prev, LIBMTP_mtpdevice_struct::storage, LIBMTP_devicestorage_struct::StorageDescription, LIBMTP_devicestorage_struct::StorageType, and LIBMTP_devicestorage_struct::VolumeIdentifier.

int LIBMTP_Get_Supported_Filetypes	(	LIBMTP_mtpdevice_t *	device,
		uint16_t **const	filetypes,
		uint16_t *const	length
	)

This function retrieves a list of supported file types, i.e. the file types that this device claims it supports, e.g. audio file types that the device can play etc. This list is mitigated to inlcude the file types that libmtp can handle, i.e. it will not list filetypes that libmtp will handle internally like playlists and folders.

Parameters:

	device	a pointer to the device to get the filetype capabilities for.
	filetypes	a pointer to a pointer that will hold the list of supported filetypes if the call was successful. This list must be free():ed by the caller after use.
	length	a pointer to a variable that will hold the length of the list of supported filetypes if the call was successful.

Returns:

0 on success, any other value means failure.

See also:

LIBMTP_Get_Filetype_Description()

References DEVICE_FLAG_OGG_IS_UNKNOWN, LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

char* LIBMTP_Get_Syncpartner

(

LIBMTP_mtpdevice_t *

device

)

This retrieves the syncronization partner of an MTP device. This property should be supported by all MTP devices.

Parameters:

device

a pointer to the device to get the sync partner for.

Returns:

a newly allocated UTF-8 string representing the synchronization partner. The string must be freed by the caller after use.

See also:

LIBMTP_Set_Syncpartner()

References LIBMTP_mtpdevice_struct::params.

uint32_t LIBMTP_Number_Devices_In_List

(

LIBMTP_mtpdevice_t *

device_list

)

Get the number of devices that are available in the listed device list

Parameters:

device_list

Pointer to a linked list of devices

Returns:

Number of devices in the device list device_list

See also:

LIBMTP_Get_Connected_Devices()

References LIBMTP_mtpdevice_struct::next.

void LIBMTP_Release_Device

(

LIBMTP_mtpdevice_t *

device

)

This closes and releases an allocated MTP device.

Parameters:

device

a pointer to the MTP device to release.

References LIBMTP_Clear_Errorstack(), LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

Referenced by LIBMTP_Release_Device_List().

void LIBMTP_Release_Device_List

(

LIBMTP_mtpdevice_t *

device

)

This closes and releases an allocated MTP device.

Parameters:

device

a pointer to the MTP device to release.

References LIBMTP_Release_Device(), LIBMTP_Release_Device_List(), and LIBMTP_mtpdevice_struct::next.

Referenced by LIBMTP_Get_First_Device(), and LIBMTP_Release_Device_List().

int LIBMTP_Reset_Device

(

LIBMTP_mtpdevice_t *

device

)

This resets a device in case it supports the PTP_OC_ResetDevice operation code (0x1010).

Parameters:

device

a pointer to the device to reset.

Returns:

0 on success, any other value means failure.

References LIBMTP_mtpdevice_struct::params.

int LIBMTP_Set_Friendlyname	(	LIBMTP_mtpdevice_t *	device,
		char const *const	friendlyname
	)

Sets the "friendly name" of an MTP device.

Parameters:

	device	a pointer to the device to set the friendly name for.
	friendlyname	the new friendly name for the device.

Returns:

0 on success, any other value means failure.

See also:

LIBMTP_Get_Ownername()

References LIBMTP_mtpdevice_struct::params.

int LIBMTP_Set_Syncpartner	(	LIBMTP_mtpdevice_t *	device,
		char const *const	syncpartner
	)

Sets the synchronization partner of an MTP device. Note that we have no idea what the effect of setting this to "foobar" may be. But the general idea seems to be to tell which program shall synchronize with this device and tell others to leave it alone.

Parameters:

	device	a pointer to the device to set the sync partner for.
	syncpartner	the new synchronization partner for the device.

Returns:

0 on success, any other value means failure.

See also:

LIBMTP_Get_Syncpartner()

References LIBMTP_mtpdevice_struct::params.