### Class

# RB RhythmDB

#### Description [src]

    abstract class RB.RhythmDB : GObject.Object
    {
      RhythmDBPrivate* priv
    }

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

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

#### Ancestors

- GObject

#### Functions

###### rhythmdb_compute_status_normal

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.

###### rhythmdb_error_quark

Returns the `GQuark` used for `RhythmDBError` information.

###### rhythmdb_get_error_entry_type

Returns the `RhythmDBEntryType` for import errors.

###### rhythmdb_get_ignore_entry_type

Returns the `RhythmDBEntryType` for ignored files.

###### rhythmdb_get_song_entry_type

Returns the `RhythmDBEntryType` for normal songs.

###### rhythmdb_query_concatenate

Appends `query2` to `query1`.

###### rhythmdb_query_copy

Creates a copy of a query.

###### rhythmdb_query_free

Frees the query `query`.

#### Instance methods

###### rhythmdb_add_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.

###### rhythmdb_add_uri_with_types

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.

###### rhythmdb_commit

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.

###### rhythmdb_do_full_query

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.

###### rhythmdb_do_full_query_async

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.

###### rhythmdb_do_full_query_async_parsed

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

###### rhythmdb_do_full_query_parsed

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

###### rhythmdb_emit_entry_added

No description available.

###### rhythmdb_emit_entry_deleted

No description available.

###### rhythmdb_emit_entry_extra_metadata_notify

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.

###### rhythmdb_entry_count

Returns the number of entries in the database.

###### rhythmdb_entry_count_by_type

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

###### rhythmdb_entry_delete

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.

###### rhythmdb_entry_delete_by_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.

###### rhythmdb_entry_foreach

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

###### rhythmdb_entry_foreach_by_type

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

###### rhythmdb_entry_gather_metadata

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.

###### rhythmdb_entry_get

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

###### rhythmdb_entry_keyword_add

Adds a keyword to an entry.

###### rhythmdb_entry_keyword_has

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

###### rhythmdb_entry_keyword_remove

Removed a keyword from an entry.

###### rhythmdb_entry_keywords_get

Gets the list ofkeywords that have been added to an entry.

###### rhythmdb_entry_lookup_by_id

Looks up the entry with id `id`.

###### rhythmdb_entry_lookup_by_location

Looks up the entry with location `uri`.

###### rhythmdb_entry_lookup_from_string

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

###### rhythmdb_entry_matches_ext_db_key

Checks whether `key` matches `entry`.

###### rhythmdb_entry_move_to_trash

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.

###### rhythmdb_entry_request_extra_metadata

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.

###### rhythmdb_entry_set

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.

###### rhythmdb_entry_type_get_by_name

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

###### rhythmdb_entry_write_metadata_changes

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.

###### rhythmdb_evaluate_query

Evaluates the given entry against the given query.

###### rhythmdb_get_property_type

Returns the `GType` for the value of the property.

###### rhythmdb_load

Load the database from disk.

###### rhythmdb_nice_elt_name_from_propid

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

###### rhythmdb_propid_from_nice_elt_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.

###### rhythmdb_query_append

Appends new criteria to the query `query`.

###### rhythmdb_query_append_params

Appends a new query term to `query`.

###### rhythmdb_query_append_prop_multiple

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

###### rhythmdb_query_deserialize

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

###### rhythmdb_query_is_time_relative

Checks if a query contains any time-relative criteria.

###### rhythmdb_query_parse

Creates a query from a list of criteria.

###### rhythmdb_query_preprocess

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.

