libmpdclient 2.14

Functions
queue.h File Reference

MPD client library. More...

Go to the source code of this file.

## Functions
bool | mpd_send_list_queue_meta (struct mpd_connection *connection)
bool | mpd_send_list_queue_range_meta (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_send_get_queue_song_pos (struct mpd_connection *connection, unsigned pos)
mpd_malloc struct mpd_song * | mpd_run_get_queue_song_pos (struct mpd_connection *connection, unsigned pos)
bool | mpd_send_get_queue_song_id (struct mpd_connection *connection, unsigned id)
mpd_malloc struct mpd_song * | mpd_run_get_queue_song_id (struct mpd_connection *connection, unsigned id)
bool | mpd_send_queue_changes_meta (struct mpd_connection *connection, unsigned version)
bool | mpd_send_queue_changes_meta_range (struct mpd_connection *connection, unsigned version, unsigned start, unsigned end)
bool | mpd_send_queue_changes_brief (struct mpd_connection *connection, unsigned version)
bool | mpd_send_queue_changes_brief_range (struct mpd_connection *connection, unsigned version, unsigned start, unsigned end)
bool | mpd_recv_queue_change_brief (struct mpd_connection *connection, unsigned *position_r, unsigned *id_r)
bool | mpd_send_add (struct mpd_connection *connection, const char *file)
bool | mpd_run_add (struct mpd_connection *connection, const char *uri)
bool | mpd_send_add_id (struct mpd_connection *connection, const char *file)
bool | mpd_send_add_id_to (struct mpd_connection *connection, const char *uri, unsigned to)
int | mpd_recv_song_id (struct mpd_connection *connection)
int | mpd_run_add_id (struct mpd_connection *connection, const char *file)
int | mpd_run_add_id_to (struct mpd_connection *connection, const char *uri, unsigned to)
bool | mpd_send_delete (struct mpd_connection *connection, unsigned pos)
bool | mpd_run_delete (struct mpd_connection *connection, unsigned pos)
bool | mpd_send_delete_range (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_run_delete_range (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_send_delete_id (struct mpd_connection *connection, unsigned id)
bool | mpd_run_delete_id (struct mpd_connection *connection, unsigned id)
bool | mpd_send_shuffle (struct mpd_connection *connection)
bool | mpd_run_shuffle (struct mpd_connection *connection)
bool | mpd_send_shuffle_range (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_run_shuffle_range (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_send_clear (struct mpd_connection *connection)
bool | mpd_run_clear (struct mpd_connection *connection)
bool | mpd_send_move (struct mpd_connection *connection, unsigned from, unsigned to)
bool | mpd_run_move (struct mpd_connection *connection, unsigned from, unsigned to)
bool | mpd_send_move_id (struct mpd_connection *connection, unsigned from, unsigned to)
bool | mpd_run_move_id (struct mpd_connection *connection, unsigned from, unsigned to)
bool | mpd_send_move_range (struct mpd_connection *connection, unsigned start, unsigned end, unsigned to)
bool | mpd_run_move_range (struct mpd_connection *connection, unsigned start, unsigned end, unsigned to)
bool | mpd_send_swap (struct mpd_connection *connection, unsigned pos1, unsigned pos2)
bool | mpd_run_swap (struct mpd_connection *connection, unsigned pos1, unsigned pos2)
bool | mpd_send_swap_id (struct mpd_connection *connection, unsigned id1, unsigned id2)
bool | mpd_run_swap_id (struct mpd_connection *connection, unsigned id1, unsigned id2)
bool | mpd_send_add_tag_id (struct mpd_connection *connection, unsigned id, enum mpd_tag_type tag, const char *value)
bool | mpd_run_add_tag_id (struct mpd_connection *connection, unsigned id, enum mpd_tag_type tag, const char *value)
bool | mpd_send_clear_tag_id (struct mpd_connection *connection, unsigned id, enum mpd_tag_type tag)
bool | mpd_run_clear_tag_id (struct mpd_connection *connection, unsigned id, enum mpd_tag_type tag)
bool | mpd_send_clear_all_tags_id (struct mpd_connection *connection, unsigned id)
bool | mpd_run_clear_all_tags_id (struct mpd_connection *connection, unsigned id)
bool | mpd_send_prio (struct mpd_connection *connection, int priority, unsigned position)
bool | mpd_run_prio (struct mpd_connection *connection, int priority, unsigned position)
bool | mpd_send_prio_range (struct mpd_connection *connection, int priority, unsigned start, unsigned end)
bool | mpd_run_prio_range (struct mpd_connection *connection, int priority, unsigned start, unsigned end)
bool | mpd_send_prio_id (struct mpd_connection *connection, int priority, unsigned id)
bool | mpd_run_prio_id (struct mpd_connection *connection, int priority, unsigned id)

## Detailed Description

MPD client library.

Manipulate the queue (current playlist).

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

Definition in file queue.h.

## Function Documentation

## ◆ mpd_send_list_queue_meta()

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

Sends the "playlistinfo" command: list all songs in the queue including meta information.

## ◆ mpd_send_list_queue_range_meta()

bool mpd_send_list_queue_range_meta | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Like mpd_send_list_queue_meta(), but specifies a (position) range.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_send_get_queue_song_pos()

bool mpd_send_get_queue_song_pos | ( | struct mpd_connection * | connection,
|  | unsigned | pos
| ) |  |

Requests information (including tags) about one song in the playlist (command "playlistid").

Parameters

  connection | the connection to MPD
  pos | the position of the requested song

## ◆ mpd_run_get_queue_song_pos()

mpd_malloc struct mpd_song* mpd_run_get_queue_song_pos | ( | struct mpd_connection * | connection,
|  | unsigned | pos
| ) |  |

Shortcut for mpd_send_get_queue_song_pos() and mpd_recv_song().

Parameters

  connection | the connection to MPD
  pos | the position of the requested song

Returns
  the song at the specified position, or NULL on error

## ◆ mpd_send_get_queue_song_id()

bool mpd_send_get_queue_song_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Requests information (including tags) about one song in the playlist (command "playlistid").

Parameters

  connection | the connection to MPD
  id | the id of the requested song

## ◆ mpd_run_get_queue_song_id()

mpd_malloc struct mpd_song* mpd_run_get_queue_song_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Shortcut for mpd_send_get_queue_song_id() and mpd_recv_song().

Parameters

  connection | the connection to MPD
  id | the id of the requested song

Returns
  the song at the specified id, or NULL on error

## ◆ mpd_send_queue_changes_meta()

bool mpd_send_queue_changes_meta | ( | struct mpd_connection * | connection,
|  | unsigned | version
| ) |  |

Request the queue changes from MPD since the specified version, including tags. The MPD command is called "plchanges".

Parameters

  connection | the connection to MPD
  version | The playlist version you want the diff with.

Returns
  true on success, false on error

## ◆ mpd_send_queue_changes_meta_range()

bool mpd_send_queue_changes_meta_range | ( | struct mpd_connection * | connection,
|  | unsigned | version,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Same as mpd_send_queue_changes_meta(), but limit the result to a range.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.12

## ◆ mpd_send_queue_changes_brief()

bool mpd_send_queue_changes_brief | ( | struct mpd_connection * | connection,
|  | unsigned | version
| ) |  |

A more bandwidth efficient version of the mpd_send_queue_changes_meta(). It only returns the position and id of changed songs. The MPD command is called "plchangesposid".

Parameters

  connection | A valid and connected mpd_connection.
  version | The playlist version you want the diff with.

Returns
  true on success, false on error

## ◆ mpd_send_queue_changes_brief_range()

bool mpd_send_queue_changes_brief_range | ( | struct mpd_connection * | connection,
|  | unsigned | version,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Same as mpd_send_queue_changes_brief(), but limit the result to a range.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.12

## ◆ mpd_recv_queue_change_brief()

bool mpd_recv_queue_change_brief | ( | struct mpd_connection * | connection,
|  | unsigned * | position_r,
|  | unsigned * | id_r
| ) |  |

Receives a response element of mpd_send_queue_changes_brief().

Parameters

  connection | A valid and connected mpd_connection.
  position_r | reference to the position of the changed song
  id_r | reference to the id of the changed song

Returns
  true on success, false on error or if there are no more changes in this response

## ◆ mpd_send_add()

bool mpd_send_add | ( | struct mpd_connection * | connection,
|  | const char * | file
| ) |  |

Appends a song to the playlist.

## ◆ mpd_run_add()

bool mpd_run_add | ( | struct mpd_connection * | connection,
|  | const char * | uri
| ) |  |

Shortcut for mpd_send_add() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  uri | the URI of the song to be added

Returns
  true on success, false on error

## ◆ mpd_send_add_id()

bool mpd_send_add_id | ( | struct mpd_connection * | connection,
|  | const char * | file
| ) |  |

Appends a song to the playlist, and returns its id.

## ◆ mpd_send_add_id_to()

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

Inserts a song into the playlist, and returns its id.

Parameters

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

Returns
  true on success, false on error

## ◆ mpd_recv_song_id()

int mpd_recv_song_id | ( | struct mpd_connection * | connection | ) |

Returns the id of the new song in the playlist. To be called after mpd_send_add_id().

Returns
  the new song id, -1 on error or if MPD did not send an id

## ◆ mpd_run_add_id()

int mpd_run_add_id | ( | struct mpd_connection * | connection,
|  | const char * | file
| ) |  |

Executes the "addid" command and reads the response.

Returns
  the new song id, -1 on error or if MPD did not send an id

## ◆ mpd_run_add_id_to()

int mpd_run_add_id_to | ( | struct mpd_connection * | connection,
|  | const char * | uri,
|  | unsigned | to
| ) |  |

Executes the "addid" command and reads the response.

Parameters

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

Returns
  the new song id, -1 on error or if MPD did not send an id

## ◆ mpd_send_delete()

bool mpd_send_delete | ( | struct mpd_connection * | connection,
|  | unsigned | pos
| ) |  |

Deletes a song from the queue.

Parameters

  connection | the connection to MPD
  pos | the position of the song to be deleted

## ◆ mpd_run_delete()

bool mpd_run_delete | ( | struct mpd_connection * | connection,
|  | unsigned | pos
| ) |  |

Shortcut for mpd_send_delete() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  pos | the position of the song to be deleted

Returns
  true on success, false on error

## ◆ mpd_send_delete_range()

bool mpd_send_delete_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Deletes songs from the queue.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_run_delete_range()

bool mpd_run_delete_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Shortcut for mpd_send_delete_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Returns
  true on success, false on error

Since
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_send_delete_id()

bool mpd_send_delete_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Deletes a song from the queue.

Parameters

  connection | the connection to MPD
  id | the id of the song to be deleted

## ◆ mpd_run_delete_id()

bool mpd_run_delete_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Shortcut for mpd_send_delete_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  id | the id of the song to be deleted

Returns
  true on success, false on error

## ◆ mpd_send_shuffle()

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

Shuffles the queue.

Parameters

  connection | the connection to MPD

## ◆ mpd_run_shuffle()

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

Shortcut for mpd_send_shuffle() and mpd_response_finish().

Parameters

  connection | the connection to MPD

## ◆ mpd_send_shuffle_range()

bool mpd_send_shuffle_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Shuffles a range within the queue.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Since
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_run_shuffle_range()

bool mpd_run_shuffle_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Shortcut for mpd_send_shuffle_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Since
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_send_clear()

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

Clear the queue.

Parameters

  connection | the connection to MPD

## ◆ mpd_run_clear()

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

Shortcut for mpd_send_clear() and mpd_response_finish().

Parameters

  connection | the connection to MPD

## ◆ mpd_send_move()

bool mpd_send_move | ( | struct mpd_connection * | connection,
|  | unsigned | from,
|  | unsigned | to
| ) |  |

Moves a song within the queue.

Parameters

  connection | the connection to MPD
  from | the source song position
  to | the new position of the song

## ◆ mpd_run_move()

bool mpd_run_move | ( | struct mpd_connection * | connection,
|  | unsigned | from,
|  | unsigned | to
| ) |  |

Shortcut for mpd_send_move() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  from | the source song position
  to | the new position of the song

## ◆ mpd_send_move_id()

bool mpd_send_move_id | ( | struct mpd_connection * | connection,
|  | unsigned | from,
|  | unsigned | to
| ) |  |

Moves a song within the queue.

Parameters

  connection | the connection to MPD
  from | the source song id
  to | the new position of the song (not an id!)

## ◆ mpd_run_move_id()

bool mpd_run_move_id | ( | struct mpd_connection * | connection,
|  | unsigned | from,
|  | unsigned | to
| ) |  |

Shortcut for mpd_send_move_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  from | the source song id
  to | the new position of the song (not an id!)

## ◆ mpd_send_move_range()

bool mpd_send_move_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to
| ) |  |

Moves a range of songs within the queue.

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" 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.8 added support for "(unsigned)-1"

## ◆ mpd_run_move_range()

bool mpd_run_move_range | ( | struct mpd_connection * | connection,
|  | unsigned | start,
|  | unsigned | end,
|  | unsigned | to
| ) |  |

Shortcut for mpd_send_move_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" 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.8 added support for "(unsigned)-1"

## ◆ mpd_send_swap()

bool mpd_send_swap | ( | struct mpd_connection * | connection,
|  | unsigned | pos1,
|  | unsigned | pos2
| ) |  |

Swap the position of two songs in the queue.

Parameters

  connection | the connection to MPD
  pos1 | the position of one song
  pos2 | the position of the other song

## ◆ mpd_run_swap()

bool mpd_run_swap | ( | struct mpd_connection * | connection,
|  | unsigned | pos1,
|  | unsigned | pos2
| ) |  |

Shortcut for mpd_send_swap() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  pos1 | the position of one song
  pos2 | the position of the other song

## ◆ mpd_send_swap_id()

bool mpd_send_swap_id | ( | struct mpd_connection * | connection,
|  | unsigned | id1,
|  | unsigned | id2
| ) |  |

Swap the position of two songs in the queue.

Parameters

  connection | the connection to MPD
  id1 | the id of one song
  id2 | the id of the other song

## ◆ mpd_run_swap_id()

bool mpd_run_swap_id | ( | struct mpd_connection * | connection,
|  | unsigned | id1,
|  | unsigned | id2
| ) |  |

Shortcut for mpd_send_swap_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  id1 | the id of one song
  id2 | the id of the other song

## ◆ mpd_send_add_tag_id()

bool mpd_send_add_tag_id | ( | struct mpd_connection * | connection,
|  | unsigned | id,
|  | enum mpd_tag_type | tag,
|  | const char * | value
| ) |  |

Adds a tag to the specified song (command "addtagid").

Parameters

  connection | the connection to MPD
  id | the id of the song
  tag | the tag to be added
  value | the tag value

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_run_add_tag_id()

bool mpd_run_add_tag_id | ( | struct mpd_connection * | connection,
|  | unsigned | id,
|  | enum mpd_tag_type | tag,
|  | const char * | value
| ) |  |

Shortcut for mpd_send_add_tag_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  id | the id of the song
  tag | the tag to be added
  value | the tag value

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_send_clear_tag_id()

bool mpd_send_clear_tag_id | ( | struct mpd_connection * | connection,
|  | unsigned | id,
|  | enum mpd_tag_type | tag
| ) |  |

Remove a tag from the specified song (command "cleartagid").

Parameters

  connection | the connection to MPD
  id | the id of the song
  tag | the tag to be cleared

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_run_clear_tag_id()

bool mpd_run_clear_tag_id | ( | struct mpd_connection * | connection,
|  | unsigned | id,
|  | enum mpd_tag_type | tag
| ) |  |

Shortcut for mpd_send_clear_tag_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  id | the id of the song
  tag | the tag to be cleared

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_send_clear_all_tags_id()

bool mpd_send_clear_all_tags_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Remove all tags from the specified song (command "cleartagid").

Parameters

  connection | the connection to MPD
  id | the id of the song

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_run_clear_all_tags_id()

bool mpd_run_clear_all_tags_id | ( | struct mpd_connection * | connection,
|  | unsigned | id
| ) |  |

Shortcut for mpd_send_clear_all_tags_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  id | the id of the song

Since
  libmpdclient 2.12, MPD 0.19

## ◆ mpd_send_prio()

bool mpd_send_prio | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | position
| ) |  |

Change the priority of the specified song.

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  position | the position of the song

Since
  libmpdclient 2.6

## ◆ mpd_run_prio()

bool mpd_run_prio | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | position
| ) |  |

Shortcut for mpd_send_prio() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  position | the position of the song

Since
  libmpdclient 2.6

## ◆ mpd_send_prio_range()

bool mpd_send_prio_range | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Change the priority of a song range.

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Since
  libmpdclient 2.6
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_run_prio_range()

bool mpd_run_prio_range | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | start,
|  | unsigned | end
| ) |  |

Shortcut for mpd_send_prio_range() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  start | the start position of the range (including)
  end | the end position of the range (excluding); the special value "(unsigned)-1" makes the end of the range open

Since
  libmpdclient 2.6
  libmpdclient 2.8 added support for "(unsigned)-1"

## ◆ mpd_send_prio_id()

bool mpd_send_prio_id | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | id
| ) |  |

Change the priority of the specified song.

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  id | the id of the song

Since
  libmpdclient 2.6

## ◆ mpd_run_prio_id()

bool mpd_run_prio_id | ( | struct mpd_connection * | connection,
|  | int | priority,
|  | unsigned | id
| ) |  |

Shortcut for mpd_send_prio_id() and mpd_response_finish().

Parameters

  connection | the connection to MPD
  priority | a number between 0 and 255
  id | the id of the song

Since
  libmpdclient 2.6