playlist.h File Reference

MPD client library. More...

`#include "compiler.h"`
`#include "position.h"`
`#include <stdbool.h>`
`#include <time.h>`

Go to the source code of this file.

## Enumerations

enum | mpd_queue_save_mode { MPD_QUEUE_SAVE_MODE_CREATE = 0 , MPD_QUEUE_SAVE_MODE_REPLACE , MPD_QUEUE_SAVE_MODE_APPEND , MPD_QUEUE_SAVE_MODE_UNKNOWN }

## Functions

void | mpd_playlist_free (struct mpd_playlist *playlist)
struct mpd_playlist * | mpd_playlist_dup (const struct mpd_playlist *playlist)
const char * | mpd_playlist_get_path (const struct mpd_playlist *playlist)
time_t | mpd_playlist_get_last_modified (const struct mpd_playlist *playlist)
struct mpd_playlist * | mpd_playlist_begin (const struct mpd_pair *pair)
bool | mpd_playlist_feed (struct mpd_playlist *playlist, const struct mpd_pair *pair)
bool | mpd_send_list_playlists (struct mpd_connection *connection)
struct mpd_playlist * | mpd_recv_playlist (struct mpd_connection *connection)
bool | mpd_send_list_playlist (struct mpd_connection *connection, const char *name)
bool | mpd_send_list_playlist_meta (struct mpd_connection *connection, const char *name)
bool | mpd_send_playlist_clear (struct mpd_connection *connection, const char *name)
bool | mpd_run_playlist_clear (struct mpd_connection *connection, const char *name)
bool | mpd_send_playlist_add (struct mpd_connection *connection, const char *name, const char *path)
bool | mpd_run_playlist_add (struct mpd_connection *connection, const char *name, const char *path)
bool | mpd_send_playlist_add_to (struct mpd_connection *connection, const char *name, const char *uri, unsigned to)
bool | mpd_run_playlist_add_to (struct mpd_connection *connection, const char *name, const char *uri, unsigned to)
bool | mpd_send_playlist_move (struct mpd_connection *connection, const char *name, unsigned from, unsigned to)
bool | mpd_run_playlist_move (struct mpd_connection *connection, const char *name, unsigned from, unsigned to)
bool | mpd_send_playlist_move_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end, unsigned to)
bool | mpd_run_playlist_move_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end, unsigned to)
bool | mpd_send_playlist_delete (struct mpd_connection *connection, const char *name, unsigned pos)
bool | mpd_run_playlist_delete (struct mpd_connection *connection, const char *name, unsigned pos)
bool | mpd_send_playlist_delete_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end)
bool | mpd_run_playlist_delete_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end)
bool | mpd_send_save (struct mpd_connection *connection, const char *name)
bool | mpd_run_save (struct mpd_connection *connection, const char *name)
bool | mpd_send_save_queue (struct mpd_connection *connection, const char *name, enum mpd_queue_save_mode mode)
bool | mpd_run_save_queue (struct mpd_connection *connection, const char *name, enum mpd_queue_save_mode mode)
const char * | mpd_lookup_queue_save_mode (enum mpd_queue_save_mode mode)
enum mpd_queue_save_mode | mpd_parse_queue_save_mode (const char *mode)
bool | mpd_send_load (struct mpd_connection *connection, const char *name)
bool | mpd_run_load (struct mpd_connection *connection, const char *name)
bool | mpd_send_load_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end)
bool | mpd_run_load_range (struct mpd_connection *connection, const char *name, unsigned start, unsigned end)
bool | mpd_send_load_range_to (struct mpd_connection *connection, const char *name, unsigned start, unsigned end, unsigned to, enum mpd_position_whence whence)
bool | mpd_run_load_range_to (struct mpd_connection *connection, const char *name, unsigned start, unsigned end, unsigned to, enum mpd_position_whence whence)
bool | mpd_send_rename (struct mpd_connection *connection, const char *from, const char *to)
bool | mpd_run_rename (struct mpd_connection *connection, const char *from, const char *to)
bool | mpd_send_rm (struct mpd_connection *connection, const char *name)
bool | mpd_run_rm (struct mpd_connection *connection, const char *name)

## Detailed Description

MPD client library.

Manipulate stored playlists.

Do not include this header directly. Use mpd/client.h instead.

Definition in file playlist.h.

## Enumeration Type Documentation

## mpd_queue_save_mode

enum mpd_queue_save_mode

MPDs queue save modes.

Since
  libmpdclient 2.21, MPD 0.24.

Enumerator
MPD_QUEUE_SAVE_MODE_CREATE | Create new playlist
MPD_QUEUE_SAVE_MODE_REPLACE | Replace existing playlist
MPD_QUEUE_SAVE_MODE_APPEND | Append to existing playlist
MPD_QUEUE_SAVE_MODE_UNKNOWN | Unknown queue save mode

Definition at line 38 of file playlist.h.

## Function Documentation

## mpd_playlist_free()

void mpd_playlist_free | ( | struct mpd_playlist * | playlist | ) |

Free memory allocated by the mpd_playlist object.