###### rhythmdb_query_serialize

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`.

###### rhythmdb_query_to_string

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

###### rhythmdb_register_entry_type

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

###### rhythmdb_save

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

###### rhythmdb_save_async

Save the database to disk, asynchronously.

###### rhythmdb_shutdown

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

###### rhythmdb_start_action_thread

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

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

###### RB.RhythmDB:dry-run

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

###### RB.RhythmDB:name

Database name. Not sure whta this is used for.

###### RB.RhythmDB:no-update

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

#### Signals

###### RB.RhythmDB::create-mount-op

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

###### RB.RhythmDB::entry-added

Emitted when a new entry is added to the database.

###### RB.RhythmDB::entry-changed

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

###### RB.RhythmDB::entry-deleted

Emitted when an entry is deleted from the database.

###### RB.RhythmDB::entry-extra-metadata-gather

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.

###### RB.RhythmDB::entry-extra-metadata-notify

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

###### RB.RhythmDB::entry-extra-metadata-request

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.

###### RB.RhythmDB::entry-keyword-added

Emitted when a keyword is added to an entry.

###### RB.RhythmDB::entry-keyword-removed

Emitted when a keyword is removed from an entry.

###### RB.RhythmDB::load-complete

Emitted when the database is fully loaded.

###### RB.RhythmDB::read-only

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

###### RB.RhythmDB::save-complete

Emitted when the database has been saved.

###### RB.RhythmDB::save-error

Emitted when an error occurs while saving the database.

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct RBRhythmDBClass {
      GObjectClass parent;
      void (* entry_added) (
        RhythmDB* db,
        RhythmDBEntry* entry
      );
      void (* entry_changed) (
        RhythmDB* db,
        RhythmDBEntry* entry,
        GArray* changes
      );
      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
      );
      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,
        RhythmDBEntryForeachFunc func,
        gpointer data
      );
      gint64 (* impl_entry_count) (
        RhythmDB* db
      );
      void (* impl_entry_foreach_by_type) (
        RhythmDB* db,
        RhythmDBEntryType* type,
        RhythmDBEntryForeachFunc 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
      );

    }

No description available.

###### Class members

`parent: GObjectClass`

  No description available.

`entry_added: void (* entry_added) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

`entry_changed: void (* entry_changed) ( RhythmDB* db, RhythmDBEntry* entry, GArray* changes )`

  No description available.

`entry_deleted: void (* entry_deleted) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

`entry_keyword_added: void (* entry_keyword_added) ( RhythmDB* db, RhythmDBEntry* entry, RBRefString* keyword )`

  No description available.

`entry_keyword_removed: void (* entry_keyword_removed) ( RhythmDB* db, RhythmDBEntry* entry, RBRefString* keyword )`

  No description available.

`entry_extra_metadata_request: GValue* (* entry_extra_metadata_request) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

`entry_extra_metadata_gather: void (* entry_extra_metadata_gather) ( RhythmDB* db, RhythmDBEntry* entry, RBStringValueMap* data )`

  No description available.

`entry_extra_metadata_notify: void (* entry_extra_metadata_notify) ( RhythmDB* db, RhythmDBEntry* entry, const char* field, GValue* metadata )`

  No description available.

`load_complete: void (* load_complete) ( RhythmDB* db )`

  No description available.

`save_complete: void (* save_complete) ( RhythmDB* db )`

  No description available.

`load_error: void (* load_error) ( RhythmDB* db, const char* uri, const char* msg )`

  No description available.

`save_error: void (* save_error) ( RhythmDB* db, const char* uri, const GError* error )`

  No description available.

`read_only: void (* read_only) ( RhythmDB* db, gboolean readonly )`

  No description available.

`impl_load: gboolean (* impl_load) ( RhythmDB* db, GCancellable* cancel, GError** error )`

  No description available.

`impl_save: void (* impl_save) ( RhythmDB* db )`

  No description available.

`impl_entry_new: void (* impl_entry_new) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

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

  No description available.

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

  No description available.

`impl_entry_delete: void (* impl_entry_delete) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

`impl_entry_delete_by_type: void (* impl_entry_delete_by_type) ( RhythmDB* db, RhythmDBEntryType* type )`

  No description available.

`impl_lookup_by_location: RhythmDBEntry* (* impl_lookup_by_location) ( RhythmDB* db, RBRefString* uri )`

  No description available.

