.TH "albums" 3 "Version 1.1.21" "libmtp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libmtp \- albums
.SH SYNOPSIS
.br
.PP
.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 *const metadata)"
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 \fBLIBMTP_album_struct::album_id\fP, \fBLIBMTP_album_struct::artist\fP, \fBLIBMTP_album_struct::composer\fP, \fBLIBMTP_mtpdevice_struct::default_album_folder\fP, \fBLIBMTP_mtpdevice_struct::default_music_folder\fP, \fBLIBMTP_album_struct::genre\fP, \fBLIBMTP_album_struct::name\fP, \fBLIBMTP_album_struct::no_tracks\fP, \fBLIBMTP_album_struct::parent_id\fP, \fBLIBMTP_album_struct::storage_id\fP, and \fBLIBMTP_album_struct::tracks\fP\&.
.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 \fBLIBMTP_album_struct::artist\fP, \fBLIBMTP_album_struct::composer\fP, \fBLIBMTP_album_struct::genre\fP, \fBLIBMTP_album_struct::name\fP, and \fBLIBMTP_album_struct::tracks\fP\&.
.SS "\fBLIBMTP_album_t\fP * LIBMTP_Get_Album (\fBLIBMTP_mtpdevice_t\fP * device, uint32_t const albid)"
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 \fBLIBMTP_album_struct::album_id\fP, \fBLIBMTP_new_album_t()\fP, \fBLIBMTP_album_struct::no_tracks\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBLIBMTP_album_struct::parent_id\fP, \fBLIBMTP_album_struct::storage_id\fP, and \fBLIBMTP_album_struct::tracks\fP\&.
.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 \fBLIBMTP_Get_Album_List_For_Storage()\fP\&.
.SS "\fBLIBMTP_album_t\fP * LIBMTP_Get_Album_List_For_Storage (\fBLIBMTP_mtpdevice_t\fP * 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\&.
.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 \fBLIBMTP_album_struct::album_id\fP, \fBLIBMTP_new_album_t()\fP, \fBLIBMTP_album_struct::next\fP, \fBLIBMTP_album_struct::no_tracks\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBLIBMTP_album_struct::parent_id\fP, \fBLIBMTP_album_struct::storage_id\fP, and \fBLIBMTP_album_struct::tracks\fP\&.
.PP
Referenced by \fBLIBMTP_Get_Album_List()\fP\&.
.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 \fBLIBMTP_album_struct::album_id\fP\&.
.PP
Referenced by \fBLIBMTP_Get_Album()\fP, and \fBLIBMTP_Get_Album_List_For_Storage()\fP\&.
.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 \fBLIBMTP_album_struct::album_id\fP, and \fBLIBMTP_album_struct::name\fP\&.
.SS "int LIBMTP_Update_Album (\fBLIBMTP_mtpdevice_t\fP * device, \fBLIBMTP_album_t\fP const *const metadata)"
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 appropriate 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 \fBLIBMTP_album_struct::album_id\fP, \fBLIBMTP_album_struct::artist\fP, \fBLIBMTP_album_struct::composer\fP, \fBLIBMTP_album_struct::genre\fP, \fBLIBMTP_album_struct::name\fP, \fBLIBMTP_album_struct::no_tracks\fP, and \fBLIBMTP_album_struct::tracks\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libmtp from the source code\&.