## RhythmDB

RhythmDB — Rhythmbox database functions

## Synopsis

    #define             RHYTHMDB_TYPE
    #define             RHYTHMDB                            (o)
    #define             RHYTHMDB_IS                         (o)
    typedef             RhythmDBQuery;
    enum                RhythmDBQueryType;
    enum                RhythmDBPropType;
    #define             RHYTHMDB_PROP_STREAM_SONG_TITLE
    #define             RHYTHMDB_PROP_STREAM_SONG_ARTIST
    #define             RHYTHMDB_PROP_STREAM_SONG_ALBUM
    #define             RHYTHMDB_PROP_COVER_ART
    #define             RHYTHMDB_PROP_COVER_ART_URI
                        RhythmDBQueryData;
                        RhythmDBEntryChange;
    const char *        rhythmdb_entry_get_string           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    RBRefString *       rhythmdb_entry_get_refstring        (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    char *              rhythmdb_entry_dup_string           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    gboolean            rhythmdb_entry_get_boolean          (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    guint64             rhythmdb_entry_get_uint64           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    gulong              rhythmdb_entry_get_ulong            (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    double              rhythmdb_entry_get_double           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    GObject *           rhythmdb_entry_get_object           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);
    RhythmDBEntryType * rhythmdb_entry_get_entry_type       (RhythmDBEntry *entry);
    enum                RhythmDBError;
    #define             RHYTHMDB_ERROR
    GQuark              rhythmdb_error_quark                (void);
    struct              RhythmDB;
    struct              RhythmDBClass;
    GType               rhythmdb_get_type                   (void);
    void                rhythmdb_shutdown                   (RhythmDB *db);
    void                rhythmdb_load                       (RhythmDB *db);
    void                rhythmdb_save                       (RhythmDB *db);
    void                rhythmdb_save_async                 (RhythmDB *db);
    void                rhythmdb_start_action_thread        (RhythmDB *db);
    void                rhythmdb_commit                     (RhythmDB *db);
    RhythmDBEntry *     rhythmdb_entry_new                  (RhythmDB *db,
                                                             RhythmDBEntryType *type,
                                                             const char *uri);
    RhythmDBEntry *     rhythmdb_entry_example_new          (RhythmDB *db,
                                                             RhythmDBEntryType *type,
                                                             const char *uri);
    void                rhythmdb_add_uri                    (RhythmDB *db,
                                                             const char *uri);
    void                rhythmdb_add_uri_with_types         (RhythmDB *db,
                                                             const char *uri,
                                                             RhythmDBEntryType *type,
                                                             RhythmDBEntryType *ignore_type,
                                                             RhythmDBEntryType *error_type);
    void                rhythmdb_entry_get                  (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RhythmDBPropType propid,
                                                             GValue *val);
    void                rhythmdb_entry_set                  (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             guint propid,
                                                             const GValue *value);
    gboolean            rhythmdb_entry_is_lossless          (RhythmDBEntry *entry);
    gpointer            rhythmdb_entry_get_type_data        (RhythmDBEntry *entry,
                                                             guint expected_size);
    #define             RHYTHMDB_ENTRY_GET_TYPE_DATA        (e,
                                                             t)
    void                rhythmdb_entry_delete               (RhythmDB *db,
                                                             RhythmDBEntry *entry);
    void                rhythmdb_entry_delete_by_type       (RhythmDB *db,
                                                             RhythmDBEntryType *type);
    void                rhythmdb_entry_move_to_trash        (RhythmDB *db,
                                                             RhythmDBEntry *entry);
    RhythmDBEntry *     rhythmdb_entry_lookup_by_location   (RhythmDB *db,
                                                             const char *uri);
    RhythmDBEntry *     rhythmdb_entry_lookup_by_id         (RhythmDB *db,
                                                             gint id);
    RhythmDBEntry *     rhythmdb_entry_lookup_from_string   (RhythmDB *db,
                                                             const char *str,
                                                             gboolean is_id);
    gboolean            rhythmdb_evaluate_query             (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBEntry *entry);
    void                rhythmdb_entry_foreach              (RhythmDB *db,
                                                             GFunc func,
                                                             gpointer data);
    gint64              rhythmdb_entry_count                (RhythmDB *db);
    void                rhythmdb_entry_foreach_by_type      (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type,
                                                             GFunc func,
                                                             gpointer data);
    gint64              rhythmdb_entry_count_by_type        (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type);
    gboolean            rhythmdb_entry_keyword_add          (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);
    gboolean            rhythmdb_entry_keyword_remove       (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);
    gboolean            rhythmdb_entry_keyword_has          (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);
    void                rhythmdb_entry_write_metadata_changes
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             GSList *changes,
                                                             GError **error);
    RBExtDBKey *        rhythmdb_entry_create_ext_db_key    (RhythmDBEntry *entry,
                                                             RhythmDBPropType prop);
    gboolean            rhythmdb_entry_matches_ext_db_key   (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBExtDBKey *key);
    void                rhythmdb_do_full_query              (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             ...);
    void                rhythmdb_do_full_query_parsed       (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             RhythmDBQuery *query);
    void                rhythmdb_do_full_query_async        (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             ...);
    void                rhythmdb_do_full_query_async_parsed (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             RhythmDBQuery *query);
    RhythmDBQuery *     rhythmdb_query_parse                (RhythmDB *db,
                                                             ...);
    void                rhythmdb_query_append               (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             ...);
    void                rhythmdb_query_append_params        (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBQueryType type,
                                                             RhythmDBPropType prop,
                                                             const GValue *value);
    void                rhythmdb_query_append_prop_multiple (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBPropType propid,
                                                             GList *items);
    void                rhythmdb_query_concatenate          (RhythmDBQuery *query1,
                                                             RhythmDBQuery *query2);
    void                rhythmdb_query_free                 (RhythmDBQuery *query);
    RhythmDBQuery *     rhythmdb_query_copy                 (RhythmDBQuery *array);
    void                rhythmdb_query_preprocess           (RhythmDB *db,
                                                             RhythmDBQuery *query);
    void                rhythmdb_query_serialize            (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             xmlNodePtr parent);
    RhythmDBQuery *     rhythmdb_query_deserialize          (RhythmDB *db,
                                                             xmlNodePtr parent);
    char *              rhythmdb_query_to_string            (RhythmDB *db,
                                                             RhythmDBQuery *query);
    gboolean            rhythmdb_query_is_time_relative     (RhythmDB *db,
                                                             RhythmDBQuery *query);
    const xmlChar *     rhythmdb_nice_elt_name_from_propid  (RhythmDB *db,
                                                             RhythmDBPropType propid);
    int                 rhythmdb_propid_from_nice_elt_name  (RhythmDB *db,
                                                             const xmlChar *name);
    void                rhythmdb_emit_entry_added           (RhythmDB *db,
                                                             RhythmDBEntry *entry);
    void                rhythmdb_emit_entry_deleted         (RhythmDB *db,
                                                             RhythmDBEntry *entry);
    GValue *            rhythmdb_entry_request_extra_metadata
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             const gchar *property_name);
    RBStringValueMap *  rhythmdb_entry_gather_metadata      (RhythmDB *db,
                                                             RhythmDBEntry *entry);
    void                rhythmdb_emit_entry_extra_metadata_notify
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             const gchar *property_name,
                                                             const GValue *metadata);
    char *              rhythmdb_compute_status_normal      (gint n_songs,
                                                             glong duration,
                                                             guint64 size,
                                                             const char *singular,
                                                             const char *plural);
    void                rhythmdb_register_entry_type        (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type);
    RhythmDBEntryType * rhythmdb_entry_type_get_by_name     (RhythmDB *db,
                                                             const char *name);
    GType               rhythmdb_get_property_type          (RhythmDB *db,
                                                             guint property_id);
    RhythmDBEntry *     rhythmdb_entry_ref                  (RhythmDBEntry *entry);
    void                rhythmdb_entry_unref                (RhythmDBEntry *entry);
                        RhythmDBPrivate;

