folders(3)

🎀 NAME 🎀

okay so bestie, welcome to libmtp — folders 💖 this page is straight out of the Library Functions Manual, and it's all about the folder-flavoured functions in libmtp. yes we are going through literally every single one, no skimming, no skipping, we eat the whole plate 🍓

---

🦋 SYNOPSIS 🦋

Functions

LIBMTP_folder_t * LIBMTP_new_folder_t (void)
void LIBMTP_destroy_folder_t (LIBMTP_folder_t *)
LIBMTP_folder_t * LIBMTP_Get_Folder_List (LIBMTP_mtpdevice_t *)
LIBMTP_folder_t * LIBMTP_Get_Folder_List_For_Storage (LIBMTP_mtpdevice_t *, uint32_t const)
LIBMTP_folder_t * LIBMTP_Find_Folder (LIBMTP_folder_t *, uint32_t const)
uint32_t LIBMTP_Create_Folder (LIBMTP_mtpdevice_t *, char *, uint32_t, uint32_t)
int LIBMTP_Set_Folder_Name (LIBMTP_mtpdevice_t *, LIBMTP_folder_t *, const char *)

---

💅 Detailed Description 💅

ngl bestie, this section is literally empty on the original page — there is genuinely nothing here between the heading and the next one. the real tea is all waiting for you right below ⤵️

---

🔥 Function Documentation 🔥

uint32_t LIBMTP_Create_Folder (LIBMTP_mtpdevice_t * device, char * name, uint32_t parent_id, uint32_t storage_id)

this one creates a folder on the current MTP device 🎀 and here's the lore: the PTP name for a folder is "association". PTP/MTP devices don't actually have an internal "folder" concept fr fr — what's really inside is a flat list of all the files, and some of those files are "associations" that other files and folders can point at as their "parent". it's giving fake hierarchy, but it works 💅

Parameters

• device — a pointer to the device to create the folder on.
• name — the name of the new folder. heads up bestie: this can get modified if the device doesn't support all the characters in the name.
• parent_id — id of the parent folder to add the new folder to, or 0xFFFFFFFF to drop it straight into the root directory.
• storage_id — id of the storage to add this new folder to. ⚠️ notice you cannot mismatch the storage id and the parent id: they must both be on the same storage! pass in 0 if you want to create this folder on the default storage.

Returns

id to the new folder, or 0 if an error happened 😭

References

DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST, LIBMTP_mtpdevice_struct::params, strip_7bit_from_utf8(), and LIBMTP_mtpdevice_struct::usbinfo.

---

void LIBMTP_destroy_folder_t (LIBMTP_folder_t * folder)

this one recursively deletes the memory for a folder structure 💀 typically you call it on a top-level folder list, and boom — the entire folder tree is gone. iconic cleanup energy ✨

Parameters

• folder — the folder structure to destroy.

See also

LIBMTP_new_folder_t()

References

LIBMTP_folder_struct::child, LIBMTP_destroy_folder_t(), LIBMTP_folder_struct::name, and LIBMTP_folder_struct::sibling.

Referenced by

LIBMTP_destroy_folder_t(), and LIBMTP_Get_Folder_List_For_Storage().

---

LIBMTP_folder_t * LIBMTP_Find_Folder (LIBMTP_folder_t * folderlist, uint32_t id)

a little helper function 🫶 it hands you back a folder structure for a specified id.

Parameters

• folderlist — the list of folders to search.
• id — of the folder to look for.

Returns

a folder, or NULL if it's not found 🙈

References

LIBMTP_folder_struct::child, LIBMTP_folder_struct::folder_id, LIBMTP_Find_Folder(), and LIBMTP_folder_struct::sibling.

Referenced by

LIBMTP_Find_Folder().

---

LIBMTP_folder_t * LIBMTP_Get_Folder_List (LIBMTP_mtpdevice_t * device)

this returns a list of all folders available on the current MTP device 🌸

Parameters

• device — a pointer to the device to get the folder listing for.

Returns

a list of folders 👑

References

LIBMTP_Get_Folder_List_For_Storage().

---

LIBMTP_folder_t * LIBMTP_Get_Folder_List_For_Storage (LIBMTP_mtpdevice_t * device, uint32_t const storage)

same vibe as the last one — it returns a list of all folders available on the current MTP device, except you get to pick the storage 🦋

Parameters

• device — a pointer to the device to get the folder listing for.
• storage — a storage ID to get the folder list from.

Returns

a list of folders ✨

References

LIBMTP_folder_struct::child, LIBMTP_folder_struct::folder_id, LIBMTP_destroy_folder_t(), LIBMTP_new_folder_t(), LIBMTP_folder_struct::name, LIBMTP_mtpdevice_struct::params, LIBMTP_folder_struct::parent_id, LIBMTP_folder_struct::sibling, and LIBMTP_folder_struct::storage_id.

Referenced by

LIBMTP_Get_Folder_List().

---

LIBMTP_folder_t * LIBMTP_new_folder_t (void )

this creates a brand-new folder structure and allocates the memory for it 🎀 but listen — heads up: if you add strings to this structure, they will be freed by the corresponding LIBMTP_folder_track_t operation later, so be careful about using strdup() when assigning strings, e.g.:

(and yes bestie, the e.g.: is just... hanging there with no example after it on the page 🙈 that's how it ships)

Returns

a pointer to the newly allocated folder structure 💖

See also

LIBMTP_destroy_folder_t()

Referenced by

LIBMTP_Get_Folder_List_For_Storage().

---

int LIBMTP_Set_Folder_Name (LIBMTP_mtpdevice_t * device, LIBMTP_folder_t * folder, const char * newname)

this function renames a single folder 💅 which simply means the PTP_OPC_ObjectFileName property gets updated — if the device supports that.

Parameters

• device — a pointer to the device that contains the file.
• folder — the folder metadata of the folder to rename. on success, the name member is updated. be aware that this name can be different than newname, depending on device restrictions 👀
• newname — the new name for this object.

Returns

0 on success, any other value means failure 😭

References

LIBMTP_folder_struct::folder_id, and LIBMTP_folder_struct::name.

---

👑 Author 👑

Generated automatically by Doxygen for libmtp from the source code. so no, a human didn't hand-write this one — it's Doxygen doing Doxygen things 🤖✨

---

okay that's the whole page bestie, you ate it 🫶 this was libmtp, Version 1.1.23, and the page you just read is folders(3) — no date on the footer, so that's all the meta we've got. now go create some folders, you main character 💖🎀🦋