## mpd_playlist_dup()

struct mpd_playlist * mpd_playlist_dup | ( | const struct mpd_playlist * | playlist | ) |

Duplicates a mpd_playlist object.

Returns
  the new object, or NULL on out of memory

## mpd_playlist_get_path()

const char * mpd_playlist_get_path | ( | const struct mpd_playlist * | playlist | ) |

Returns the path name of this playlist file. It does not begin with a slash.

## mpd_playlist_get_last_modified()

time_t mpd_playlist_get_last_modified | ( | const struct mpd_playlist * | playlist | ) |

Returns
  the POSIX UTC time stamp of the last modification, or 0 if that is unknown

## mpd_playlist_begin()

struct mpd_playlist * mpd_playlist_begin | ( | const struct mpd_pair * | pair | ) |

Begins parsing a new playlist.

Parameters

  pair | the first pair in this playlist (name must be "playlist")

Returns
  the new mpd_playlist object, or NULL on error (out of memory, or pair name is not "playlist")

## mpd_playlist_feed()

bool mpd_playlist_feed | ( | struct mpd_playlist * | playlist,
|  | const struct mpd_pair * | pair )

Parses the pair, adding its information to the specified mpd_playlist object.

Returns
  true if the pair was parsed and added to the playlist (or if the pair was not understood and ignored), false if this pair is the beginning of the next playlist

## mpd_send_list_playlists()

bool mpd_send_list_playlists | ( | struct mpd_connection * | connection | ) |

Obtain a list of stored playlists. Use mpd_recv_playlist() to read the playlists.

Parameters

  connection | the connection to MPD

Returns
  true on success, false on error

Since
  libmpdclient 2.5

## mpd_recv_playlist()

struct mpd_playlist * mpd_recv_playlist | ( | struct mpd_connection * | connection | ) |

Receives the next playlist from the MPD server.

Returns
  a mpd_playlist object, or NULL on error or if the playlist list is finished

## mpd_send_list_playlist()

bool mpd_send_list_playlist | ( | struct mpd_connection * | connection,
|  | const char * | name )

List the content of the stored playlist identified by name. Use mpd_recv_entity() to receive the songs (MPD_ENTITY_TYPE_SONG).

Parameters

  connection | the connection to MPD
  name | the name of the playlist

Returns
  true on success, false on error

## mpd_send_list_playlist_meta()

bool mpd_send_list_playlist_meta | ( | struct mpd_connection * | connection,
|  | const char * | name )

List the content, with full metadata, of the stored playlist identified by name. Use mpd_recv_entity() to receive the songs (MPD_ENTITY_TYPE_SONG).

Parameters

  connection | the connection to MPD
  name | the name of the playlist

Returns
  true on success, false on error

## mpd_send_playlist_clear()

bool mpd_send_playlist_clear | ( | struct mpd_connection * | connection,
|  | const char * | name )

Clear the playlist name (i.e. truncate name.m3u)

Parameters

  connection | the connection to MPD
  name | the name of the playlist

Returns
  true on success, false on error

## mpd_run_playlist_clear()

bool mpd_run_playlist_clear | ( | struct mpd_connection * | connection,
|  | const char * | name )

Shortcut for mpd_send_playlist_clear() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist

Returns
  true on success, false on error

## mpd_send_playlist_add()

bool mpd_send_playlist_add | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | const char * | path )

Add a path to a playlist. The playlist will be created if it does not exist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  path | URI to be added

Returns
  true on success, false on error

## mpd_run_playlist_add()

bool mpd_run_playlist_add | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | const char * | path )

Shortcut for mpd_send_playlist_add() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  path | URI to be added

Returns
  true on success, false on error

## mpd_send_playlist_add_to()

bool mpd_send_playlist_add_to | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | const char * | uri,
|  | unsigned | to )

Inserts a uri to a playlist for a given position. The playlist will be created if it does not exist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  uri | URI to be added
  to | the desired position

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_run_playlist_add_to()

bool mpd_run_playlist_add_to | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | const char * | uri,
|  | unsigned | to )

Shortcut for mpd_send_playlist_add_to() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  uri | URI to be added
  to | the desired position

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_send_playlist_move()

bool mpd_send_playlist_move | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | from,
|  | unsigned | to )

Move a song from one position to another in the same playlist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  from | previous song place in the playlist
  to | next song position in the playlist

Returns
  true on success, false on error

## mpd_run_playlist_move()

bool mpd_run_playlist_move | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | from,
|  | unsigned | to )

Shortcut for mpd_send_playlist_move() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  from | previous song place in the playlist
  to | next song position in the playlist

Returns
  true on success, false on error

Since
  libmpdclient 2.19

## mpd_send_playlist_move_range()

bool mpd_send_playlist_move_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to )

Moves a range of songs within the same playlist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open
  to | the new position of the song range

Returns
  true on success, false on error

Since
  libmpdclient 2.21, MPD 0.24

## mpd_run_playlist_move_range()

bool mpd_run_playlist_move_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to )

Shortcut for mpd_send_playlist_move_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open
  to | the new position of the song range