## Object Hierarchy

      GBoxed
       +----RhythmDBQuery

      GEnum
       +----RhythmDBQueryType

      GEnum
       +----RhythmDBPropType

      GObject
       +----RhythmDB

## Properties

      "dry-run"                  gboolean              : Read / Write
      "name"                     gchar*                : Read / Write
      "no-update"                gboolean              : Read / Write

## Signals

      "create-mount-op"                                : Run Last
      "entry-added"                                    : Run Last
      "entry-changed"                                  : Run Last
      "entry-deleted"                                  : Run Last
      "entry-extra-metadata-gather"                    : Run Last
      "entry-extra-metadata-notify"                    : Has Details
      "entry-extra-metadata-request"                   : Has Details
      "entry-keyword-added"                            : Run Last
      "entry-keyword-removed"                          : Run Last
      "load-complete"                                  : Run Last
      "read-only"                                      : Run Last
      "save-complete"                                  : Run Last
      "save-error"                                     : Run Last

## Description

RhythmDB is an in-memory database containing RhythmDBEntry items. It runs queries represented as GPtrArrays containing query criteria, feeding the results into RhythmDBQueryResults implementations such as RhythmDBQueryModel. From there, entries are grouped by particular property values to form RhythmDBPropertyModels.

RhythmDBEntry contains a fixed set of properties, defined by RhythmDBPropType,

## Details

### RHYTHMDB_TYPE

    #define RHYTHMDB_TYPE      (rhythmdb_get_type ())

### RHYTHMDB()

    #define RHYTHMDB(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE, RhythmDB))

### RHYTHMDB_IS()

    #define RHYTHMDB_IS(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE))

### RhythmDBQuery

    typedef GPtrArray RhythmDBQuery;

### enum RhythmDBQueryType

    typedef enum {
    	RHYTHMDB_QUERY_END,
    	RHYTHMDB_QUERY_DISJUNCTION,
    	RHYTHMDB_QUERY_SUBQUERY,

    	/* general */
    	RHYTHMDB_QUERY_PROP_EQUALS,
    	RHYTHMDB_QUERY_PROP_NOT_EQUAL,

    	/* string */
    	RHYTHMDB_QUERY_PROP_LIKE,
    	RHYTHMDB_QUERY_PROP_NOT_LIKE,
    	RHYTHMDB_QUERY_PROP_PREFIX,
    	RHYTHMDB_QUERY_PROP_SUFFIX,

    	/* numerical */
    	RHYTHMDB_QUERY_PROP_GREATER,
    	RHYTHMDB_QUERY_PROP_LESS,

    	/* synthetic query types, translated into non-synthetic ones internally */
    	RHYTHMDB_QUERY_PROP_CURRENT_TIME_WITHIN,
    	RHYTHMDB_QUERY_PROP_CURRENT_TIME_NOT_WITHIN,
    	RHYTHMDB_QUERY_PROP_YEAR_EQUALS,
    	RHYTHMDB_QUERY_PROP_YEAR_NOT_EQUAL,
    	RHYTHMDB_QUERY_PROP_YEAR_GREATER,
    	RHYTHMDB_QUERY_PROP_YEAR_LESS,
    } RhythmDBQueryType;

`RHYTHMDB_QUERY_END` |
`RHYTHMDB_QUERY_DISJUNCTION` |
`RHYTHMDB_QUERY_SUBQUERY` |
`RHYTHMDB_QUERY_PROP_EQUALS` |
`RHYTHMDB_QUERY_PROP_NOT_EQUAL` |
`RHYTHMDB_QUERY_PROP_LIKE` |
`RHYTHMDB_QUERY_PROP_NOT_LIKE` |
`RHYTHMDB_QUERY_PROP_PREFIX` |
`RHYTHMDB_QUERY_PROP_SUFFIX` |
`RHYTHMDB_QUERY_PROP_GREATER` |
`RHYTHMDB_QUERY_PROP_LESS` |
`RHYTHMDB_QUERY_PROP_CURRENT_TIME_WITHIN` |
`RHYTHMDB_QUERY_PROP_CURRENT_TIME_NOT_WITHIN` |
`RHYTHMDB_QUERY_PROP_YEAR_EQUALS` |
`RHYTHMDB_QUERY_PROP_YEAR_NOT_EQUAL` |
`RHYTHMDB_QUERY_PROP_YEAR_GREATER` |
`RHYTHMDB_QUERY_PROP_YEAR_LESS` |

### enum RhythmDBPropType

    typedef enum {
    	RHYTHMDB_PROP_TYPE = 0,
    	RHYTHMDB_PROP_ENTRY_ID,
    	RHYTHMDB_PROP_TITLE,
    	RHYTHMDB_PROP_GENRE,
    	RHYTHMDB_PROP_ARTIST,
    	RHYTHMDB_PROP_ALBUM,
    	RHYTHMDB_PROP_TRACK_NUMBER,
    	RHYTHMDB_PROP_DISC_NUMBER,
    	RHYTHMDB_PROP_DURATION,
    	RHYTHMDB_PROP_FILE_SIZE,
    	RHYTHMDB_PROP_LOCATION,
    	RHYTHMDB_PROP_MOUNTPOINT,
    	RHYTHMDB_PROP_MTIME,
    	RHYTHMDB_PROP_FIRST_SEEN,
    	RHYTHMDB_PROP_LAST_SEEN,
    	RHYTHMDB_PROP_RATING,
    	RHYTHMDB_PROP_PLAY_COUNT,
    	RHYTHMDB_PROP_LAST_PLAYED,
    	RHYTHMDB_PROP_BITRATE,
    	RHYTHMDB_PROP_DATE,
    	RHYTHMDB_PROP_TRACK_GAIN,			/* obsolete */
    	RHYTHMDB_PROP_TRACK_PEAK,			/* obsolete */
    	RHYTHMDB_PROP_ALBUM_GAIN,			/* obsolete */
    	RHYTHMDB_PROP_ALBUM_PEAK,			/* obsolete */
    	RHYTHMDB_PROP_MEDIA_TYPE,
    	RHYTHMDB_PROP_TITLE_SORT_KEY,
    	RHYTHMDB_PROP_GENRE_SORT_KEY,
    	RHYTHMDB_PROP_ARTIST_SORT_KEY,
    	RHYTHMDB_PROP_ALBUM_SORT_KEY,
    	RHYTHMDB_PROP_TITLE_FOLDED,
    	RHYTHMDB_PROP_GENRE_FOLDED,
    	RHYTHMDB_PROP_ARTIST_FOLDED,
    	RHYTHMDB_PROP_ALBUM_FOLDED,
    	RHYTHMDB_PROP_LAST_PLAYED_STR,
    	RHYTHMDB_PROP_HIDDEN,
    	RHYTHMDB_PROP_PLAYBACK_ERROR,
    	RHYTHMDB_PROP_FIRST_SEEN_STR,
    	RHYTHMDB_PROP_LAST_SEEN_STR,

    	/* synthetic properties */
    	RHYTHMDB_PROP_SEARCH_MATCH,
    	RHYTHMDB_PROP_YEAR,
    	RHYTHMDB_PROP_KEYWORD, /**/

    	/* Podcast properties */
    	RHYTHMDB_PROP_STATUS,
    	RHYTHMDB_PROP_DESCRIPTION,
    	RHYTHMDB_PROP_SUBTITLE,
    	RHYTHMDB_PROP_SUMMARY,
    	RHYTHMDB_PROP_LANG,
    	RHYTHMDB_PROP_COPYRIGHT,
    	RHYTHMDB_PROP_IMAGE,
    	RHYTHMDB_PROP_POST_TIME,

    	RHYTHMDB_PROP_MUSICBRAINZ_TRACKID,
    	RHYTHMDB_PROP_MUSICBRAINZ_ARTISTID,
    	RHYTHMDB_PROP_MUSICBRAINZ_ALBUMID,
    	RHYTHMDB_PROP_MUSICBRAINZ_ALBUMARTISTID,
    	RHYTHMDB_PROP_ARTIST_SORTNAME,
    	RHYTHMDB_PROP_ALBUM_SORTNAME,

    	RHYTHMDB_PROP_ARTIST_SORTNAME_SORT_KEY,
    	RHYTHMDB_PROP_ARTIST_SORTNAME_FOLDED,
    	RHYTHMDB_PROP_ALBUM_SORTNAME_SORT_KEY,
    	RHYTHMDB_PROP_ALBUM_SORTNAME_FOLDED,

    	RHYTHMDB_PROP_COMMENT,
    	RHYTHMDB_PROP_ALBUM_ARTIST,
    	RHYTHMDB_PROP_ALBUM_ARTIST_SORT_KEY,
    	RHYTHMDB_PROP_ALBUM_ARTIST_FOLDED,
    	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME,
    	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_SORT_KEY,
    	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_FOLDED,
    	RHYTHMDB_PROP_BPM,

    	RHYTHMDB_PROP_COMPOSER,
    	RHYTHMDB_PROP_COMPOSER_SORT_KEY,
    	RHYTHMDB_PROP_COMPOSER_FOLDED,
    	RHYTHMDB_PROP_COMPOSER_SORTNAME,
    	RHYTHMDB_PROP_COMPOSER_SORTNAME_SORT_KEY,
    	RHYTHMDB_PROP_COMPOSER_SORTNAME_FOLDED,

    	RHYTHMDB_NUM_PROPERTIES
    } RhythmDBPropType;

