.TH "playlists" 3 "Version 1.1.21" "libmtp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libmtp \- playlists
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBLIBMTP_playlist_t\fP * \fBLIBMTP_new_playlist_t\fP (void)"
.br
.ti -1c
.RI "void \fBLIBMTP_destroy_playlist_t\fP (\fBLIBMTP_playlist_t\fP *)"
.br
.ti -1c
.RI "\fBLIBMTP_playlist_t\fP * \fBLIBMTP_Get_Playlist_List\fP (\fBLIBMTP_mtpdevice_t\fP *)"
.br
.ti -1c
.RI "\fBLIBMTP_playlist_t\fP * \fBLIBMTP_Get_Playlist\fP (\fBLIBMTP_mtpdevice_t\fP *, uint32_t const)"
.br
.ti -1c
.RI "int \fBLIBMTP_Create_New_Playlist\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_playlist_t\fP *const)"
.br
.ti -1c
.RI "int \fBLIBMTP_Update_Playlist\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_playlist_t\fP *const)"
.br
.ti -1c
.RI "int \fBLIBMTP_Set_Playlist_Name\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_playlist_t\fP *, const char *)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.SH "Function Documentation"
.PP 
.SS "int LIBMTP_Create_New_Playlist (\fBLIBMTP_mtpdevice_t\fP * device, \fBLIBMTP_playlist_t\fP *const metadata)"
This routine creates a new playlist based on the metadata supplied\&. If the \fCtracks\fP field of the metadata contains a track listing, these tracks will be added to the playlist\&. 
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to create the new playlist on\&. 
.br
\fImetadata\fP the metadata for the new playlist\&. If the function exits with success, the \fCplaylist_id\fP field of this struct will contain the new playlist ID of the playlist\&. 
.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_Playlist()\fP 
.PP
\fBLIBMTP_Delete_Object()\fP 
.RE
.PP

.PP
References \fBLIBMTP_mtpdevice_struct::default_music_folder\fP, \fBLIBMTP_mtpdevice_struct::default_playlist_folder\fP, \fBLIBMTP_playlist_struct::name\fP, \fBLIBMTP_playlist_struct::no_tracks\fP, \fBLIBMTP_playlist_struct::parent_id\fP, \fBLIBMTP_playlist_struct::playlist_id\fP, \fBLIBMTP_playlist_struct::storage_id\fP, \fBLIBMTP_playlist_struct::tracks\fP, and \fBLIBMTP_mtpdevice_struct::usbinfo\fP\&.
.SS "void LIBMTP_destroy_playlist_t (\fBLIBMTP_playlist_t\fP * playlist)"
This destroys a playlist metadata structure and deallocates the memory used by it, including any strings\&. Never use a track metadata structure again after calling this function on it\&. 
.PP
\fBParameters\fP
.RS 4
\fIplaylist\fP the playlist metadata to destroy\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_new_playlist_t()\fP 
.RE
.PP

.PP
References \fBLIBMTP_playlist_struct::name\fP, and \fBLIBMTP_playlist_struct::tracks\fP\&.
.SS "\fBLIBMTP_playlist_t\fP * LIBMTP_Get_Playlist (\fBLIBMTP_mtpdevice_t\fP * device, uint32_t const plid)"
This function retrieves an individual playlist from the device\&. 
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to get the playlist from\&. 
.br
\fIplid\fP the unique ID of the playlist to retrieve\&. 
.RE
.PP
\fBReturns\fP
.RS 4
a valid playlist metadata post or NULL on failure\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_Get_Playlist_List()\fP 
.RE
.PP

.PP
References \fBLIBMTP_new_playlist_t()\fP, \fBLIBMTP_playlist_struct::name\fP, \fBLIBMTP_playlist_struct::no_tracks\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBLIBMTP_playlist_struct::parent_id\fP, \fBLIBMTP_playlist_struct::playlist_id\fP, \fBLIBMTP_playlist_struct::storage_id\fP, \fBLIBMTP_playlist_struct::tracks\fP, and \fBLIBMTP_mtpdevice_struct::usbinfo\fP\&.
.SS "\fBLIBMTP_playlist_t\fP * LIBMTP_Get_Playlist_List (\fBLIBMTP_mtpdevice_t\fP * device)"
This function returns a list of the playlists available on the device\&. Typical usage:
.PP
.PP
.nf

