basic(3)

📦
version 1.1.23 · 6 versions
, in ubuntu stonking

✨ basic(3) ✨

okay so bestie 💖 welcome to the basic page of libmtp — the Library Functions Manual energy, but make it slay. This is the whole "talk to your phone / MP3 player / camera over MTP" foundation: detecting raw devices, opening them, reading their names, their battery, their storage, their properties, and cleaning up after yourself like a responsible icon. Lowkey everything here is the groundwork. No cap.

🫶 NAME 🫶

libmtp — basic

🎀 SYNOPSIS 🎀

Macros

#define LIBMTP_STORAGE_SORTBY_NOTSORTED   0
#define LIBMTP_STORAGE_SORTBY_FREESPACE   1
#define LIBMTP_STORAGE_SORTBY_MAXSPACE    2

Functions

LIBMTP_error_number_t LIBMTP_Detect_Raw_Devices (LIBMTP_raw_device_t **, int *)
int LIBMTP_Check_Specific_Device (int busno, int devno)
LIBMTP_mtpdevice_t * LIBMTP_Open_Raw_Device (LIBMTP_raw_device_t *)
LIBMTP_mtpdevice_t * LIBMTP_Open_Raw_Device_Uncached (LIBMTP_raw_device_t *)
LIBMTP_mtpdevice_t * LIBMTP_Get_Device (int)
LIBMTP_mtpdevice_t * LIBMTP_Get_First_Device (void)
LIBMTP_mtpdevice_t * LIBMTP_Get_Device_By_SerialNumber (char *)
LIBMTP_mtpdevice_t * LIBMTP_Get_Device_By_ID (char *)
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)
int LIBMTP_Check_Capability (LIBMTP_mtpdevice_t *, LIBMTP_devicecap_t)
LIBMTP_error_t * LIBMTP_Get_Errorstack (LIBMTP_mtpdevice_t *)
void LIBMTP_Clear_Errorstack (LIBMTP_mtpdevice_t *)
void LIBMTP_Dump_Errorstack (LIBMTP_mtpdevice_t *)
void LIBMTP_FreeMemory (void *)
int LIBMTP_Get_Storage (LIBMTP_mtpdevice_t *, int const)
int LIBMTP_Format_Storage (LIBMTP_mtpdevice_t *, LIBMTP_devicestorage_t *)
char * LIBMTP_Get_String_From_Object (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const)
uint64_t LIBMTP_Get_u64_From_Object (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint64_t const)
uint32_t LIBMTP_Get_u32_From_Object (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint32_t const)
uint16_t LIBMTP_Get_u16_From_Object (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint16_t const)
uint8_t LIBMTP_Get_u8_From_Object (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint8_t const)
int LIBMTP_Set_Object_String (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, char const *const)
int LIBMTP_Set_Object_u32 (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint32_t const)
int LIBMTP_Set_Object_u16 (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint16_t const)
int LIBMTP_Set_Object_u8 (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const, uint8_t const)
char const * LIBMTP_Get_Property_Description (LIBMTP_property_t inproperty)
int LIBMTP_Is_Property_Supported (LIBMTP_mtpdevice_t *, LIBMTP_property_t const, LIBMTP_filetype_t const)
int LIBMTP_Get_Allowed_Property_Values (LIBMTP_mtpdevice_t *, LIBMTP_property_t const, LIBMTP_filetype_t const, LIBMTP_allowed_values_t *)
void LIBMTP_destroy_allowed_values_t (LIBMTP_allowed_values_t *)

👑 Detailed Description 👑

This heading is genuinely empty in the original, bestie — the whole personality lives down in Function Documentation. Keep scrolling. 👇

🧚 Function Documentation 🧚

int LIBMTP_Check_Capability (LIBMTP_mtpdevice_t * device, LIBMTP_devicecap_t cap)

This one vibe-checks whether your device actually has certain capabilities, so you don't go calling APIs that would just confuse or disturb the poor thing. Politeness is free, fr fr.

Parameters

  • device — a pointer to the device you want to check the capability on.
  • cap — the capability you're asking about.

Returns