`RHYTHMDB_PROP_TYPE` |
`RHYTHMDB_PROP_ENTRY_ID` |
`RHYTHMDB_PROP_TITLE` |
`RHYTHMDB_PROP_GENRE` |
`RHYTHMDB_PROP_ARTIST` |
`RHYTHMDB_PROP_ALBUM` |
`RHYTHMDB_PROP_TRACK_NUMBER` |
`RHYTHMDB_PROP_DISC_NUMBER` |
`RHYTHMDB_PROP_DURATION` |
`RHYTHMDB_PROP_FILE_SIZE` |
`RHYTHMDB_PROP_LOCATION` |
`RHYTHMDB_PROP_MOUNTPOINT` |
`RHYTHMDB_PROP_MTIME` |
`RHYTHMDB_PROP_FIRST_SEEN` |
`RHYTHMDB_PROP_LAST_SEEN` |
`RHYTHMDB_PROP_RATING` |
`RHYTHMDB_PROP_PLAY_COUNT` |
`RHYTHMDB_PROP_LAST_PLAYED` |
`RHYTHMDB_PROP_BITRATE` |
`RHYTHMDB_PROP_DATE` |
`RHYTHMDB_PROP_TRACK_GAIN` |
`RHYTHMDB_PROP_TRACK_PEAK` |
`RHYTHMDB_PROP_ALBUM_GAIN` |
`RHYTHMDB_PROP_ALBUM_PEAK` |
`RHYTHMDB_PROP_MEDIA_TYPE` |
`RHYTHMDB_PROP_TITLE_SORT_KEY` |
`RHYTHMDB_PROP_GENRE_SORT_KEY` |
`RHYTHMDB_PROP_ARTIST_SORT_KEY` |
`RHYTHMDB_PROP_ALBUM_SORT_KEY` |
`RHYTHMDB_PROP_TITLE_FOLDED` |
`RHYTHMDB_PROP_GENRE_FOLDED` |
`RHYTHMDB_PROP_ARTIST_FOLDED` |
`RHYTHMDB_PROP_ALBUM_FOLDED` |
`RHYTHMDB_PROP_LAST_PLAYED_STR` |
`RHYTHMDB_PROP_HIDDEN` |
`RHYTHMDB_PROP_PLAYBACK_ERROR` |
`RHYTHMDB_PROP_FIRST_SEEN_STR` |
`RHYTHMDB_PROP_LAST_SEEN_STR` |
`RHYTHMDB_PROP_SEARCH_MATCH` |
`RHYTHMDB_PROP_YEAR` |
`RHYTHMDB_PROP_KEYWORD` |
`RHYTHMDB_PROP_STATUS` |
`RHYTHMDB_PROP_DESCRIPTION` |
`RHYTHMDB_PROP_SUBTITLE` |
`RHYTHMDB_PROP_SUMMARY` |
`RHYTHMDB_PROP_LANG` |
`RHYTHMDB_PROP_COPYRIGHT` |
`RHYTHMDB_PROP_IMAGE` |
`RHYTHMDB_PROP_POST_TIME` |
`RHYTHMDB_PROP_MUSICBRAINZ_TRACKID` |
`RHYTHMDB_PROP_MUSICBRAINZ_ARTISTID` |
`RHYTHMDB_PROP_MUSICBRAINZ_ALBUMID` |
`RHYTHMDB_PROP_MUSICBRAINZ_ALBUMARTISTID` |
`RHYTHMDB_PROP_ARTIST_SORTNAME` |
`RHYTHMDB_PROP_ALBUM_SORTNAME` |
`RHYTHMDB_PROP_ARTIST_SORTNAME_SORT_KEY` |
`RHYTHMDB_PROP_ARTIST_SORTNAME_FOLDED` |
`RHYTHMDB_PROP_ALBUM_SORTNAME_SORT_KEY` |
`RHYTHMDB_PROP_ALBUM_SORTNAME_FOLDED` |
`RHYTHMDB_PROP_COMMENT` |
`RHYTHMDB_PROP_ALBUM_ARTIST` |
`RHYTHMDB_PROP_ALBUM_ARTIST_SORT_KEY` |
`RHYTHMDB_PROP_ALBUM_ARTIST_FOLDED` |
`RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME` |
`RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_SORT_KEY` |
`RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_FOLDED` |
`RHYTHMDB_PROP_BPM` |
`RHYTHMDB_PROP_COMPOSER` |
`RHYTHMDB_PROP_COMPOSER_SORT_KEY` |
`RHYTHMDB_PROP_COMPOSER_FOLDED` |
`RHYTHMDB_PROP_COMPOSER_SORTNAME` |
`RHYTHMDB_PROP_COMPOSER_SORTNAME_SORT_KEY` |
`RHYTHMDB_PROP_COMPOSER_SORTNAME_FOLDED` |
`RHYTHMDB_NUM_PROPERTIES` |

### RHYTHMDB_PROP_STREAM_SONG_TITLE

    #define RHYTHMDB_PROP_STREAM_SONG_TITLE		"rb:stream-song-title"

### RHYTHMDB_PROP_STREAM_SONG_ARTIST

    #define RHYTHMDB_PROP_STREAM_SONG_ARTIST "rb:stream-song-artist"

### RHYTHMDB_PROP_STREAM_SONG_ALBUM

    #define RHYTHMDB_PROP_STREAM_SONG_ALBUM		"rb:stream-song-album"