`impl_lookup_by_id: RhythmDBEntry* (* impl_lookup_by_id) ( RhythmDB* db, gint id )`

  No description available.

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

  No description available.

`impl_entry_foreach: void (* impl_entry_foreach) ( RhythmDB* db, RhythmDBEntryForeachFunc func, gpointer data )`

  No description available.

`impl_entry_count: gint64 (* impl_entry_count) ( RhythmDB* db )`

  No description available.

`impl_entry_foreach_by_type: void (* impl_entry_foreach_by_type) ( RhythmDB* db, RhythmDBEntryType* type, RhythmDBEntryForeachFunc func, gpointer data )`

  No description available.

`impl_entry_count_by_type: gint64 (* impl_entry_count_by_type) ( RhythmDB* db, RhythmDBEntryType* type )`

  No description available.

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

  No description available.

`impl_entry_type_registered: void (* impl_entry_type_registered) ( RhythmDB* db, RhythmDBEntryType* type )`

  No description available.

`impl_entry_keyword_add: gboolean (* impl_entry_keyword_add) ( RhythmDB* db, RhythmDBEntry* entry, RBRefString* keyword )`

  No description available.

`impl_entry_keyword_remove: gboolean (* impl_entry_keyword_remove) ( RhythmDB* db, RhythmDBEntry* entry, RBRefString* keyword )`

  No description available.

`impl_entry_keyword_has: gboolean (* impl_entry_keyword_has) ( RhythmDB* db, RhythmDBEntry* entry, RBRefString* keyword )`

  No description available.

`impl_entry_keywords_get: GList* (* impl_entry_keywords_get) ( RhythmDB* db, RhythmDBEntry* entry )`

  No description available.

#### Virtual methods

###### RB.RhythmDBClass.entry_added

No description available.

###### RB.RhythmDBClass.entry_changed

No description available.

###### RB.RhythmDBClass.entry_deleted

No description available.

###### RB.RhythmDBClass.entry_extra_metadata_gather

No description available.

###### RB.RhythmDBClass.entry_extra_metadata_notify

No description available.

###### RB.RhythmDBClass.entry_extra_metadata_request

No description available.

###### RB.RhythmDBClass.entry_keyword_added

No description available.

###### RB.RhythmDBClass.entry_keyword_removed

No description available.

###### RB.RhythmDBClass.impl_do_full_query

No description available.

###### RB.RhythmDBClass.impl_entry_count

No description available.

###### RB.RhythmDBClass.impl_entry_count_by_type

No description available.

###### RB.RhythmDBClass.impl_entry_delete

No description available.

###### RB.RhythmDBClass.impl_entry_delete_by_type

No description available.

###### RB.RhythmDBClass.impl_entry_foreach

No description available.

###### RB.RhythmDBClass.impl_entry_foreach_by_type

No description available.

###### RB.RhythmDBClass.impl_entry_get

No description available.

###### RB.RhythmDBClass.impl_entry_keyword_add

No description available.

###### RB.RhythmDBClass.impl_entry_keyword_has

No description available.

###### RB.RhythmDBClass.impl_entry_keyword_remove

No description available.

###### RB.RhythmDBClass.impl_entry_keywords_get

No description available.

###### RB.RhythmDBClass.impl_entry_new

No description available.

###### RB.RhythmDBClass.impl_entry_set

No description available.

###### RB.RhythmDBClass.impl_entry_type_registered

No description available.

###### RB.RhythmDBClass.impl_evaluate_query

No description available.

###### RB.RhythmDBClass.impl_load

No description available.

###### RB.RhythmDBClass.impl_lookup_by_id

No description available.

###### RB.RhythmDBClass.impl_lookup_by_location

No description available.

###### RB.RhythmDBClass.impl_save

No description available.

###### RB.RhythmDBClass.load_complete

No description available.

###### RB.RhythmDBClass.load_error

No description available.

###### RB.RhythmDBClass.read_only

No description available.

###### RB.RhythmDBClass.save_complete

No description available.

###### RB.RhythmDBClass.save_error

No description available.