albums(3)

📦
version 1.1.23 · 6 versions
, in ubuntu stonking

🌸 NAME 🌸

libmtp — albums 💿✨

okay so bestie, this is the albums page of libmtp. it's giving "how do i talk to the album-shaped little guys on my mp3 player" energy and honestly? iconic.

✨ SYNOPSIS ✨

Functions 🫶

LIBMTP_album_t * LIBMTP_new_album_t (void)
void LIBMTP_destroy_album_t (LIBMTP_album_t *)
LIBMTP_album_t * LIBMTP_Get_Album_List (LIBMTP_mtpdevice_t *)
LIBMTP_album_t * LIBMTP_Get_Album_List_For_Storage (LIBMTP_mtpdevice_t *, uint32_t const)
LIBMTP_album_t * LIBMTP_Get_Album (LIBMTP_mtpdevice_t *, uint32_t const)
int LIBMTP_Create_New_Album (LIBMTP_mtpdevice_t *, LIBMTP_album_t *const)
int LIBMTP_Update_Album (LIBMTP_mtpdevice_t *, LIBMTP_album_t const *const)
int LIBMTP_Set_Album_Name (LIBMTP_mtpdevice_t *, LIBMTP_album_t *, const char *)

📖 Detailed Description 📖

bestie... there is literally nothing here. the Doxygen girlies left this section empty 💀. no cap. moving on fr fr.

🔥 Function Documentation 🔥

int LIBMTP_Create_New_Album (LIBMTP_mtpdevice_t * device, LIBMTP_album_t *const metadata)

this routine creates a brand new album based on the metadata you hand it. and listen — if the tracks field of the metadata has a track listing in it, those tracks get added to the album too. slay. 🎀

Parameters

  • device — a pointer to the device to create the new album on.
  • metadata — the metadata for the new album. If the function exits with success, the album_id field of this struct will contain the new ID of the album.
    • metadata->parent_id should be set to the parent (e.g. folder) to store this track in. Since some devices are a bit picky about where files are placed, a default folder will be chosen if libmtp has detected one for the current filetype and this parameter is set to 0. If this is 0 and no default folder can be found, the file will be stored in the root folder.
    • metadata->storage_id should be set to the desired storage (e.g. memory card or whatever your device presents) to store this track in. Setting this to 0 will store the track on the primary storage.

Returns

0 on success, any other value means failure. 👑

See also

LIBMTP_Update_Album()

LIBMTP_Delete_Object()

References

LIBMTP_album_struct::album_id, LIBMTP_album_struct::artist, LIBMTP_album_struct::composer, LIBMTP_mtpdevice_struct::default_album_folder, LIBMTP_mtpdevice_struct::default_music_folder, LIBMTP_album_struct::genre, LIBMTP_album_struct::name, LIBMTP_album_struct::no_tracks, LIBMTP_album_struct::parent_id, LIBMTP_album_struct::storage_id, and LIBMTP_album_struct::tracks.

void LIBMTP_destroy_album_t (LIBMTP_album_t * album)

this one recursively deletes the memory for an album structure. like, everything inside goes bye-bye 🫧

Parameters

  • album — structure to destroy

See also

LIBMTP_new_album_t()

References

LIBMTP_album_struct::artist, LIBMTP_album_struct::composer, LIBMTP_album_struct::genre, LIBMTP_album_struct::name, and LIBMTP_album_struct::tracks.

LIBMTP_album_t * LIBMTP_Get_Album (LIBMTP_mtpdevice_t * device, uint32_t const albid)

this function retrieves one single individual album from the device. one. just the one. main character album energy 💅

Parameters

  • device — a pointer to the device to get the album from.
  • albid — the unique ID of the album to retrieve.

Returns

a valid album metadata or NULL on failure. 😭

See also

LIBMTP_Get_Album_List()

References

LIBMTP_album_struct::album_id, LIBMTP_new_album_t(), LIBMTP_album_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_album_struct::parent_id, LIBMTP_album_struct::storage_id, and LIBMTP_album_struct::tracks.