### RHYTHMDB_PROP_COVER_ART

    #define RHYTHMDB_PROP_COVER_ART			"rb:coverArt"

### RHYTHMDB_PROP_COVER_ART_URI

    #define RHYTHMDB_PROP_COVER_ART_URI		"rb:coverArt-uri"

### RhythmDBQueryData

    typedef struct {
    	guint type;
    	guint propid;
    	GValue *val;
    	RhythmDBQuery *subquery;
    } RhythmDBQueryData;

### RhythmDBEntryChange

    typedef struct {
    	RhythmDBPropType prop;
    	GValue old;
    	GValue new;
    } RhythmDBEntryChange;

### rhythmdb_entry_get_string ()

    const char *        rhythmdb_entry_get_string           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of a string property of entry.

`entry` : | a RhythmDBEntry
`propid` : | the RhythmDBPropType to return
Returns : | property value, must not be freed

### rhythmdb_entry_get_refstring ()

    RBRefString *       rhythmdb_entry_get_refstring        (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns an RBRefString containing a string property of `entry`.

`entry` : | a RhythmDBEntry
`propid` : | the property to return
Returns : | a RBRefString, must be unreffed by caller.

### rhythmdb_entry_dup_string ()

    char *              rhythmdb_entry_dup_string           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

### rhythmdb_entry_get_boolean ()

    gboolean            rhythmdb_entry_get_boolean          (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of a boolean property of `entry`.

`entry` : | a RhythmDBEntry
`propid` : | property to return
Returns : | property value

### rhythmdb_entry_get_uint64 ()

    guint64             rhythmdb_entry_get_uint64           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of a 64bit unsigned integer property.

`entry` : | a RhythmDBEntry
`propid` : | property to return
Returns : | property value

### rhythmdb_entry_get_ulong ()

    gulong              rhythmdb_entry_get_ulong            (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of an unsigned long integer property of `entry`.

`entry` : | a RhythmDBEntry
`propid` : | property to return
Returns : | property value

### rhythmdb_entry_get_double ()

    double              rhythmdb_entry_get_double           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of a double-precision floating point property of `value`.

`entry` : | a RhythmDBEntry
`propid` : | the property to return
Returns : | property value

### rhythmdb_entry_get_object ()

    GObject *           rhythmdb_entry_get_object           (RhythmDBEntry *entry,
                                                             RhythmDBPropType propid);

Returns the value of an object property of `entry`.

`entry` : | a RhythmDBEntry
`propid` : | the property to return
Returns : | property value. [transfer none]

### rhythmdb_entry_get_entry_type ()

    RhythmDBEntryType * rhythmdb_entry_get_entry_type       (RhythmDBEntry *entry);

Returns the RhythmDBEntryType for `entry`. This is used to access entry type properties, to check that entries are of the same type, and to call entry type methods.

`entry` : | a RhythmDBEntry
Returns : | the RhythmDBEntryType for `entry`. [transfer none]

### enum RhythmDBError

    typedef enum {
    	RHYTHMDB_ERROR_ACCESS_FAILED,
    } RhythmDBError;

`RHYTHMDB_ERROR_ACCESS_FAILED` |

### RHYTHMDB_ERROR

    #define RHYTHMDB_ERROR (rhythmdb_error_quark ())

### rhythmdb_error_quark ()

    GQuark              rhythmdb_error_quark                (void);

Returns the GQuark used for RhythmDBError information

Returns : | error quark

### struct RhythmDB

    struct RhythmDB;

### struct RhythmDBClass

    struct RhythmDBClass {
    	GObjectClass parent;

    	/* signals */
    	void (*entry_added)		(RhythmDB *db, RhythmDBEntry *entry);
    	void (*entry_changed) (RhythmDB *db, RhythmDBEntry *entry, GArray *changes); /* array of RhythmDBEntryChanges */
    	void (*entry_deleted) (RhythmDB *db, RhythmDBEntry *entry);
    	void (*entry_keyword_added) (RhythmDB *db, RhythmDBEntry *entry, RBRefString *keyword);
    	void (*entry_keyword_removed)(RhythmDB *db, RhythmDBEntry *entry, RBRefString *keyword);
    	GValue *(*entry_extra_metadata_request) (RhythmDB *db, RhythmDBEntry *entry);
    	void    (*entry_extra_metadata_gather) (RhythmDB *db, RhythmDBEntry *entry, RBStringValueMap *data);
    	void (*entry_extra_metadata_notify) (RhythmDB *db, RhythmDBEntry *entry, const char *field, GValue *metadata);
    	void (*load_complete) (RhythmDB *db);
    	void (*save_complete) (RhythmDB *db);
    	void (*load_error)		(RhythmDB *db, const char *uri, const char *msg);
    	void (*save_error)		(RhythmDB *db, const char *uri, const GError *error);
    	void (*read_only)		(RhythmDB *db, gboolean readonly);

    	/* virtual methods */

    	gboolean (*impl_load)		(RhythmDB *db, GCancellable *cancel, GError **error);
    	void		(*impl_save)		(RhythmDB *db);

    	void		(*impl_entry_new) (RhythmDB *db, RhythmDBEntry *entry);

    	gboolean (*impl_entry_set) (RhythmDB *db, RhythmDBEntry *entry,
    	                                 guint propid, const GValue *value);

    	void		(*impl_entry_get) (RhythmDB *db, RhythmDBEntry *entry,
    						 guint propid, GValue *value);

    	void		(*impl_entry_delete) (RhythmDB *db, RhythmDBEntry *entry);

    	void            (*impl_entry_delete_by_type) (RhythmDB *db, RhythmDBEntryType *type);

    	RhythmDBEntry * (*impl_lookup_by_location)(RhythmDB *db, RBRefString *uri);

    	RhythmDBEntry * (*impl_lookup_by_id)    (RhythmDB *db, gint id);

    	gboolean 	(*impl_evaluate_query) (RhythmDB *db, RhythmDBQuery *query, RhythmDBEntry *entry);

    	void		(*impl_entry_foreach) (RhythmDB *db, GFunc func, gpointer data);

    	gint64		(*impl_entry_count) (RhythmDB *db);

    	void		(*impl_entry_foreach_by_type) (RhythmDB *db, RhythmDBEntryType *type, GFunc func, gpointer data);

    	gint64		(*impl_entry_count_by_type) (RhythmDB *db, RhythmDBEntryType *type);

    	void		(*impl_do_full_query) (RhythmDB *db, RhythmDBQuery *query,
    						 RhythmDBQueryResults *results,
    						 gboolean *cancel);

    	void		(*impl_entry_type_registered) (RhythmDB *db,
    						       RhythmDBEntryType *type);

    	gboolean (*impl_entry_keyword_add) (RhythmDB *db,
    							 RhythmDBEntry *entry,
    							 RBRefString *keyword);
    	gboolean (*impl_entry_keyword_remove) (RhythmDB *db,
    							 RhythmDBEntry *entry,
    							 RBRefString *keyword);
    	gboolean (*impl_entry_keyword_has) (RhythmDB *db,
    							 RhythmDBEntry *entry,
    							 RBRefString *keyword);
    	GList*		(*impl_entry_keywords_get) (RhythmDB *db,
    							 RhythmDBEntry *entry);
    };

### rhythmdb_get_type ()

    GType               rhythmdb_get_type                   (void);

### rhythmdb_shutdown ()

    void                rhythmdb_shutdown                   (RhythmDB *db);

Ceases all RhythmDB operations, including stopping all directory monitoring, and removing all actions and events currently queued.

`db` : | the RhythmDB

### rhythmdb_load ()

    void                rhythmdb_load                       (RhythmDB *db);

Load the database from disk.

`db` : | a RhythmDB.

### rhythmdb_save ()

    void                rhythmdb_save                       (RhythmDB *db);

Save the database to disk, not returning until it has been saved.

`db` : | a RhythmDB.

### rhythmdb_save_async ()

    void                rhythmdb_save_async                 (RhythmDB *db);

Save the database to disk, asynchronously.

`db` : | a RhythmDB.

### rhythmdb_start_action_thread ()

    void                rhythmdb_start_action_thread        (RhythmDB *db);

Starts the RhythmDB processing thread. Needs to be called during startup.

`db` : | the RhythmDB

### rhythmdb_commit ()

    void                rhythmdb_commit                     (RhythmDB *db);

Apply all database changes, and send notification of changes and new entries. This needs to be called after any changes have been made, such as a group of `rhythmdb_entry_set()` calls, or a new entry has been added.

`db` : | a RhythmDB.

### rhythmdb_entry_new ()

    RhythmDBEntry *     rhythmdb_entry_new                  (RhythmDB *db,
                                                             RhythmDBEntryType *type,
                                                             const char *uri);

Creates a new entry of type `type` and location `uri`, and inserts it into the database. You must call `rhythmdb_commit()` at some point after invoking this function.

This may return NULL if entry creation fails. This can occur if there is already an entry with the given uri.

`db` : | a RhythmDB.
`type` : | type of entry to create
`uri` : | the location of the entry, this be unique amongst all entries.
Returns : | the newly created RhythmDBEntry

### rhythmdb_entry_example_new ()

    RhythmDBEntry *     rhythmdb_entry_example_new          (RhythmDB *db,
                                                             RhythmDBEntryType *type,
                                                             const char *uri);

Creates a new sample entry of type `type` and location `uri`, it does not insert it into the database. This is indended for use as a example entry.

This may return NULL if entry creation fails.

`db` : | a RhythmDB.
`type` : | type of entry to create
`uri` : | the location of the entry, this be unique amongst all entries.
Returns : | the newly created RhythmDBEntry

### rhythmdb_add_uri ()

    void                rhythmdb_add_uri                    (RhythmDB *db,
                                                             const char *uri);

Adds the file(s) pointed to by `uri` to the database, as entries of type RHYTHMDB_ENTRY_TYPE_SONG. If the URI is that of a file, it will be added. If the URI is that of a directory, everything under it will be added recursively.

`db` : | a RhythmDB.
`uri` : | the URI to add an entry/entries for

### rhythmdb_add_uri_with_types ()

    void                rhythmdb_add_uri_with_types         (RhythmDB *db,
                                                             const char *uri,
                                                             RhythmDBEntryType *type,
                                                             RhythmDBEntryType *ignore_type,
                                                             RhythmDBEntryType *error_type);

Adds the file(s) pointed to by `uri` to the database, as entries of the specified type. If the URI points to a file, it will be added. The the URI identifies a directory, everything under it will be added recursively.

`db` : | a RhythmDB.
`uri` : | the URI to add
`type` : | the RhythmDBEntryType to use for new entries
`ignore_type` : | the RhythmDBEntryType to use for ignored files
`error_type` : | the RhythmDBEntryType to use for import errors

### rhythmdb_entry_get ()

    void                rhythmdb_entry_get                  (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RhythmDBPropType propid,
                                                             GValue *val);

Gets a property of an entry, storing it in the given GValue.

`db` : | the RhythmDB
`entry` : | a RhythmDBEntry.
`propid` : | the id of the property to get.
`val` : | return location for the property value.

### rhythmdb_entry_set ()

    void                rhythmdb_entry_set                  (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             guint propid,
                                                             const GValue *value);

This function can be called by any code which wishes to change a song property and send a notification. It may be called when the database is read-only; in this case the change will be queued for an unspecified time in the future. The implication of this is that `rhythmdb_entry_get()` may not reflect the changes immediately. However, if this property is exposed in the user interface, you should still make the change in the widget. Then when the database returns to a writable state, your change will take effect in the database too, and a notification will be sent at that point.

Note that you must call `rhythmdb_commit()` at some point after invoking this function, and that even after the commit, your change may not have taken effect.

`db` : | # a RhythmDB.
`entry` : | a RhythmDBEntry.
`propid` : | the id of the property to set.
`value` : | the property value.

### rhythmdb_entry_is_lossless ()

    gboolean            rhythmdb_entry_is_lossless          (RhythmDBEntry *entry);

Checks if `entry` represents a file that is losslessly encoded. An entry is considered lossless if it has no bitrate value and its media type is "audio/x-flac". Other lossless encoding types may be added in the future.

`entry` : | a RhythmDBEntry
Returns : | `TRUE` if `entry` is lossless

### rhythmdb_entry_get_type_data ()

    gpointer            rhythmdb_entry_get_type_data        (RhythmDBEntry *entry,
                                                             guint expected_size);

Retrieves a pointer to the entry's type-specific data, checking that the size of the data structure matches what is expected. Callers should use the RHYTHMDB_ENTRY_GET_TYPE_DATA macro for a slightly more friendly interface to this functionality.

`entry` : | a RhythmDBEntry
`expected_size` : | expected size of the type-specific data.
Returns : | type-specific data pointer. [transfer none]

### RHYTHMDB_ENTRY_GET_TYPE_DATA()

    #define		RHYTHMDB_ENTRY_GET_TYPE_DATA(e,t) ((t*)rhythmdb_entry_get_type_data((e),sizeof(t)))

### rhythmdb_entry_delete ()

    void                rhythmdb_entry_delete               (RhythmDB *db,
                                                             RhythmDBEntry *entry);

Delete entry `entry` from the database, sending notification of its deletion. This is usually used by sources where entries can disappear randomly, such as a network source.

`db` : | a RhythmDB.
`entry` : | a RhythmDBEntry.

### rhythmdb_entry_delete_by_type ()

    void                rhythmdb_entry_delete_by_type       (RhythmDB *db,
                                                             RhythmDBEntryType *type);

Delete all entries from the database of the given type. This is usually used by non-permanent sources when they disappear, such as removable media being removed, or a network share becoming unavailable.

`db` : | a RhythmDB.
`type` : | type of entried to delete.

### rhythmdb_entry_move_to_trash ()

    void                rhythmdb_entry_move_to_trash        (RhythmDB *db,
                                                             RhythmDBEntry *entry);

Trashes the file represented by entry. If possible, the file is moved to the user's trash directory and the entry is set to hidden, otherwise the error will be stored as the playback error for the entry.

`db` : | the RhythmDB
`entry` : | RhythmDBEntry to trash

### rhythmdb_entry_lookup_by_location ()

    RhythmDBEntry *     rhythmdb_entry_lookup_by_location   (RhythmDB *db,
                                                             const char *uri);

Looks up the entry with location `uri`.

`db` : | a RhythmDB.
`uri` : | the URI of the entry to lookup.
Returns : | the entry with location `uri`, or NULL if no such entry exists.

### rhythmdb_entry_lookup_by_id ()

    RhythmDBEntry *     rhythmdb_entry_lookup_by_id         (RhythmDB *db,
                                                             gint id);

Looks up the entry with id `id`.

`db` : | a RhythmDB.
`id` : | entry ID
Returns : | the entry with id `id`, or NULL if no such entry exists.

### rhythmdb_entry_lookup_from_string ()

    RhythmDBEntry *     rhythmdb_entry_lookup_from_string   (RhythmDB *db,
                                                             const char *str,
                                                             gboolean is_id);

Locates an entry using a string containing either an entry ID or a location.

`db` : | a RhythmDB.
`str` : | string
`is_id` : | whether the string is an entry ID or a location.
Returns : | the entry matching the string, or NULL if no such entry exists.

### rhythmdb_evaluate_query ()

    gboolean            rhythmdb_evaluate_query             (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBEntry *entry);

Evaluates the given entry against the given query.

`db` : | a RhythmDB.
`query` : | a query.
`entry` : | a `RhythmDBEntry`.
Returns : | whether the given entry matches the criteria of the given query.

### rhythmdb_entry_foreach ()

    void                rhythmdb_entry_foreach              (RhythmDB *db,
                                                             GFunc func,
                                                             gpointer data);

Calls the given function for each of the entries in the database.

`db` : | a RhythmDB.
`func` : | the function to call with each entry. [scope call]
`data` : | user data to pass to the function.

### rhythmdb_entry_count ()

    gint64              rhythmdb_entry_count                (RhythmDB *db);

Returns the number of entries in the database.

`db` : | a RhythmDB.
Returns : | number of entries

### rhythmdb_entry_foreach_by_type ()

    void                rhythmdb_entry_foreach_by_type      (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type,
                                                             GFunc func,
                                                             gpointer data);

Calls the given function for each of the entries in the database of a given type.

`db` : | a RhythmDB.
`entry_type` : | the type of entry to retrieve
`func` : | the function to call with each entry. [scope call]
`data` : | user data to pass to the function.

### rhythmdb_entry_count_by_type ()

    gint64              rhythmdb_entry_count_by_type        (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type);

Returns the number of entries in the database of a particular type.

`db` : | a RhythmDB.
`entry_type` : | a RhythmDBEntryType.
Returns : | entry count

### rhythmdb_entry_keyword_add ()

    gboolean            rhythmdb_entry_keyword_add          (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);

Adds a keyword to an entry.

`db` : | the RhythmDB
`entry` : | a RhythmDBEntry.
`keyword` : | the keyword to add.
Returns : | whether the keyword was already on the entry

### rhythmdb_entry_keyword_remove ()

    gboolean            rhythmdb_entry_keyword_remove       (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);

Removed a keyword from an entry.

`db` : | the RhythmDB
`entry` : | a RhythmDBEntry.
`keyword` : | the keyword to remove.
Returns : | whether the keyword had previously been added to the entry.

### rhythmdb_entry_keyword_has ()

    gboolean            rhythmdb_entry_keyword_has          (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBRefString *keyword);

Checks whether a keyword is has been added to an entry.

`db` : | the RhythmDB
`entry` : | a RhythmDBEntry.
`keyword` : | the keyword to check for.
Returns : | whether the keyword had been added to the entry.

### rhythmdb_entry_write_metadata_changes ()

    void                rhythmdb_entry_write_metadata_changes
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             GSList *changes,
                                                             GError **error);

This can be called from a RhythmDBEntryType sync_metadata function when the appropriate action is to write the metadata changes to the file at the entry's location.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry to update
`changes` : | a list of changes to write. [element-type RB.RhythmDBEntryChange]
`error` : | returns error information

### rhythmdb_entry_create_ext_db_key ()

    RBExtDBKey *        rhythmdb_entry_create_ext_db_key    (RhythmDBEntry *entry,
                                                             RhythmDBPropType prop);

Creates a RBExtDBKey for finding external metadata for a given property. This is mostly useful for finding album or track related data.

`entry` : | a RhythmDBEntry
`prop` : | the primary RhythmDBPropType for metadata lookups
Returns : | the new RBExtDBKey

### rhythmdb_entry_matches_ext_db_key ()

    gboolean            rhythmdb_entry_matches_ext_db_key   (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             RBExtDBKey *key);

Checks whether `key` matches `entry`.

`db` : | RhythmDB instance
`entry` : | a RhythmDBEntry
`key` : | a RBExtDBKey
Returns : | `TRUE` if the key matches the entry

### rhythmdb_do_full_query ()

    void                rhythmdb_do_full_query              (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             ...);

Synchronously evaluates `query`, feeding results to `results` in chunks. Does not return until the query is complete. This can only be called from the main thread.

FIXME: example

`db` : | the RhythmDB
`results` : | a RhythmDBQueryResults instance to feed results to

### rhythmdb_do_full_query_parsed ()

    void                rhythmdb_do_full_query_parsed       (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             RhythmDBQuery *query);

Synchronously evaluates the parsed query `query`, feeding results to `results` in chunks. Does not return until the query is complete.

`db` : | the RhythmDB
`results` : | a RhythmDBQueryResults instance to feed results to
`query` : | a parsed query

### rhythmdb_do_full_query_async ()

    void                rhythmdb_do_full_query_async        (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             ...);

Asynchronously runs a query specified in the function arguments across the database, feeding matching entries to `results` in chunks. This can only be called from the main thread.

Since `results` is always a `RhythmDBQueryModel`, use the RhythmDBQueryModel::complete signal to identify when the query is complete.

FIXME: example

`db` : | the RhythmDB
`results` : | a RhythmDBQueryResults to feed results to

### rhythmdb_do_full_query_async_parsed ()

    void                rhythmdb_do_full_query_async_parsed (RhythmDB *db,
                                                             RhythmDBQueryResults *results,
                                                             RhythmDBQuery *query);

Asynchronously runs a parsed query across the database, feeding matching entries to `results` in chunks. This can only be called from the main thread.

Since `results` is always a `RhythmDBQueryModel`, use the RhythmDBQueryModel::complete signal to identify when the query is complete.

`db` : | the RhythmDB
`results` : | a RhythmDBQueryResults instance to feed results to
`query` : | the query to run

### rhythmdb_query_parse ()

    RhythmDBQuery *     rhythmdb_query_parse                (RhythmDB *db,
                                                             ...);

Creates a query from a list of criteria.

Most criteria consists of an operator (RhythmDBQueryType), a property (RhythmDBPropType) and the data to compare with. An entry matches a criteria if the operator returns true with the value of the entries property as the first argument, and the given data as the second argument.

Three types criteria are special. Passing RHYTHMDB_QUERY_END indicates the end of the list of criteria, and must be the last passes parameter.

The second special criteria is a subquery which is defined by passing RHYTHMDB_QUERY_SUBQUERY, followed by a query (GPtrArray). An entry will match a subquery criteria if it matches all criteria in the subquery.

The third special criteria is a disjunction which is defined by passing RHYTHMDB_QUERY_DISJUNCTION, which will make an entry match the query if it matches the criteria before the disjunction, the criteria after the disjunction, or both.

Example: rhythmdb_query_parse (db, RHYTHMDB_QUERY_SUBQUERY, subquery, RHYTHMDB_QUERY_DISJUNCTION RHYTHMDB_QUERY_PROP_LIKE, RHYTHMDB_PROP_TITLE, "cat", RHYTHMDB_QUERY_DISJUNCTION RHYTHMDB_QUERY_PROP_GREATER, RHYTHMDB_PROP_RATING, 2.5, RHYTHMDB_QUERY_PROP_LESS, RHYTHMDB_PROP_PLAY_COUNT, 10, RHYTHMDB_QUERY_END);

will create a query that matches entries: a) that match the query "subquery", or b) that have "cat" in their title, or c) have a rating of at least 2.5, and a play count of at most 10