0 if it's not supported. Any other value means yes, the device has the requested capability. ✨

References: LIBMTP_DEVICECAP_CopyObject, LIBMTP_DEVICECAP_EditObjects, LIBMTP_DEVICECAP_GetPartialObject, LIBMTP_DEVICECAP_MoveObject, LIBMTP_DEVICECAP_SendPartialObject, and LIBMTP_mtpdevice_struct::params.

int LIBMTP_Check_Specific_Device (int busno, int devno)

Checks whether one specific device — identified by its bus number and its device number — has an MTP type device descriptor. It's giving "are you the one, or not." 🔍

Parameters

  • busno — the bus number of the device to check.
  • devno — the device number of the device to check.

Returns

1 if the device is MTP, else 0.

void LIBMTP_Clear_Errorstack (LIBMTP_mtpdevice_t * device)

Clears the error stack of a device and frees every scrap of memory it was using. Call this once you're done with the errors — like closing the group chat when the drama's over. 🧹

Parameters

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

References: LIBMTP_mtpdevice_struct::errorstack.

Referenced by: LIBMTP_Release_Device().

void LIBMTP_destroy_allowed_values_t (LIBMTP_allowed_values_t * allowed_vals)

Destroys a LIBMTP_allowed_values_t struct. It had a good run, bestie. 🪦

Parameters

  • allowed_vals — the struct to destroy.

References: LIBMTP_allowed_values_struct::datatype, and LIBMTP_allowed_values_struct::is_range.

LIBMTP_error_number_t LIBMTP_Detect_Raw_Devices (LIBMTP_raw_device_t ** devices, int * numdevs)

Detects the raw MTP device descriptors and hands you back a whole list of the devices it found. This is like the first step of every MTP journey — you can't open a device you haven't even spotted. 👀

Parameters

  • devices — a pointer to a variable that will hold the list of raw devices found. This may be NULL on return if the number of detected devices is zero. The user shall simply free() this variable when finished with the raw devices, in order to release memory.
  • numdevs — a pointer to an integer that will hold the number of devices in the list. This may be 0.

Returns

0 if successful. Any other value means failure. 💀

Examples

detect.c, files.c, folders.c, and tracks.c.

References: LIBMTP_raw_device_struct::bus_location, LIBMTP_raw_device_struct::device_entry, LIBMTP_device_entry_struct::device_flags, device_unknown(), LIBMTP_raw_device_struct::devnum, LIBMTP_device_entry_struct::product, LIBMTP_device_entry_struct::product_id, LIBMTP_device_entry_struct::vendor, and LIBMTP_device_entry_struct::vendor_id.

Referenced by: LIBMTP_Get_Connected_Devices(), LIBMTP_Get_Device(), and LIBMTP_Get_Device_By_SerialNumber().

void LIBMTP_Dump_Device_Info (LIBMTP_mtpdevice_t * device)

Dumps out a big glorious chunk of textual info straight from the PTP protocol, plus a lil extra MTP-specific info where it applies. It's the "tell me everything about yourself" button. 📋✨

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_mtpdevice_struct::extensions, LIBMTP_devicestorage_struct::FilesystemType, LIBMTP_devicestorage_struct::FreeSpaceInBytes, LIBMTP_devicestorage_struct::FreeSpaceInObjects, LIBMTP_devicestorage_struct::id, LIBMTP_Get_Property_Description(), LIBMTP_device_extension_struct::major, LIBMTP_devicestorage_struct::MaxCapacity, LIBMTP_device_extension_struct::minor, LIBMTP_device_extension_struct::name, LIBMTP_device_extension_struct::next, 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)

