search.h File Reference

MPD client library. More...

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

Go to the source code of this file.

## Enumerations

enum | mpd_operator { MPD_OPERATOR_DEFAULT }

## Functions

bool | mpd_search_db_songs (struct mpd_connection *connection, bool exact)
bool | mpd_search_add_db_songs (struct mpd_connection *connection, bool exact)
bool | mpd_search_add_db_songs_to_playlist (struct mpd_connection *connection, const char *playlist_name)
bool | mpd_search_queue_songs (struct mpd_connection *connection, bool exact)
bool | mpd_search_db_tags (struct mpd_connection *connection, enum mpd_tag_type type)
bool | mpd_count_db_songs (struct mpd_connection *connection)
bool | mpd_search_add_base_constraint (struct mpd_connection *connection, enum mpd_operator oper, const char *value)
bool | mpd_search_add_uri_constraint (struct mpd_connection *connection, enum mpd_operator oper, const char *value)
bool | mpd_search_add_tag_constraint (struct mpd_connection *connection, enum mpd_operator oper, enum mpd_tag_type type, const char *value)
bool | mpd_search_add_any_tag_constraint (struct mpd_connection *connection, enum mpd_operator oper, const char *value)
bool | mpd_search_add_modified_since_constraint (struct mpd_connection *connection, enum mpd_operator oper, time_t value)
bool | mpd_search_add_expression (struct mpd_connection *connection, const char *expression)
bool | mpd_search_add_group_tag (struct mpd_connection *connection, enum mpd_tag_type type)
bool | mpd_search_add_sort_name (struct mpd_connection *connection, const char *name, bool descending)
bool | mpd_search_add_sort_tag (struct mpd_connection *connection, enum mpd_tag_type type, bool descending)
bool | mpd_search_add_window (struct mpd_connection *connection, unsigned start, unsigned end)
bool | mpd_search_add_position (struct mpd_connection *connection, unsigned position, enum mpd_position_whence whence)
bool | mpd_search_commit (struct mpd_connection *connection)
void | mpd_search_cancel (struct mpd_connection *connection)
struct mpd_pair * | mpd_recv_pair_tag (struct mpd_connection *connection, enum mpd_tag_type type)

## Detailed Description

MPD client library.

Search songs in the database or the queue.

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

Definition in file search.h.

## Enumeration Type Documentation

## mpd_operator

enum mpd_operator

This type is not yet used, it is reserved for a future protocol extension which will allow us to specify a comparison operator for constraints.

Enumerator
MPD_OPERATOR_DEFAULT | The default search operator. If "exact" was passed as "true", then it means "full string comparison"; if false, then it means "search for substring".

Definition at line 57 of file search.h.

## Function Documentation

## mpd_search_db_songs()

bool mpd_search_db_songs | ( | struct mpd_connection * | connection,
|  | bool | exact
| ) |  |

Search for songs in the database. Constraints may be specified with mpd_search_add_tag_constraint(). Send the search command with mpd_search_commit(), and read the response items with mpd_recv_song().

Parameters

  connection | the connection to MPD
  exact | if to match exact

Returns
  true on success, false on error

## mpd_search_add_db_songs()

bool mpd_search_add_db_songs | ( | struct mpd_connection * | connection,
|  | bool | exact
| ) |  |

Search for songs in the database and adds the result to the queue. Constraints may be specified with mpd_search_add_tag_constraint(). Send the search command with mpd_search_commit().

Parameters

  connection | the connection to MPD
  exact | if to match exact (only "true" supported by MPD 0.16)

Returns
  true on success, false on error

## mpd_search_add_db_songs_to_playlist()

bool mpd_search_add_db_songs_to_playlist | ( | struct mpd_connection * | connection,
|  | const char * | playlist_name
| ) |  |

Search for songs in the database and adds the result to a playlist. Constraints may be specified with mpd_search_add_tag_constraint(). Send the search command with mpd_search_commit().

Parameters

  connection | the connection to MPD
  playlist_name | the name of the playlist where songs shall be added

Returns
  true on success, false on error

Since
  libmpdclient 2.17.

## mpd_search_queue_songs()

bool mpd_search_queue_songs | ( | struct mpd_connection * | connection,
|  | bool | exact
| ) |  |

Search for songs in the queue. Constraints may be specified with mpd_search_add_tag_constraint(). Send the search command with mpd_search_commit(), and read the response items with mpd_recv_song().

Parameters

  connection | the connection to MPD
  exact | if to match exact

Returns
  true on success, false on error

## mpd_search_db_tags()

bool mpd_search_db_tags | ( | struct mpd_connection * | connection,
|  | enum mpd_tag_type | type
| ) |  |

Obtains a list of unique tag values from the database. Constraints may be specified with mpd_search_add_tag_constraint(). Send the search command with mpd_search_commit(), and read the response items with mpd_recv_pair_tag().

Parameters

  connection | the connection to MPD
  type | The type of the tags to search for

Returns
  true on success, false on error

## mpd_count_db_songs()

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

Gathers statistics on a set of songs in the database. Constraints may be specified with mpd_search_add_tag_constraint(). Send the command with mpd_search_commit(), and read the response with mpd_recv_stats().

Parameters

  connection | the connection to MPD

Returns
  true on success, false on error