.fi
.PP
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to get the playlist listing from\&. 
.RE
.PP
\fBReturns\fP
.RS 4
a playlist list on success, else NULL\&. If there are no playlists on the device, NULL will be returned as well\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_Get_Playlist()\fP 
.RE
.PP

.PP
References \fBLIBMTP_new_playlist_t()\fP, \fBLIBMTP_playlist_struct::name\fP, \fBLIBMTP_playlist_struct::next\fP, \fBLIBMTP_playlist_struct::no_tracks\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBLIBMTP_playlist_struct::parent_id\fP, \fBLIBMTP_playlist_struct::playlist_id\fP, \fBLIBMTP_playlist_struct::storage_id\fP, \fBLIBMTP_playlist_struct::tracks\fP, and \fBLIBMTP_mtpdevice_struct::usbinfo\fP\&.
.SS "\fBLIBMTP_playlist_t\fP * LIBMTP_new_playlist_t (void)"
This creates a new playlist 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_playlist_t\fP operation later, so be careful of using strdup() when assigning strings, e\&.g\&.:
.PP
.PP
.nf

LIBMTP_playlist_t *pl = \fBLIBMTP_new_playlist_t()\fP;
pl->name = strdup(str);
\&.\&.\&.\&.
LIBMTP_destroy_playlist_t(pl);
.fi
.PP
.PP
\fBReturns\fP
.RS 4
a pointer to the newly allocated metadata structure\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_destroy_playlist_t()\fP 
.RE
.PP

.PP
References \fBLIBMTP_playlist_struct::playlist_id\fP\&.
.PP
Referenced by \fBLIBMTP_Get_Playlist()\fP, and \fBLIBMTP_Get_Playlist_List()\fP\&.
.SS "int LIBMTP_Set_Playlist_Name (\fBLIBMTP_mtpdevice_t\fP * device, \fBLIBMTP_playlist_t\fP * playlist, const char * newname)"
This function renames a single playlist object file holder\&. This simply means that the \fCPTP_OPC_ObjectFileName\fP property is updated, if this is supported by the device\&. The playlist filename should nominally end with an extension like '\&.pla'\&.
.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_Playlist()\fP\fP instead!
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device that contains the file\&. 
.br
\fIplaylist\fP the playlist metadata of the playlist 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_Playlist()\fP 
.RE
.PP

.PP
References \fBLIBMTP_playlist_struct::name\fP, and \fBLIBMTP_playlist_struct::playlist_id\fP\&.
.SS "int LIBMTP_Update_Playlist (\fBLIBMTP_mtpdevice_t\fP * device, \fBLIBMTP_playlist_t\fP *const metadata)"
This routine updates a playlist based on the metadata supplied\&. If the \fCtracks\fP field of the metadata contains a track listing, these tracks will be added to the playlist in place of those already present, i\&.e\&. the previous track listing will be deleted\&. For Samsung devices the playlist id (metadata->playlist_id) is likely to change\&. 
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to create the new playlist on\&. 
.br
\fImetadata\fP the metadata for the playlist to be updated\&. notice that the field \fCplaylist_id\fP must contain the appropriate playlist ID\&. Playlist ID be modified to a new playlist ID by the time the function returns since edit-in-place is not always possible\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, any other value means failure\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_Create_New_Playlist()\fP 
.PP
\fBLIBMTP_Delete_Object()\fP 
.RE
.PP

.PP
References \fBLIBMTP_playlist_struct::name\fP, \fBLIBMTP_playlist_struct::no_tracks\fP, \fBLIBMTP_playlist_struct::playlist_id\fP, \fBLIBMTP_playlist_struct::tracks\fP, and \fBLIBMTP_mtpdevice_struct::usbinfo\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libmtp from the source code\&.