# The audio/video playlist management API.

## Functions
LIBMTP_playlist_t * | LIBMTP_new_playlist_t (void)
void | LIBMTP_destroy_playlist_t (LIBMTP_playlist_t *)
LIBMTP_playlist_t * | LIBMTP_Get_Playlist_List (LIBMTP_mtpdevice_t *)
LIBMTP_playlist_t * | LIBMTP_Get_Playlist (LIBMTP_mtpdevice_t *, uint32_t const)
int | LIBMTP_Create_New_Playlist (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *const)
int | LIBMTP_Update_Playlist (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t const *const)
int | LIBMTP_Set_Playlist_Name (LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *, const char *)

## Function Documentation

int LIBMTP_Create_New_Playlist | ( | LIBMTP_mtpdevice_t * | device,
|  | LIBMTP_playlist_t *const | metadata |
| ) |  |  |

This routine creates a new playlist based on the metadata supplied. If the `tracks` field of the metadata contains a track listing, these tracks will be added to the playlist.

Parameters:

  | device | a pointer to the device to create the new playlist on.
  | metadata | the metadata for the new playlist. If the function exits with success, the `playlist_id` field of this struct will contain the new playlist ID of the playlist. `parent_id` will also be valid.
  | parenthandle | the parent (e.g. folder) to store this playlist in. Pass in 0 to put the playlist in the root directory.

Returns:
  0 on success, any other value means failure.

See also:
  LIBMTP_Update_Playlist()

  LIBMTP_Delete_Object()

References LIBMTP_mtpdevice_struct::default_playlist_folder, LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, playlist_t_to_spl(), LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo.

Referenced by update_spl_playlist().

void LIBMTP_destroy_playlist_t | ( | LIBMTP_playlist_t * | 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.

Parameters:

  | playlist | the playlist metadata to destroy.

See also:
  LIBMTP_new_playlist_t()

References LIBMTP_playlist_struct::name, and LIBMTP_playlist_struct::tracks.

LIBMTP_playlist_t* LIBMTP_Get_Playlist | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | plid |
| ) |  |  |

This function retrieves an individual playlist from the device.

Parameters:

  | device | a pointer to the device to get the playlist from.
  | plid | the unique ID of the playlist to retrieve.

Returns:
  a valid playlist metadata post or NULL on failure.

See also:
  LIBMTP_Get_Playlist_List()

References is_spl_playlist(), LIBMTP_new_playlist_t(), LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, spl_to_playlist_t(), LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo.

Referenced by update_spl_playlist().

LIBMTP_playlist_t* LIBMTP_Get_Playlist_List | ( | LIBMTP_mtpdevice_t * | device | ) |

This function returns a list of the playlists available on the device. Typical usage:

Parameters:

  | device | a pointer to the device to get the playlist listing from.

Returns:
  a playlist list on success, else NULL. If there are no playlists on the device, NULL will be returned as well.

See also:
  LIBMTP_Get_Playlist()

References is_spl_playlist(), LIBMTP_new_playlist_t(), LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::next, LIBMTP_playlist_struct::no_tracks, LIBMTP_mtpdevice_struct::params, LIBMTP_playlist_struct::parent_id, LIBMTP_playlist_struct::playlist_id, spl_to_playlist_t(), LIBMTP_playlist_struct::storage_id, LIBMTP_playlist_struct::tracks, and LIBMTP_mtpdevice_struct::usbinfo.

LIBMTP_playlist_t* 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 `LIBMTP_destroy_playlist_t` operation later, so be careful of using strdup() when assigning strings, e.g.:

     LIBMTP_playlist_t *pl = LIBMTP_new_playlist_t();
     pl->name = strdup(str);
     ....
     LIBMTP_destroy_playlist_t(pl);

Returns:
  a pointer to the newly allocated metadata structure.

See also:
  LIBMTP_destroy_playlist_t()

References LIBMTP_playlist_struct::playlist_id.

Referenced by LIBMTP_Get_Playlist(), and LIBMTP_Get_Playlist_List().

int LIBMTP_Set_Playlist_Name | ( | LIBMTP_mtpdevice_t * | device,
|  | LIBMTP_playlist_t * | playlist,
|  | const char * | newname |
| ) |  |  |

This function renames a single playlist. This simply means that the PTP_OPC_ObjectFileName property is updated, if this is supported by the device.

Parameters:

  | device | a pointer to the device that contains the file.
  | playlist | 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.
  | newname | the new name for this object.

Returns:
  0 on success, any other value means failure.

References LIBMTP_playlist_struct::name, and LIBMTP_playlist_struct::playlist_id.

Referenced by update_spl_playlist().

int LIBMTP_Update_Playlist | ( | LIBMTP_mtpdevice_t * | device,
|  | LIBMTP_playlist_t const *const | metadata |
| ) |  |  |

This routine updates a playlist based on the metadata supplied. If the `tracks` 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.

Parameters:

  | device | a pointer to the device to create the new playlist on.
  | metadata | the metadata for the playlist to be updated. notice that the field `playlist_id` must contain the apropriate playlist ID.

Returns:
  0 on success, any other value means failure.

See also:
  LIBMTP_Create_New_Playlist()

  LIBMTP_Delete_Object()

References LIBMTP_playlist_struct::name, LIBMTP_playlist_struct::no_tracks, LIBMTP_playlist_struct::playlist_id, LIBMTP_playlist_struct::tracks, update_spl_playlist(), and LIBMTP_mtpdevice_struct::usbinfo.