`db` : | a RhythmDB instance
Returns : | a the newly created query. It must be freed with `rhythmdb_query_free()`. [transfer full]

### rhythmdb_query_append ()

    void                rhythmdb_query_append               (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             ...);

Appends new criteria to the query `query`.

The list of criteria must be in the same format as for rhythmdb_query_parse, and ended by RHYTHMDB_QUERY_END.

`db` : | a RhythmDB instance
`query` : | a query.

### rhythmdb_query_append_params ()

    void                rhythmdb_query_append_params        (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBQueryType type,
                                                             RhythmDBPropType prop,
                                                             const GValue *value);

Appends a new query term to `query`.

`db` : | the RhythmDB
`query` : | the query to append to
`type` : | query type
`prop` : | query property
`value` : | query value

### rhythmdb_query_append_prop_multiple ()

    void                rhythmdb_query_append_prop_multiple (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             RhythmDBPropType propid,
                                                             GList *items);

Appends a set of criteria to a query to match against any of the values listed in `items`.

`db` : | the RhythmDB
`query` : | the query to append to
`propid` : | property ID to match
`items` : | GList of values to match against. [element-type GObject.Value]

### rhythmdb_query_concatenate ()

    void                rhythmdb_query_concatenate          (RhythmDBQuery *query1,
                                                             RhythmDBQuery *query2);

