--- name: "mtp_albums" section: "3" platform: "linux" package: "libmtp-doc" version: "1.1.22-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/mtp_albums" --- # mtp\_albums(3) albums ## NAME libmtp - albums ## 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 ## Function Documentation ### int LIBMTP\_Create\_New\_Album (LIBMTP\_mtpdevice\_t \* device, LIBMTP\_album\_t \*const metadata) This routine creates a new album based on the metadata supplied. If the `tracks` field of the metadata contains a track listing, these tracks will be added to the album. **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 recursively deletes the memory for an album structure **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 an individual album from the device. **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. **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. **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. You can filter on the storage ID. **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. Notice that 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. **Returns** a pointer to the newly allocated metadata structure. **See also** **LIBMTP\_destroy\_album\_t()** References **LIBMTP\_album\_struct::album\_id**. 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!** **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. 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.** **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.**