## mpd_search_add_base_constraint()

bool mpd_search_add_base_constraint | ( | struct mpd_connection * | connection,
|  | enum mpd_operator | oper,
|  | const char * | value
| ) |  |

Limit the search to a certain directory.

Parameters

  connection | a mpd_connection
  oper | reserved, pass MPD_OPERATOR_DEFAULT
  value | the URI relative to the music directory

Returns
  true on success, false on error

Since
  libmpdclient 2.9

## mpd_search_add_uri_constraint()

bool mpd_search_add_uri_constraint | ( | struct mpd_connection * | connection,
|  | enum mpd_operator | oper,
|  | const char * | value
| ) |  |

Add a constraint on the song's URI.

Parameters

  connection | a mpd_connection
  oper | reserved, pass MPD_OPERATOR_DEFAULT
  value | The value of the constraint

Returns
  true on success, false on error

## mpd_search_add_tag_constraint()

bool mpd_search_add_tag_constraint | ( | struct mpd_connection * | connection,
|  | enum mpd_operator | oper,
|  | enum mpd_tag_type | type,
|  | const char * | value
| ) |  |

Add a constraint to a search limiting the value of a tag.

Parameters

  connection | a mpd_connection
  oper | reserved, pass MPD_OPERATOR_DEFAULT
  type | The tag type of the constraint
  value | The value of the constraint

Returns
  true on success, false on error

## mpd_search_add_any_tag_constraint()

bool mpd_search_add_any_tag_constraint | ( | struct mpd_connection * | connection,
|  | enum mpd_operator | oper,
|  | const char * | value
| ) |  |

Add a constraint to a search, search for a value in any tag.

Parameters

  connection | a mpd_connection
  oper | reserved, pass MPD_OPERATOR_DEFAULT
  value | The value of the constraint

Returns
  true on success, false on error

## mpd_search_add_modified_since_constraint()

bool mpd_search_add_modified_since_constraint | ( | struct mpd_connection * | connection,
|  | enum mpd_operator | oper,
|  | time_t | value
| ) |  |

Limit the search to files modified after the given time stamp.

Parameters

  connection | a mpd_connection
  oper | reserved, pass MPD_OPERATOR_DEFAULT
  value | the reference time stamp

Returns
  true on success, false on error

Since
  libmpdclient 2.10

## mpd_search_add_expression()

bool mpd_search_add_expression | ( | struct mpd_connection * | connection,
|  | const char * | expression
| ) |  |

Add an expression string.

Parameters

  connection | a mpd_connection
  expression | the expression string; must be enclosed in parentheses

Returns
  true on success, false on error

Since
  libmpdclient 2.15, MPD 0.21

## mpd_search_add_group_tag()

bool mpd_search_add_group_tag | ( | struct mpd_connection * | connection,
|  | enum mpd_tag_type | type
| ) |  |

Group the results by the specified tag.

Parameters

  connection | a mpd_connection
  type | the tag type to group by

Returns
  true on success, false on error

Since
  libmpdclient 2.12, MPD 0.19

## mpd_search_add_sort_name()

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

Sort the results by the specified named attribute.

Parameters

  connection | a mpd_connection
  name | the attribute name to sort with; can be a tag name or "Last-Modified"
  descending | sort in reverse order?

Returns
  true on success, false on error

Since
  MPD 0.21, libmpdclient 2.15

## mpd_search_add_sort_tag()

bool mpd_search_add_sort_tag | ( | struct mpd_connection * | connection,
|  | enum mpd_tag_type | type,
|  | bool | descending
| ) |  |

Sort the results by the specified tag.

Parameters

  connection | a mpd_connection
  type | the tag type to sort with
  descending | sort in reverse order?

Returns
  true on success, false on error

Since
  MPD 0.21, libmpdclient 2.11; #descending since libmpdclient 2.15

## mpd_search_add_window()

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

Request only a portion of the result set.

Parameters

  connection | a mpd_connection
  start | the start offset (including)
  end | the end offset (not including)

Returns
  true on success, false on error

Since
  libmpdclient 2.10

## mpd_search_add_position()

bool mpd_search_add_position | ( | struct mpd_connection * | connection,
|  | unsigned | position,
|  | enum mpd_position_whence | whence
| ) |  |

Adds the search to the specified position in the queue.

Parameters

  connection | a mpd_connection
  position | the position in the queue
  whence | how to interpret the position parameter

Since
  libmpdclient 2.20

## mpd_search_commit()

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

Starts the real search with constraints added with mpd_search_add_constraint().

Parameters

  connection | the connection to MPD

Returns
  true on success, false on error

## mpd_search_cancel()

void mpd_search_cancel | ( | struct mpd_connection * | connection | ) |

Cancels the search request before you have called mpd_search_commit(). Call this to clear the current search request.

Parameters

  connection | the connection to MPD

## mpd_recv_pair_tag()

struct mpd_pair* mpd_recv_pair_tag | ( | struct mpd_connection * | connection,
|  | enum mpd_tag_type | type
| ) |  |

Same as mpd_recv_pair_named(), but the pair name is specified as mpd_tag_type.

Parameters

  connection | the connection to MPD
  type | the tag type you are looking for

Returns
  a pair, or NULL on error or if there are no more matching pairs in this response