objects(3)

📦
version 1.1.23 · 6 versions
, in ubuntu stonking

💖 objects(3) — the libmtp object ops, explained by your fave unix girlie 💖

okay bestie, sit DOWN. this is the libmtp page about objects — like, files, tracks, playlists, folders, all the little guys chilling on your MTP device. this is from the Library Functions Manual, section 3, and it's literally just a pile of functions that let you yank objects around, rename them, delete them, and nibble at them byte by byte. slay. ✨

🌸 SYNOPSIS 🌸

the whole squad, in order, exactly as written:

int LIBMTP_Delete_Object (LIBMTP_mtpdevice_t *, uint32_t)
int LIBMTP_Move_Object (LIBMTP_mtpdevice_t *, uint32_t, uint32_t,
    uint32_t)
int LIBMTP_Copy_Object (LIBMTP_mtpdevice_t *, uint32_t, uint32_t,
    uint32_t)
int LIBMTP_Set_Object_Filename (LIBMTP_mtpdevice_t *, uint32_t, char *)
int LIBMTP_GetPartialObject (LIBMTP_mtpdevice_t *, uint32_t const,
    uint64_t, uint32_t, unsigned char **, unsigned int *)
int LIBMTP_SendPartialObject (LIBMTP_mtpdevice_t *, uint32_t const,
    uint64_t, unsigned char *, unsigned int)
int LIBMTP_BeginEditObject (LIBMTP_mtpdevice_t *, uint32_t const)
int LIBMTP_EndEditObject (LIBMTP_mtpdevice_t *, uint32_t const)
int LIBMTP_TruncateObject (LIBMTP_mtpdevice_t *, uint32_t const,
    uint64_t)

🧚 Functions

  • int LIBMTP_Delete_Object (LIBMTP_mtpdevice_t *, uint32_t) — yeets one object off the device
  • int LIBMTP_Move_Object (LIBMTP_mtpdevice_t *, uint32_t, uint32_t, uint32_t) — moves an object somewhere else
  • int LIBMTP_Copy_Object (LIBMTP_mtpdevice_t *, uint32_t, uint32_t, uint32_t) — copies an object somewhere else
  • int LIBMTP_Set_Object_Filename (LIBMTP_mtpdevice_t *, uint32_t, char *) — renames an object (⚠️ deprecated, more below)
  • int LIBMTP_GetPartialObject (LIBMTP_mtpdevice_t *, uint32_t const, uint64_t, uint32_t, unsigned char **, unsigned int *) — grabs just a lil slice of an object
  • int LIBMTP_SendPartialObject (LIBMTP_mtpdevice_t *, uint32_t const, uint64_t, unsigned char *, unsigned int) — sends just a lil slice of an object
  • int LIBMTP_BeginEditObject (LIBMTP_mtpdevice_t *, uint32_t const) — opens an object for editing
  • int LIBMTP_EndEditObject (LIBMTP_mtpdevice_t *, uint32_t const) — closes that editing session
  • int LIBMTP_TruncateObject (LIBMTP_mtpdevice_t *, uint32_t const, uint64_t) — chops an object down to size

✨ Detailed Description ✨

...and that's it, bestie. the original page just says "Detailed Description" and then moves straight into the functions. no extra lore. we love a low-effort section that still ate. 💅

🦋 Function Documentation 🦋

🌈 int LIBMTP_Copy_Object (LIBMTP_mtpdevice_t * device, uint32_t object_id, uint32_t storage_id, uint32_t parent_id)

this one copies an object from one location on a device to another location. iconic behaviour, honestly.

soooo here's the tea on folders: the semantics of copying a folder are not defined in the spec, but it appears to do the right thing when tested (but devices that implement this operation are rare). so like, don't count on it, k?

also — copying an object may take a significant amount of time. and MTP does not provide any kind of progress mechanism, so the operation will simply block for the duration. no little spinner, no percent bar, no vibes. it just sits there. 🫠

Parameters

  • device — a pointer to the device where the object exists.
  • object_id — the object to copy.
  • storage_id — the id of the destination storage.
  • parent_id — the id of the destination parent object (folder). If the destination is the root of the storage, pass '0'.

Returns

0 on success, any other value means failure.

References

LIBMTP_mtpdevice_struct::params.

🔥 int LIBMTP_Delete_Object (LIBMTP_mtpdevice_t * device, uint32_t object_id)

this function deletes a single file, track, playlist, folder or any other object off the MTP device, identified by the object ID. one object, one deletion. very targeted. very main character.

now, the important bit, listen up bestie: if you delete a folder, there is no guarantee that the device will really delete all the files that were in that folder. rather it is expected that they will not be deleted, and will turn up in object listings with parent set to a non-existant object ID. so you'll have these lil orphan ghosts in your listings. 😭

the safe way to do this is to recursively delete all files (and folders) contained in the folder, then the folder itself. do it in that order. periodt.

Parameters

  • device — a pointer to the device to delete the object from.
  • object_id — the object to delete.

Returns

0 on success, any other value means failure.

References

LIBMTP_mtpdevice_struct::params.

👑 int LIBMTP_Move_Object (LIBMTP_mtpdevice_t * device, uint32_t object_id, uint32_t storage_id, uint32_t parent_id)

the function moves an object from one location on a device to another location. yes queen, relocate.

same folder situation as copy: the semantics of moving a folder are not defined in the spec, but it appears to do the right thing when tested (but devices that implement this operation are rare).

⚠️ and the timing thing again, but worse — moving an object may take a significant amount of time, particularly if being moved between storages. MTP does not provide any kind of progress mechanism, so the operation will simply block for the duration. just. sitting. there. 🧘

Parameters

  • device — a pointer to the device where the object exists.
  • object_id — the object to move.
  • storage_id — the id of the destination storage.
  • parent_id — the id of the destination parent object (folder). If the destination is the root of the storage, pass '0'.

Returns

0 on success, any other value means failure.

References

LIBMTP_mtpdevice_struct::params.

💀 int LIBMTP_Set_Object_Filename (LIBMTP_mtpdevice_t * device, uint32_t object_id, char * newname)

🚨 THIS FUNCTION IS DEPRECATED. PLEASE UPDATE YOUR CODE IN ORDER NOT TO USE IT. 🚨

okay so this one is the ex you don't text back. it's deprecated, it's giving "please let me go", and the docs are screaming at you in all caps to update your code so you don't use it. so do that. fr fr.

See also

  • LIBMTP_Set_File_Name()
  • LIBMTP_Set_Track_Name()
  • LIBMTP_Set_Folder_Name()
  • LIBMTP_Set_Playlist_Name()
  • LIBMTP_Set_Album_Name()

(go use one of those instead, bestie, they're right there 💜)

References

LIBMTP_file_struct::filetype, and LIBMTP_Get_Filemetadata().

🎀 Author 🎀

Generated automatically by Doxygen for libmtp from the source code. (no human author credit, it's just the Doxygen machine doing its thing. we stan an automated king. 🤖)

okay that's the whole page, you're caught up, go forth and move objects responsibly 🌸 this was libmtp Version 1.1.23, page objects(3) — mwah, bye bestie! 💖✨🦋

📦 where this page comes from