libmtp: The basic device management API.

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.

Examples:: detect.c.

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.

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 value means failure. A typical cause of failure is that the device does not support the battery level property.

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.

LIBMTP_mtpdevice_t* LIBMTP_Get_First_Device ( void )

Get the first connected MTP device. There is currently no API for retrieveing multiple devices.

Returns:: a device pointer.

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()

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.

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.

int LIBMTP_Get_Storageinfo	(	LIBMTP_mtpdevice_t *	device,
		uint64_t *const	total,
		uint64_t *const	free,
		char **const	storage_description,
		char **const	volume_label
	)

This function finds out how much storage space is currently used and any additional storage information. Storage may be a hard disk or flash memory or whatever.

Parameters:

	device	a pointer to the device to get the storage info for.
	total	a pointer to a variable that will hold the total the total number of bytes available on this volume after the call.
	free	a pointer to a variable that will hold the number of free bytes available on this volume right now after the call.
	storage_description	a description of the storage. This may be NULL after the call even if it succeeded. If it is not NULL, it must be freed by the callee after use.
	volume_label	a volume label or similar. This may be NULL after the call even if it succeeded. If it is not NULL, it must be freed by the callee after use.

Returns:: 0 if the storage info was successfully retrieved, any other value means failure.

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()

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()

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.

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()

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()


Functions
int	LIBMTP_Detect_Descriptor (uint16_t , uint16_t )
LIBMTP_mtpdevice_t *	LIBMTP_Get_First_Device (void)
void	LIBMTP_Release_Device (LIBMTP_mtpdevice_t *)
void	LIBMTP_Dump_Device_Info (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_Storageinfo (LIBMTP_mtpdevice_t , uint64_t const, uint64_t const, char const storage_description, char *const volume_label)
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)

The basic device management API.

Functions

Function Documentation