Appends `query2` to `query1`.

`query1` : | query to append to
`query2` : | query to append

### rhythmdb_query_free ()

    void                rhythmdb_query_free                 (RhythmDBQuery *query);

Frees the query `query`

`query` : | a query.

### rhythmdb_query_copy ()

    RhythmDBQuery *     rhythmdb_query_copy                 (RhythmDBQuery *array);

Creates a copy of a query.

`array` : | the query to copy.
Returns : | a copy of the passed query. It must be freed with `rhythmdb_query_free()`. [transfer full]

### rhythmdb_query_preprocess ()

    void                rhythmdb_query_preprocess           (RhythmDB *db,
                                                             RhythmDBQuery *query);

Preprocesses a query to prepare it for execution. This has two main roles: to perform expensive data transformations once per query, rather than once per entry, and converting criteria to lower-level forms that are implemented by the database backend.

For RHYTHMDB_PROP_SEARCH_MATCH, this converts the search terms into an array of case-folded words.

When matching against case-folded properties such as RHYTHMDB_PROP_TITLE_FOLDED, this case-folds the query value.

When performing year-based criteria such as RHYTHMDB_QUERY_PROP_YEAR_LESS, it converts the year into the Julian date such that a simple numeric comparison will work.

`db` : | the RhythmDB
`query` : | query to preprocess

