libmtp: The basic device management API.

- Main Page
- Modules
- Data Structures
- Files
- Directories
- Examples

# The basic device management API.

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

## Function Documentation

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