Returns
  true on success, false on error

Since
  libmpdclient 2.21, MPD 0.24

## mpd_send_playlist_delete()

bool mpd_send_playlist_delete | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | pos )

Delete a position from a playlist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  pos | song position in the playlist

Returns
  true on success, false on error

## mpd_run_playlist_delete()

bool mpd_run_playlist_delete | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | pos )

Shortcut for mpd_send_playlist_delete() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  pos | song position in the playlist

Returns
  true on success, false on error

## mpd_send_playlist_delete_range()

bool mpd_send_playlist_delete_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end )

Delete a range from a playlist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  start | the start position of the range (including)
  end | the end position of the range (excluding)

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_run_playlist_delete_range()

bool mpd_run_playlist_delete_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end )

Shortcut for mpd_send_playlist_delete_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist
  start | the start position of the range (including)
  end | the end position of the range (excluding)

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_send_save()

bool mpd_send_save | ( | struct mpd_connection * | connection,
|  | const char * | name )

Saves the current queue as a m3u file in the playlist directory (i.e. name.m3u).

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error

## mpd_run_save()

bool mpd_run_save | ( | struct mpd_connection * | connection,
|  | const char * | name )

Shortcut for mpd_send_save() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error

## mpd_send_save_queue()

bool mpd_send_save_queue | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | enum mpd_queue_save_mode | mode )

Saves the current queue as a m3u file in the playlist directory (i.e. name.m3u). This function supports the mode argument that can be MPD_QUEUE_SAVE_MODE_CREATE: creates a new playlist, same as mpd_send_save MPD_QUEUE_SAVE_MODE_REPLACE: replaces an existing playlist MPD_QUEUE_SAVE_MODE_APPEND: appends to an existing playlist

Since
  libmpdclient 2.21, MPD 0.24.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  mode | the desired save mode

Returns
  true on success, false on error

## mpd_run_save_queue()

bool mpd_run_save_queue | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | enum mpd_queue_save_mode | mode )

Shortcut for mpd_send_save_queue() and mpd_response_finish().

Since
  libmpdclient 2.21, MPD 0.24.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  mode | the desired save mode

Returns
  true on success, false on error

## mpd_lookup_queue_save_mode()

const char * mpd_lookup_queue_save_mode | ( | enum mpd_queue_save_mode | mode | ) |

Looks up the name of the specified queue save mode.

Returns
  the name, or NULL if the queue save mode is not valid

Since
  libmpdclient 2.21.

## mpd_parse_queue_save_mode()

enum mpd_queue_save_mode mpd_parse_queue_save_mode | ( | const char * | mode | ) |

Parse the string to check which queue save mode it contains.

Returns
  the queue save mode enum

Since
  libmpdclient 2.21.

## mpd_send_load()

bool mpd_send_load | ( | struct mpd_connection * | connection,
|  | const char * | name )

Load a stored playlist into the queue.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error

Since
  libmpdclient 2.0

## mpd_run_load()

bool mpd_run_load | ( | struct mpd_connection * | connection,
|  | const char * | name )

Shortcut for mpd_send_load() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error

Since
  libmpdclient 2.0

## mpd_send_load_range()

bool mpd_send_load_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end )

Like mpd_send_load(), but load only a portion of the playlist.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.16

## mpd_run_load_range()

bool mpd_run_load_range | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end )

Shortcut for mpd_send_load_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.16

## mpd_send_load_range_to()

bool mpd_send_load_range_to | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to,
|  | enum mpd_position_whence | whence )

Like mpd_send_load() or mpd_send_load_range(), but with range and to parameters.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open
  to | the desired position of the song
  whence | how to interpret the position parameter

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_run_load_range_to()

bool mpd_run_load_range_to | ( | struct mpd_connection * | connection,
|  | const char * | name,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to,
|  | enum mpd_position_whence | whence )

Shortcut for mpd_send_load_range_to() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist file
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "UINT_MAX" makes the end of the range open
  to | the desired position of the song
  whence | how to interpret the position parameter

Returns
  true on success, false on error

Since
  libmpdclient 2.20

## mpd_send_rename()

bool mpd_send_rename | ( | struct mpd_connection * | connection,
|  | const char * | from,
|  | const char * | to )

Rename a playlist in the playlist directory.

Parameters

  connection | the connection to MPD
  from | the previous name of the playlist file
  to | the next name of the playlist file

Returns
  true on success, false on error

## mpd_run_rename()

bool mpd_run_rename | ( | struct mpd_connection * | connection,
|  | const char * | from,
|  | const char * | to )

Shortcut for mpd_send_rename() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  from | the previous name of the playlist file
  to | the next name of the playlist file

Returns
  true on success, false on error

## mpd_send_rm()

bool mpd_send_rm | ( | struct mpd_connection * | connection,
|  | const char * | name )

Remove a playlist from the playlist directory.

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error

## mpd_run_rm()

bool mpd_run_rm | ( | struct mpd_connection * | connection,
|  | const char * | name )

Shortcut for mpd_send_rm() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  name | the name of the playlist file

Returns
  true on success, false on error