### rhythmdb_query_serialize ()

    void                rhythmdb_query_serialize            (RhythmDB *db,
                                                             RhythmDBQuery *query,
                                                             xmlNodePtr parent);

Converts `query` into XML form as a child of `parent`. It can be converted back into a query by passing `parent` to `rhythmdb_query_deserialize`.

`db` : | the RhythmDB
`query` : | query to serialize
`parent` : | XML node to attach the query to

### rhythmdb_query_deserialize ()

    RhythmDBQuery *     rhythmdb_query_deserialize          (RhythmDB *db,
                                                             xmlNodePtr parent);

Converts a serialized query back into a `GPtrArray` query.

`db` : | the RhythmDB
`parent` : | parent XML node of serialized query
Returns : | deserialized query. [transfer full]

### rhythmdb_query_to_string ()

    char *              rhythmdb_query_to_string            (RhythmDB *db,
                                                             RhythmDBQuery *query);

Returns a supposedly human-readable form of the query. This is only intended for debug usage.

`db` : | a RhythmDB instance
`query` : | a query.
Returns : | allocated string form of the query

### rhythmdb_query_is_time_relative ()

    gboolean            rhythmdb_query_is_time_relative     (RhythmDB *db,
                                                             RhythmDBQuery *query);

Checks if a query contains any time-relative criteria.

`db` : | the RhythmDB
`query` : | the query to check
Returns : | `TRUE` if time-relative criteria found

### rhythmdb_nice_elt_name_from_propid ()

    const xmlChar *     rhythmdb_nice_elt_name_from_propid  (RhythmDB *db,
                                                             RhythmDBPropType propid);

Returns a short non-translated name for the property propid. This name is suitable for use as an XML tag name, for example.

`db` : | the RhythmDB
`propid` : | property ID
Returns : | property ID name, must not be freed

### rhythmdb_propid_from_nice_elt_name ()

    int                 rhythmdb_propid_from_nice_elt_name  (RhythmDB *db,
                                                             const xmlChar *name);

Converts a property name returned by `rhythmdb_propid_from_nice_elt_name` back to a RhythmDBPropType. If the name does not match a property ID, -1 will be returned instead.

`db` : | the RhythmDB
`name` : | a property ID name
Returns : | a RhythmDBPropType, or -1

### rhythmdb_emit_entry_added ()

    void                rhythmdb_emit_entry_added           (RhythmDB *db,
                                                             RhythmDBEntry *entry);

### rhythmdb_emit_entry_deleted ()

    void                rhythmdb_emit_entry_deleted         (RhythmDB *db,
                                                             RhythmDBEntry *entry);

### rhythmdb_entry_request_extra_metadata ()

    GValue *            rhythmdb_entry_request_extra_metadata
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             const gchar *property_name);

Emits a request for extra metadata for the `entry`. The `property_name` argument is emitted as the ::detail part of the "entry_extra_metadata_request" signal. It should be a namespaced RDF predicate e.g. from Dublin Core, MusicBrainz, or internal to Rhythmbox (namespace "rb:"). Suitable predicates would be those that are expensive to acquire or only apply to a limited range of entries. Handlers capable of providing a particular predicate may ensure they only see appropriate requests by supplying an appropriate ::detail part when connecting to the signal. Upon a handler returning a non-`NULL` value, emission will be stopped and the value returned to the caller; if no handlers return a non-`NULL` value, the caller will receive `NULL`. Priority is determined by signal connection order, with `G_CONNECT_AFTER` providing a second, lower rank of priority. A handler returning a value should do so in a GValue allocated on the heap; the accumulator will take ownership. The caller should unset and free the GValue if non-`NULL` when finished with it.

`db` : | a RhythmDB
`entry` : | a RhythmDBEntry
`property_name` : | the metadata predicate
Returns : | an allocated, initialised, set GValue, or NULL

### rhythmdb_entry_gather_metadata ()

    RBStringValueMap *  rhythmdb_entry_gather_metadata      (RhythmDB *db,
                                                             RhythmDBEntry *entry);

Gathers all metadata for the `entry`. The returned GHashTable maps property names and extra metadata names (described under `rhythmdb_entry_request_extra_metadata`) to GValues. Anything wanting to provide extra metadata should connect to the "entry_extra_metadata_gather" signal.

`db` : | a RhythmDB
`entry` : | a RhythmDBEntry
Returns : | a RBStringValueMap containing metadata for the entry. This must be freed using g_object_unref. [transfer full]

### rhythmdb_emit_entry_extra_metadata_notify ()

    void                rhythmdb_emit_entry_extra_metadata_notify
                                                            (RhythmDB *db,
                                                             RhythmDBEntry *entry,
                                                             const gchar *property_name,
                                                             const GValue *metadata);

Emits a signal describing extra metadata for the `entry`. The `property_name` argument is emitted as the ::detail part of the "entry_extra_metadata_notify" signal and as the 'field' parameter. Handlers can ensure they only get metadata they are interested in by supplying an appropriate ::detail part when connecting to the signal. If handlers are interested in the metadata they should ref or copy the contents of `metadata` and unref or free it when they are finished with it.

`db` : | a RhythmDB
`entry` : | a RhythmDBEntry
`property_name` : | the metadata predicate
`metadata` : | a GValue