LIBMTP_album_t * LIBMTP_Get_Album_List (LIBMTP_mtpdevice_t * device)

this function returns a list of the albums available on the device. the whole roster 🌈

Parameters

  • device — a pointer to the device to get the album listing from.

Returns

an album list on success, else NULL. If there are no albums on the device, NULL will be returned as well. (yes bestie, empty device = NULL, that's just how it is 🙈)

See also

LIBMTP_Get_Album()

References

LIBMTP_Get_Album_List_For_Storage().

LIBMTP_album_t * LIBMTP_Get_Album_List_For_Storage (LIBMTP_mtpdevice_t * device, uint32_t const storage_id)

this function returns a list of the albums available on the device, but you get to filter on the storage ID. glow-up edition ✨

Parameters

  • device — a pointer to the device to get the album listing from.
  • storage_id — ID of device storage (if null, all storages)

Returns

an album list on success, else NULL. If there are no albums on the device, NULL will be returned as well.

See also

LIBMTP_Get_Album()

References

LIBMTP_album_struct::album_id, LIBMTP_new_album_t(), LIBMTP_album_struct::next, LIBMTP_album_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_album_struct::parent_id, LIBMTP_album_struct::storage_id, and LIBMTP_album_struct::tracks.

Referenced by LIBMTP_Get_Album_List().

LIBMTP_album_t * LIBMTP_new_album_t (void )

this creates a new album metadata structure and allocates memory for it. and hmm, listen up bestie, this part matters: if you add strings to this structure they will be freed by the corresponding LIBMTP_destroy_album_t operation later, so be careful of using strdup() when assigning strings. the way that memory management will humble you 😭

Returns

a pointer to the newly allocated metadata structure. 🫶

See also

LIBMTP_destroy_album_t()

Referenced by LIBMTP_Get_Album(), and LIBMTP_Get_Album_List_For_Storage().

int LIBMTP_Set_Album_Name (LIBMTP_mtpdevice_t * device, LIBMTP_album_t * album, const char * newname)

this function renames a single album. this simply means that the PTP_OPC_ObjectFileName property is updated, if this is supported by the device. The album filename should nominally end with an extension like ".alb". 💿

NOTE: if you want to change the metadata the device display about a playlist you must not use this function, use LIBMTP_Update_Album() instead! bestie do NOT come for me with the wrong function, ok? 😤

Parameters

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

Returns

0 on success, any other value means failure.

See also

LIBMTP_Update_Album()

References

LIBMTP_album_struct::album_id, and LIBMTP_album_struct::name.

int LIBMTP_Update_Album (LIBMTP_mtpdevice_t * device, LIBMTP_album_t const *const metadata)

this routine updates an album based on the metadata supplied. and okay here's the tea ☕: if the tracks field of the metadata contains a track listing, these tracks will be added to the album in place of those already present, i.e. the previous track listing will be deleted. so like, gone gone. periodt.

Parameters

  • device — a pointer to the device to create the new album on.
  • metadata — the metadata for the album to be updated. notice that the field album_id must contain the appropriate album ID.

Returns

0 on success, any other value means failure. 💅

See also

LIBMTP_Create_New_Album()

LIBMTP_Delete_Object()

References

LIBMTP_album_struct::album_id, LIBMTP_album_struct::artist, LIBMTP_album_struct::composer, LIBMTP_album_struct::genre, LIBMTP_album_struct::name, LIBMTP_album_struct::no_tracks, and LIBMTP_album_struct::tracks.

👑 Author 👑

Generated automatically by Doxygen for libmtp from the source code. (it was not me bestie, the robot wrote this one 🤖✨)

okay that's the whole page, you ate that fr fr 🍓💖 This little love letter to libmtp is Version 1.1.23 and it came from the libmtp source, sitting pretty at section 3 of the Library Functions Manual — so go forth, name your albums, destroy your metadata structs, and hydrate 💜🧚‍♀️

📦 where this page comes from