objects(3)

📦 version 1.1.23, in arch rolling

💖 objects(3) — the object management API, bestie 💖

This is the objects(3) page from the libmtp Library Functions Manual, and it’s all about managing objects on MTP devices. Buckle up, we’re doing API lore. 🎀

💖 NAME 💖

objects — the object management API. That’s the whole vibe.

✨ SYNOPSIS ✨

🎀 Functions 🎀

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)

🌸 Detailed Description 🌸

Okay bestie, the real detailed breakdown lives in the function docs right below. No filler, just the object-management API doing its thing. 💅

🎀 Function Documentation 🎀

💅 LIBMTP_Copy_Object

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

The function copies an object from one location on a device to another location. Slay. ✨

The semantics of copying a folder are not defined in the spec, but it appears to do the right thing when tested — and also, devices that implement this operation are rare. Not me expecting folder-copy semantics to be fully locked down 💀.

Note that copying an object may take a significant amount of time. MTP does not provide any kind of progress mechanism, so the operation will simply block for the duration. No little spinner, no progress bar, just waiting. 🫠

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.

💅 LIBMTP_Delete_Object

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 main character energy. 👑

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. The safe way to do this is to recursively delete all files (and folders) contained in the folder, then the folder itself.

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.

💅 LIBMTP_Move_Object

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. It’s giving relocation era. 🦋

The semantics of moving a folder are not defined in the spec, but it appears to do the right thing when tested — and again, devices that implement this operation are rare. Yes, we’re back to “rare” and “not defined in the spec,” bestie. 💀

Note that 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. Sorry, no progress updates, just commitment. 😭

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.

💅 LIBMTP_Set_Object_Filename

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. 🚨

Like, for real, don’t build new stuff on this one. Redirect your energy.

See also

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

References

LIBMTP_file_struct::filetype, and LIBMTP_Get_Filemetadata().

👑 Author 👑

Generated automatically by Doxygen for libmtp from the source code. Doxygen really said “I got this” and hit publish. ⭐

Sign-off from the footer, bestie: source is libmtp, version 1.1.23, page objects(3). The footer doesn’t show a date, so I’m not inventing one — periodt. 💅🎀

📦 where this page comes from