### rhythmdb_compute_status_normal ()

    char *              rhythmdb_compute_status_normal      (gint n_songs,
                                                             glong duration,
                                                             guint64 size,
                                                             const char *singular,
                                                             const char *plural);

Creates a string containing the "status" information about a list of tracks. The singular and plural strings must be used in a direct ngettext call elsewhere in order for them to be marked for translation correctly.

`n_songs` : | the number of tracks.
`duration` : | the total duration of the tracks.
`size` : | the total size of the tracks.
`singular` : | singular form of the format string to use for entries (eg "`d` song")
`plural` : | plural form of the format string to use for entries (eg "`d` songs")
Returns : | the string, which should be freed with g_free.

### rhythmdb_register_entry_type ()

    void                rhythmdb_register_entry_type        (RhythmDB *db,
                                                             RhythmDBEntryType *entry_type);

Registers a new entry type. An entry type must be registered before any entries can be created for it.

`db` : | the RhythmDB
`entry_type` : | the new entry type to register

### rhythmdb_entry_type_get_by_name ()

    RhythmDBEntryType * rhythmdb_entry_type_get_by_name     (RhythmDB *db,
                                                             const char *name);

Locates a RhythmDBEntryType by name. Returns NULL if no entry type is registered with the specified name.

`db` : | a RhythmDB
`name` : | name of the type to look for
Returns : | the RhythmDBEntryType. [transfer none]

### rhythmdb_get_property_type ()

    GType               rhythmdb_get_property_type          (RhythmDB *db,
                                                             guint property_id);

Returns the GType for the value of the property.

`db` : | the RhythmDB
`property_id` : | a property ID (RhythmDBPropType)
Returns : | property value type

### rhythmdb_entry_ref ()

    RhythmDBEntry *     rhythmdb_entry_ref                  (RhythmDBEntry *entry);

Increase the reference count of the entry.

`entry` : | a RhythmDBEntry.
Returns : | the entry

### rhythmdb_entry_unref ()

    void                rhythmdb_entry_unref                (RhythmDBEntry *entry);

Decrease the reference count of the entry, and destroys it if there are no references left.

`entry` : | a RhythmDBEntry.

### RhythmDBPrivate

    typedef struct _RhythmDBPrivate RhythmDBPrivate;

## Property Details

### The `"dry-run"` property

      "dry-run"                  gboolean              : Read / Write

If `TRUE`, no metadata changes will be written back to media fies.

Default value: FALSE

### The `"name"` property

      "name"                     gchar*                : Read / Write

Database name. Not sure whta this is used for.

Default value: NULL

### The `"no-update"` property

      "no-update"                gboolean              : Read / Write

If `TRUE`, the database will not be updated.

Default value: FALSE

## Signal Details

### The `"create-mount-op"` signal

    GMountOperation*    user_function                      (RhythmDB *db,
                                                            gpointer  user_data)      : Run Last

Emitted to request creation of a GMountOperation to use to mount a volume.

`db` : | the RhythmDB
`user_data` : | user data set when the signal handler was connected.
Returns : | a GMountOperation (usually actually a GtkMountOperation). [transfer full]

### The `"entry-added"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            gpointer       user_data)      : Run Last

Emitted when a new entry is added to the database.

`db` : | the RhythmDB
`entry` : | the newly added RhythmDBEntry
`user_data` : | user data set when the signal handler was connected.

### The `"entry-changed"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            GPtrArray     *changes,
                                                            gpointer       user_data)      : Run Last

Emitted when a database entry is modified. The `changes` list contains a structure for each entry property that has been modified.

`db` : | the RhythmDB
`entry` : | the changed RhythmDBEntry
`changes` : | a GPtrArray of RhythmDBEntryChange structures describing the changes. [element-type RB.RhythmDBEntryChange]
`user_data` : | user data set when the signal handler was connected.

### The `"entry-deleted"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            gpointer       user_data)      : Run Last

Emitted when an entry is deleted from the database.

`db` : | the RhythmDB
`entry` : | the deleted RhythmDBEntry
`user_data` : | user data set when the signal handler was connected.

### The `"entry-extra-metadata-gather"` signal

    void                user_function                      (RhythmDB         *db,
                                                            RhythmDBEntry    *entry,
                                                            RBStringValueMap *data,
                                                            gpointer          user_data)      : Run Last

Emitted to gather all available extra metadata for a database entry. Handlers for this signal should insert any metadata they can provide into the string-value map. Only immediately available metadata items should be returned. If one or more metadata items is not immediately available, the handler should not initiate an attempt to retrieve them.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry for which to gather metadata
`data` : | a RBStringValueMap to hold the gathered metadata
`user_data` : | user data set when the signal handler was connected.

### The `"entry-extra-metadata-notify"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            gchar         *field,
                                                            GValue        *metadata,
                                                            gpointer       user_data)      : Has Details

This signal is emitted when an extra metadata value is provided for a specific entry independantly of an extra metadata request.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry for which extra metadata has been supplied
`field` : | the extra metadata field being supplied
`metadata` : | the extra metadata value
`user_data` : | user data set when the signal handler was connected.

### The `"entry-extra-metadata-request"` signal

    GValue*             user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            gpointer       user_data)      : Has Details

This signal is emitted to allow extra (transient) metadata to be supplied for the given entry. The detail of the signal invocation describes the specific metadata value being requested. If the object handling the signal can provide the requested item, but it isn't immediately available, it can initiate an attempt to retrieve it. If successful, it would call `rhythmdb_emit_entry_extra_metadata_notify` when the metadata is available.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry for which extra metadata is being requested
`user_data` : | user data set when the signal handler was connected.
Returns : | the extra metadata value

### The `"entry-keyword-added"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            RBRefString   *keyword,
                                                            gpointer       user_data)      : Run Last

Emitted when a keyword is added to an entry.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry to which a keyword has been added
`keyword` : | the keyword that was added
`user_data` : | user data set when the signal handler was connected.

### The `"entry-keyword-removed"` signal

    void                user_function                      (RhythmDB      *db,
                                                            RhythmDBEntry *entry,
                                                            RBRefString   *keyword,
                                                            gpointer       user_data)      : Run Last

Emitted when a keyword is removed from an entry.

`db` : | the RhythmDB
`entry` : | the RhythmDBEntry from which a keyword has been removed
`keyword` : | the keyword that was removed
`user_data` : | user data set when the signal handler was connected.

### The `"load-complete"` signal

    void                user_function                      (RhythmDB *db,
                                                            gpointer  user_data)      : Run Last

Emitted when the database is fully loaded.

`db` : | the RhythmDB
`user_data` : | user data set when the signal handler was connected.

### The `"read-only"` signal

    void                user_function                      (RhythmDB *db,
                                                            gboolean  readonly,
                                                            gpointer  user_data)      : Run Last

Emitted when the database becomes temporarily read-only, or becomes writeable after being read-only.

`db` : | the RhythmDB
`readonly` : | `TRUE` if the database is read-only
`user_data` : | user data set when the signal handler was connected.

### The `"save-complete"` signal

    void                user_function                      (RhythmDB *db,
                                                            gpointer  user_data)      : Run Last

Emitted when the database has been saved.

`db` : | the RhythmDB
`user_data` : | user data set when the signal handler was connected.

### The `"save-error"` signal

    void                user_function                      (RhythmDB *db,
                                                            gchar    *uri,
                                                            gpointer  error,
                                                            gpointer  user_data)      : Run Last

Emitted when an error occurs while saving the database.

`db` : | the RhythmDB
`uri` : | URI of the database file
`error` : | the error that occurred
`user_data` : | user data set when the signal handler was connected.