.TH "The audio/video album management API." 3 "Wed Apr 19 2017" "Version 1.1.12" "libmtp" \" -*- nroff -*- .ad l .nh .SH NAME libmtp \- The audio/video album management API. .SS "Functions" .in +1c .ti -1c .RI "\fBLIBMTP_album_t\fP * \fBLIBMTP_new_album_t\fP (void)" .br .ti -1c .RI "void \fBLIBMTP_destroy_album_t\fP (\fBLIBMTP_album_t\fP *)" .br .ti -1c .RI "\fBLIBMTP_album_t\fP * \fBLIBMTP_Get_Album_List\fP (\fBLIBMTP_mtpdevice_t\fP *)" .br .ti -1c .RI "\fBLIBMTP_album_t\fP * \fBLIBMTP_Get_Album_List_For_Storage\fP (\fBLIBMTP_mtpdevice_t\fP *, uint32_t const)" .br .ti -1c .RI "\fBLIBMTP_album_t\fP * \fBLIBMTP_Get_Album\fP (\fBLIBMTP_mtpdevice_t\fP *, uint32_t const)" .br .ti -1c .RI "int \fBLIBMTP_Create_New_Album\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_album_t\fP *const)" .br .ti -1c .RI "int \fBLIBMTP_Update_Album\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_album_t\fP const *const)" .br .ti -1c .RI "int \fBLIBMTP_Set_Album_Name\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_album_t\fP *, const char *)" .br .in -1c .SH "Detailed Description" .PP .SH "Function Documentation" .PP .SS "int LIBMTP_Create_New_Album (\fBLIBMTP_mtpdevice_t\fP *device, \fBLIBMTP_album_t\fP *constmetadata)" This routine creates a new album based on the metadata supplied\&. If the \fCtracks\fP field of the metadata contains a track listing, these tracks will be added to the album\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device to create the new album on\&. .br \fImetadata\fP the metadata for the new album\&. If the function exits with success, the \fCalbum_id\fP field of this struct will contain the new ID of the album\&. .PD 0 .IP "\(bu" 2 \fCmetadata->parent_id\fP 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\&. .IP "\(bu" 2 \fCmetadata->storage_id\fP 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\&. .PP .RE .PP \fBReturns:\fP .RS 4 0 on success, any other value means failure\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Update_Album()\fP .PP \fBLIBMTP_Delete_Object()\fP .RE .PP .PP 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\&. .SS "void LIBMTP_destroy_album_t (\fBLIBMTP_album_t\fP *album)" This recursively deletes the memory for an album structure .PP \fBParameters:\fP .RS 4 \fIalbum\fP structure to destroy .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_new_album_t()\fP .RE .PP .PP References LIBMTP_album_struct::artist, LIBMTP_album_struct::composer, LIBMTP_album_struct::genre, LIBMTP_album_struct::name, and LIBMTP_album_struct::tracks\&. .SS "\fBLIBMTP_album_t\fP* LIBMTP_Get_Album (\fBLIBMTP_mtpdevice_t\fP *device, uint32_t constalbid)" This function retrieves an individual album from the device\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device to get the album from\&. .br \fIalbid\fP the unique ID of the album to retrieve\&. .RE .PP \fBReturns:\fP .RS 4 a valid album metadata or NULL on failure\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Get_Album_List()\fP .RE .PP .PP 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\&. .SS "\fBLIBMTP_album_t\fP* LIBMTP_Get_Album_List (\fBLIBMTP_mtpdevice_t\fP *device)" This function returns a list of the albums available on the device\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device to get the album listing from\&. .RE .PP \fBReturns:\fP .RS 4 an album list on success, else NULL\&. If there are no albums on the device, NULL will be returned as well\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Get_Album()\fP .RE .PP .PP References LIBMTP_Get_Album_List_For_Storage()\&. .SS "\fBLIBMTP_album_t\fP* LIBMTP_Get_Album_List_For_Storage (\fBLIBMTP_mtpdevice_t\fP *device, uint32_t conststorage_id)" This function returns a list of the albums available on the device\&. You can filter on the storage ID\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device to get the album listing from\&. .br \fIstorage_id\fP ID of device storage (if null, all storages) .RE .PP \fBReturns:\fP .RS 4 an album list on success, else NULL\&. If there are no albums on the device, NULL will be returned as well\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Get_Album()\fP .RE .PP .PP 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\&. .PP Referenced by LIBMTP_Get_Album_List()\&. .SS "\fBLIBMTP_album_t\fP* 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 \fCLIBMTP_destroy_album_t\fP operation later, so be careful of using strdup() when assigning strings\&. .PP \fBReturns:\fP .RS 4 a pointer to the newly allocated metadata structure\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_destroy_album_t()\fP .RE .PP .PP References LIBMTP_album_struct::album_id\&. .PP Referenced by LIBMTP_Get_Album(), and LIBMTP_Get_Album_List_For_Storage()\&. .SS "int LIBMTP_Set_Album_Name (\fBLIBMTP_mtpdevice_t\fP *device, \fBLIBMTP_album_t\fP *album, const char *newname)" This function renames a single album\&. This simply means that the \fCPTP_OPC_ObjectFileName\fP property is updated, if this is supported by the device\&. The album filename should nominally end with an extension like '\&.alb'\&. .PP NOTE: if you want to change the metadata the device display about a playlist you must \fInot\fP use this function, use \fC\fBLIBMTP_Update_Album()\fP\fP instead! .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device that contains the file\&. .br \fIalbum\fP 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\&. .br \fInewname\fP the new name for this object\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, any other value means failure\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Update_Album()\fP .RE .PP .PP References LIBMTP_album_struct::album_id, and LIBMTP_album_struct::name\&. .SS "int LIBMTP_Update_Album (\fBLIBMTP_mtpdevice_t\fP *device, \fBLIBMTP_album_t\fP const *constmetadata)" This routine updates an album based on the metadata supplied\&. If the \fCtracks\fP 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\&. .PP \fBParameters:\fP .RS 4 \fIdevice\fP a pointer to the device to create the new album on\&. .br \fImetadata\fP the metadata for the album to be updated\&. notice that the field \fCalbum_id\fP must contain the apropriate album ID\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, any other value means failure\&. .RE .PP \fBSee also:\fP .RS 4 \fBLIBMTP_Create_New_Album()\fP .PP \fBLIBMTP_Delete_Object()\fP .RE .PP .PP 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\&. .SH "Author" .PP Generated automatically by Doxygen for libmtp from the source code\&.