Dumps the error stack to stderr. Important lil caveat, bestie: you still have to clear the stack yourself afterwards. (Yeah. It doesn't do that part for you. 😭)

Parameters

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

References: LIBMTP_mtpdevice_struct::errorstack.

int LIBMTP_Format_Storage (LIBMTP_mtpdevice_t * device, LIBMTP_devicestorage_t * storage)

Formats device storage — if the device even supports the operation.

⚠️ WARNING, and I mean it: This WILL delete all data from the device. Make absolutely sure you've got confirmation from the user BEFORE you call this function. Not "probably fine," not "they clicked something once" — actual confirmation. This is the delete-everything button and it does not come with an undo. 💀🚨

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.

void LIBMTP_FreeMemory (void * mem)

Frees memory that was allocated by libmtp. In most cases it's doing the exact same thing as libc's free(mem). @mem pointer to allocated memory. 🫶

int LIBMTP_Get_Allowed_Property_Values (LIBMTP_mtpdevice_t * device, LIBMTP_property_t const property, LIBMTP_filetype_t const filetype, LIBMTP_allowed_values_t * allowed_vals)

Gets the allowed values — whether that's a range or an enum — for a property. It's the "what are my options here" call. 🌈

Parameters

  • device — a pointer to an MTP device.
  • property — the property to query.
  • filetype — the filetype of the object you want to set values for.
  • allowed_vals — pointer to a LIBMTP_allowed_values_t struct to receive the allowed values. Call LIBMTP_destroy_allowed_values_t on this on successful completion.

Returns

0 on success. Any other value means failure.

References: LIBMTP_allowed_values_struct::datatype, LIBMTP_allowed_values_struct::is_range, LIBMTP_allowed_values_struct::num_entries, and LIBMTP_mtpdevice_struct::params.

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

Retrieves the current battery level on the device. Gotta know when your fave is running low. 🔋

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, LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

LIBMTP_Get_Connected_Devices()

aka "gimme the whole squad at once"

LIBMTP_error_number_t LIBMTP_Get_Connected_Devices (LIBMTP_mtpdevice_t ** device_list)

Gets the first connected MTP device node in the linked list of devices. Currently this only provides access to USB devices. (so if you were hoping for something wireless, bestie, not today 😭)

Parameters

  • *device_list* — a list of devices all ready to be used by you, the caller. Heads up tho: you need to know how many there are. It does not tell you. 👀

Returns

  • Any error information gathered from device connections.

See also

  • LIBMTP_Number_Devices_In_List()

References: LIBMTP_Detect_Raw_Devices().

LIBMTP_Get_Device()

LIBMTP_mtpdevice_t * LIBMTP_Get_Device (int device_nr)

Get a connected MTP device by list position. Like, "gimme device number 3" energy. 💅

Returns

  • a device pointer.

See also

  • LIBMTP_Get_Connected_Devices()

References: LIBMTP_Detect_Raw_Devices().

Referenced by: LIBMTP_Get_Device_By_ID(), and LIBMTP_Get_First_Device().

LIBMTP_Get_Device_By_ID()

LIBMTP_mtpdevice_t * LIBMTP_Get_Device_By_ID (char * device_id)

Get a connected MTP device by list position or by serial number — it's flexible like that. ✨

Returns

  • a device pointer.

See also

  • LIBMTP_Get_Connected_Devices()

References: LIBMTP_Get_Device(), and LIBMTP_Get_Device_By_SerialNumber().

LIBMTP_Get_Device_By_SerialNumber()

LIBMTP_mtpdevice_t * LIBMTP_Get_Device_By_SerialNumber (char * serial_number)

Get a connected MTP device by serial number. Every device has its own lil fingerprint, iykyk. 🦋

Returns

  • a device pointer.

See also

  • LIBMTP_Get_Connected_Devices()

References: LIBMTP_Detect_Raw_Devices(), LIBMTP_Release_Device(), and LIBMTP_mtpdevice_struct::params.

Referenced by: LIBMTP_Get_Device_By_ID().

LIBMTP_Get_Device_Certificate()

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

Returns the device (public key) certificate as an XML document string, straight off the device. 🔐

Parameters

  • *device* — a pointer to the device you want the device certificate from.
  • **devcert* — the device certificate as an XML string, or NULL if the call failed or if the device certificate property just isn't supported. This string must be free():ed by the caller after use. Don't forget or it's a leak bestie 🙈

Returns

  • 0 on success, any other value means failure.

LIBMTP_Get_Deviceversion()

char * LIBMTP_Get_Deviceversion (LIBMTP_mtpdevice_t * device)

Grabs the device version (hardware and firmware version) of an MTP device. The full deets. ✨

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

the receipts function 📋

LIBMTP_error_t * LIBMTP_Get_Errorstack (LIBMTP_mtpdevice_t * device)

Returns the error stack for a device, for when you either need to reference the error numbers (like, say, when you're building 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. The way that it just hands you the whole stack… iconic.

Okay so important: you need to call LIBMTP_Clear_Errorstack to clear it when you're finished with it. Don't just leave it lying around. 🧹

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

LIBMTP_mtpdevice_t * LIBMTP_Get_First_Device (void )

Get the first (as in "first in the list of") connected MTP device. Not first like "the winner", first like "index zero". 😌

Returns

  • a device pointer.

See also

  • LIBMTP_Get_Connected_Devices()

References: LIBMTP_Get_Device().

LIBMTP_Get_Friendlyname()

the cute nickname function 🎀

char * LIBMTP_Get_Friendlyname (LIBMTP_mtpdevice_t * device)

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. No cap.

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.

LIBMTP_Get_Manufacturername()

char * LIBMTP_Get_Manufacturername (LIBMTP_mtpdevice_t * device)

Retrieves the manufacturer name of an MTP device. Who made you, lil guy. 🏭

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.

LIBMTP_Get_Modelname()

char * LIBMTP_Get_Modelname (LIBMTP_mtpdevice_t * device)

Retrieves the model name of an MTP device — and often that's the same thing as the product name, they're kinda the same vibe here.

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.

LIBMTP_Get_Property_Description()

char const  * LIBMTP_Get_Property_Description (LIBMTP_property_t inproperty)

This helper function returns a textual description for a libmtp property, for when you need to slap it into dialog boxes and stuff. 🪟

Parameters

  • *inproperty* — the libmtp internal property to get a description for.

Returns

  • a string representing the filetype. This must NOT be free():ed by the caller! It is not yours, do not touch it, hands off bestie ✋💀

References: propertymap_struct::description, and propertymap_struct::id.

Referenced by: LIBMTP_Dump_Device_Info().

LIBMTP_Get_Secure_Time()

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

Returns the secure time as an XML document string from the device. Yes it's XML. Yes that's just how it is. ⏰

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.

LIBMTP_Get_Serialnumber()

char * LIBMTP_Get_Serialnumber (LIBMTP_mtpdevice_t * device)

Retrieves the serial number of an MTP device. The government name. 🪪

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.

LIBMTP_Get_Storage()

the storage list glow-up ✨

int LIBMTP_Get_Storage (LIBMTP_mtpdevice_t * device, int const sortby)

Okay so this one is a whole thing. It updates all the storage id's of a device and their properties, then builds a linked list and drops the list head into the device struct. It also optionally sorts that list, because of course it does. If you want to display storage info in your app you should call this function, then dereference the device struct (device->storage) to pull out the info on the storage.

You need to call this every single time you want to update the device->storage list — for example anytime you need to check available storage somewhere. It does not stay fresh on its own, bestie. 🥲

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! Like actually. I'm not being dramatic. 💀

Parameters

  • *device* — a pointer to the device to get the storage for.
  • *sortby* — an integer that determines the sorting of the storage list. Valid sort methods are defined in libmtp.h and begin with LIBMTP_STORAGE_SORTBY_. Use 0 or LIBMTP_STORAGE_SORTBY_NOTSORTED to not sort at all.

Returns

  • 0 on success
  • 1 success, but only with storage id's — the storage properties could not be retrieved 😬
  • -1 means failure.

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.

Referenced by: LIBMTP_Open_Raw_Device_Uncached().

LIBMTP_Get_String_From_Object()

char * LIBMTP_Get_String_From_Object (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id)

Get/set arbitrary properties. These do not update the cache; they should only be used on properties that are not stored in structs. Read the room before using this one 🫶

Retrieves a string from an object.

Parameters

  • *device* — a pointer to an MTP device.
  • *object_id* — Object reference.
  • *attribute_id* — MTP attribute ID.

Returns

  • a valid string, or NULL on failure. The returned string must bee free():ed by the caller after use. (yes, "bee". we love a typo, it's giving chaotic 🐝)

LIBMTP_Get_Supported_Filetypes()

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

Retrieves a list of supported file types — i.e. the file types that this device claims it supports, like audio file types the device can play and so on. 🎧 This list is mitigated to include the file types that libmtp can handle, meaning it will not list filetypes that libmtp handles internally, like playlists and folders. So it's the filtered, tasteful version. 💅

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: LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

LIBMTP_Get_Syncpartner()

char * LIBMTP_Get_Syncpartner (LIBMTP_mtpdevice_t * device)

Retrieves the synchronization partner of an MTP device. This property should be supported by all MTP devices. It's basically "who's your plus-one" 🫶

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.

LIBMTP_Get_u16_From_Object()

uint16_t LIBMTP_Get_u16_From_Object (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint16_t const value_default)

Retrieves an unsigned 16-bit integer from an object attribute. Small number, big responsibility. 🔢

Parameters

  • *device* — a pointer to an MTP device.
  • *object_id* — Object reference.
  • *attribute_id* — MTP attribute ID.
  • *value_default* — Default value to return on failure.

Returns

a value 💖

LIBMTP_Get_u32_From_Object

uint32_t LIBMTP_Get_u32_From_Object (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint32_t const value_default)

okay so this one pulls an unsigned 32-bit integer out of an object attribute. big number energy ✨

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value_default — Default value to return on failure

Returns

the value 🫶

LIBMTP_Get_u64_From_Object

uint64_t LIBMTP_Get_u64_From_Object (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint64_t const value_default)

same vibe as the last one but it's giving 64 bits instead of 32. she's big, she's unsigned, she's retrieving from an object attribute 💅

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value_default — Default value to return on failure

Returns

the value

LIBMTP_Get_u8_From_Object

uint8_t LIBMTP_Get_u8_From_Object (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint8_t const value_default)

and now we go smol 🥺 8 tiny bits, pulled out of an object attribute, no notes.

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value_default — Default value to return on failure

Returns

a value

LIBMTP_Is_Property_Supported

int LIBMTP_Is_Property_Supported (LIBMTP_mtpdevice_t * device, LIBMTP_property_t const property, LIBMTP_filetype_t const filetype)

bestie this is your vibe check 🦋 — it tells you whether a property is even supported for a given file type before you go setting values all willy-nilly.

Parameters

  • device — a pointer to an MTP device
  • property — the property to query
  • filetype — the filetype of the object you want to set values for

Returns

0 if not supported, positive if supported, negative on error 👀

References

  • LIBMTP_mtpdevice_struct::params.

LIBMTP_Number_Devices_In_List

uint32_t LIBMTP_Number_Devices_In_List (LIBMTP_mtpdevice_t * device_list)

counts how many devices are chillin' in the device list you pass in. literally just a headcount 💀

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.

LIBMTP_Open_Raw_Device_Uncached

LIBMTP_mtpdevice_t * LIBMTP_Open_Raw_Device_Uncached (LIBMTP_raw_device_t * rawdevice)

this opens a device from a raw device, and honestly it's the way to do it — the preferred way to access devices in the new interface, where several devices can come and go while the library is working on a certain device. devices be flaky like that, we love her 🙈

Parameters

  • rawdevice — the raw device to open a "real" device for.

Returns

an open device.

References

  • LIBMTP_raw_device_struct::bus_location
  • LIBMTP_mtpdevice_struct::cached
  • 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_raw_device_struct::device_entry
  • DEVICE_FLAG_FLAC_IS_UNKNOWN
  • DEVICE_FLAG_OGG_IS_UNKNOWN
  • LIBMTP_device_entry_struct::device_flags
  • DEVICE_FLAGS_ANDROID_BUGS
  • DEVICE_FLAGS_ARICENT_BUGS
  • DEVICE_FLAGS_SONY_NWZ_BUGS
  • LIBMTP_raw_device_struct::devnum
  • LIBMTP_mtpdevice_struct::errorstack
  • LIBMTP_mtpdevice_struct::extensions
  • LIBMTP_Get_Storage()
  • LIBMTP_mtpdevice_struct::maximum_battery_level
  • LIBMTP_device_extension_struct::name
  • LIBMTP_device_extension_struct::next
  • LIBMTP_mtpdevice_struct::object_bitsize
  • LIBMTP_mtpdevice_struct::params
  • _PTP_USB::rawdevice
  • LIBMTP_mtpdevice_struct::storage
  • LIBMTP_mtpdevice_struct::usbinfo.

LIBMTP_Release_Device

void LIBMTP_Release_Device (LIBMTP_mtpdevice_t * device)

closes and releases an allocated MTP device. it's the goodbye hug 🤗

Parameters

  • device — a pointer to the MTP device to release.

References

  • LIBMTP_mtpdevice_struct::extensions
  • LIBMTP_Clear_Errorstack()
  • LIBMTP_device_extension_struct::name
  • LIBMTP_device_extension_struct::next
  • LIBMTP_mtpdevice_struct::params
  • LIBMTP_mtpdevice_struct::usbinfo.

Referenced by

  • LIBMTP_Get_Device_By_SerialNumber()
  • LIBMTP_Release_Device_List().

LIBMTP_Release_Device_List

void LIBMTP_Release_Device_List (LIBMTP_mtpdevice_t * device)

yep, this also closes and releases an allocated MTP device. same description, no cap.

Parameters

  • device — a pointer to the MTP device to release.

References

  • LIBMTP_Release_Device()
  • LIBMTP_Release_Device_List()
  • LIBMTP_mtpdevice_struct::next.

Referenced by

  • LIBMTP_Release_Device_List().

LIBMTP_Reset_Device

int LIBMTP_Reset_Device (LIBMTP_mtpdevice_t * device)

resets a device in case it supports the PTP_OC_ResetDevice operation code (0x1010). like turning it off and on again but make it protocol ✨

Parameters

  • device — a pointer to the device to reset.

Returns

0 on success, any other value means failure.

References

  • LIBMTP_mtpdevice_struct::params.

LIBMTP_Set_Friendlyname

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

sets the "friendly name" of an MTP device — yes you can literally name your device, main character energy 👑

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

References

  • LIBMTP_mtpdevice_struct::params.

LIBMTP_Set_Object_String

int LIBMTP_Set_Object_String (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, char const *const string)

sets an object attribute from a string 🌸

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • string — string value to set

Returns

0 on success, any other value means failure

LIBMTP_Set_Object_u16

int LIBMTP_Set_Object_u16 (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint16_t const value)

sets an object attribute from an unsigned 16-bit integer 💖

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value — 16-bit unsigned integer to set

Returns

0 on success, any other value means failure

LIBMTP_Set_Object_u32

int LIBMTP_Set_Object_u32 (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint32_t const value)

sets an object attribute from an unsigned 32-bit integer 🔥

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value — 32-bit unsigned integer to set

Returns

0 on success, any other value means failure

LIBMTP_Set_Object_u8

int LIBMTP_Set_Object_u8 (LIBMTP_mtpdevice_t * device, uint32_t const object_id, LIBMTP_property_t const attribute_id, uint8_t const value)

sets an object attribute from an unsigned 8-bit integer 🎀

Parameters

  • device — a pointer to an MTP device.
  • object_id — Object reference
  • attribute_id — MTP attribute ID
  • value — 8-bit unsigned integer to set

Returns

0 on success, any other value means failure

LIBMTP_Set_Syncpartner

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

sets the synchronization partner of an MTP device.

okay so real talk: 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. it's giving "this seat's taken" 💅

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.

✨ Author ✨

Generated automatically by Doxygen for libmtp from the source code. (not me, bestie — Doxygen did all the heavy lifting 🧚)

and that's a wrap on basic(3) 🫶 you just read the whole entire thing. this page ships with libmtp Version 1.1.23, and yeah, it's the basic(3) page — you're welcome. now go unplug something and plug it back in. slay 💖🌈✨

📦 where this page comes from