rhythmdb

rhythmdb

Synopsis

                    RhythmDB;
typedef             RhythmDBEntry;
void                (*RhythmDBEntryActionFunc)          (RhythmDBEntry *entry,
                                                         gpointer data);
char*               (*RhythmDBEntryStringFunc)          (RhythmDBEntry *entry,
                                                         gpointer data);
gboolean            (*RhythmDBEntryCanSyncFunc)         (RhythmDB *db,
                                                         RhythmDBEntry *entry,
                                                         gpointer data);
void                (*RhythmDBEntrySyncFunc)            (RhythmDB *db,
                                                         RhythmDBEntry *entry,
                                                         GError **error,
                                                         gpointer data);
enum                RhythmDBEntryCategory;
typedef             RhythmDBEntryType;
typedef             RhythmDBQuery;
#define             RHYTHMDB_ENTRY_TYPE_SONG
#define             RHYTHMDB_ENTRY_TYPE_PODCAST_POST
#define             RHYTHMDB_ENTRY_TYPE_PODCAST_FEED
#define             RHYTHMDB_ENTRY_TYPE_IMPORT_ERROR
#define             RHYTHMDB_ENTRY_TYPE_IGNORE
#define             RHYTHMDB_ENTRY_TYPE_INVALID
enum                RhythmDBQueryType;
enum                RhythmDBPropType;
#define             RHYTHMDB_PROP_STREAM_SONG_TITLE
#define             RHYTHMDB_PROP_STREAM_SONG_ARTIST
#define             RHYTHMDB_PROP_STREAM_SONG_ALBUM
                    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);
gpointer            rhythmdb_entry_get_pointer          (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);
RhythmDBEntryType   rhythmdb_entry_get_entry_type       (RhythmDBEntry *entry);
enum                RhythmDBError;
                    RhythmDBPrivate;
RhythmDB*           rhythmdb_new                        (const char *name);
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);
gboolean            rhythmdb_entry_is_editable          (RhythmDB *db,
                                                         RhythmDBEntry *entry);
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);
char*               rhythmdb_entry_get_playback_uri     (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_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 node);
RhythmDBQuery*      rhythmdb_query_deserialize          (RhythmDB *db,
                                                         xmlNodePtr node);
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);
gboolean            rhythmdb_is_busy                    (RhythmDB *db);
char*               rhythmdb_compute_status_normal      (gint n_songs,
                                                         glong duration,
                                                         guint64 size,
                                                         const char *singular,
                                                         const char *plural);
RhythmDBEntryType   rhythmdb_entry_register_type        (RhythmDB *db,
                                                         const char *name);
RhythmDBEntryType   rhythmdb_entry_type_get_by_name     (RhythmDB *db,
                                                         const char *name);
RhythmDBEntryType   rhythmdb_entry_song_get_type        (void);
RhythmDBEntryType   rhythmdb_entry_podcast_post_get_type
                                                        (void);
RhythmDBEntryType   rhythmdb_entry_podcast_feed_get_type
                                                        (void);
RhythmDBEntryType   rhythmdb_entry_import_error_get_type
                                                        (void);
RhythmDBEntryType   rhythmdb_entry_ignore_get_type      (void);
GType               rhythmdb_get_property_type          (RhythmDB *db,
                                                         guint property_id);
RhythmDBEntry*      rhythmdb_entry_ref                  (RhythmDBEntry *entry);
void                rhythmdb_entry_unref                (RhythmDBEntry *entry);

Object Hierarchy

  GObject
   +----RhythmDB

Properties

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

Signals

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

Description

Details

RhythmDB

typedef struct _RhythmDB RhythmDB;


RhythmDBEntry

typedef struct RhythmDBEntry_ RhythmDBEntry;


RhythmDBEntryActionFunc ()

void                (*RhythmDBEntryActionFunc)          (RhythmDBEntry *entry,
                                                         gpointer data);

entry :

data :


RhythmDBEntryStringFunc ()

char*               (*RhythmDBEntryStringFunc)          (RhythmDBEntry *entry,
                                                         gpointer data);

entry :

data :

Returns :


RhythmDBEntryCanSyncFunc ()

gboolean            (*RhythmDBEntryCanSyncFunc)         (RhythmDB *db,
                                                         RhythmDBEntry *entry,
                                                         gpointer data);

db :

entry :

data :

Returns :


RhythmDBEntrySyncFunc ()

void                (*RhythmDBEntrySyncFunc)            (RhythmDB *db,
                                                         RhythmDBEntry *entry,
                                                         GError **error,
                                                         gpointer data);

db :

entry :

error :

data :


enum RhythmDBEntryCategory

typedef enum {
	RHYTHMDB_ENTRY_NORMAL,		/* anything that doesn't match the other categories */
	RHYTHMDB_ENTRY_STREAM,		/* endless streams (eg shoutcast, last.fm) */
	RHYTHMDB_ENTRY_CONTAINER,	/* things that point to other entries (eg podcast feeds) */
	RHYTHMDB_ENTRY_VIRTUAL		/* import errors, ignored files */
} RhythmDBEntryCategory;


RhythmDBEntryType

typedef RhythmDBEntryType_ *RhythmDBEntryType;


RhythmDBQuery

typedef GPtrArray RhythmDBQuery;


RHYTHMDB_ENTRY_TYPE_SONG

#define RHYTHMDB_ENTRY_TYPE_SONG (rhythmdb_entry_song_get_type ())


RHYTHMDB_ENTRY_TYPE_PODCAST_POST

#define RHYTHMDB_ENTRY_TYPE_PODCAST_POST (rhythmdb_entry_podcast_post_get_type ())


RHYTHMDB_ENTRY_TYPE_PODCAST_FEED

#define RHYTHMDB_ENTRY_TYPE_PODCAST_FEED (rhythmdb_entry_podcast_feed_get_type ())


RHYTHMDB_ENTRY_TYPE_IMPORT_ERROR

#define RHYTHMDB_ENTRY_TYPE_IMPORT_ERROR (rhythmdb_entry_import_error_get_type ())


RHYTHMDB_ENTRY_TYPE_IGNORE

#define RHYTHMDB_ENTRY_TYPE_IGNORE (rhythmdb_entry_ignore_get_type ())


RHYTHMDB_ENTRY_TYPE_INVALID

#define RHYTHMDB_ENTRY_TYPE_INVALID (GINT_TO_POINTER (-1))


enum RhythmDBQueryType

typedef enum
{
	RHYTHMDB_QUERY_END,
	RHYTHMDB_QUERY_DISJUNCTION,
	RHYTHMDB_QUERY_SUBQUERY,

	/* general */
	RHYTHMDB_QUERY_PROP_EQUALS,

	/* 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_GREATER,
	RHYTHMDB_QUERY_PROP_YEAR_LESS,
} RhythmDBQueryType;


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,
	RHYTHMDB_PROP_TRACK_PEAK,
	RHYTHMDB_PROP_ALBUM_GAIN,
	RHYTHMDB_PROP_ALBUM_PEAK,
	RHYTHMDB_PROP_MIMETYPE,
	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_NUM_PROPERTIES
} RhythmDBPropType;


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"


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);

entry :

propid :

Returns :


rhythmdb_entry_get_refstring ()

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

entry :

propid :

Returns :


rhythmdb_entry_dup_string ()

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

entry :

propid :

Returns :


rhythmdb_entry_get_boolean ()

gboolean            rhythmdb_entry_get_boolean          (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);

entry :

propid :

Returns :


rhythmdb_entry_get_uint64 ()

guint64             rhythmdb_entry_get_uint64           (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);

entry :

propid :

Returns :


rhythmdb_entry_get_ulong ()

gulong              rhythmdb_entry_get_ulong            (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);

entry :

propid :

Returns :


rhythmdb_entry_get_double ()

double              rhythmdb_entry_get_double           (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);

entry :

propid :

Returns :


rhythmdb_entry_get_pointer ()

gpointer            rhythmdb_entry_get_pointer          (RhythmDBEntry *entry,
                                                         RhythmDBPropType propid);

entry :

propid :

Returns :


rhythmdb_entry_get_entry_type ()

RhythmDBEntryType   rhythmdb_entry_get_entry_type       (RhythmDBEntry *entry);

entry :

Returns :


enum RhythmDBError

typedef enum
{
	RHYTHMDB_ERROR_ACCESS_FAILED,
} RhythmDBError;


RhythmDBPrivate

typedef struct _RhythmDBPrivate RhythmDBPrivate;


rhythmdb_new ()

RhythmDB*           rhythmdb_new                        (const char *name);

name :

Returns :


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 :


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);

db :


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_is_editable ()

gboolean            rhythmdb_entry_is_editable          (RhythmDB *db,
                                                         RhythmDBEntry *entry);

This determines whether any changes to the entries metadata can be saved. Usually this is only true for entries backed by files, where tag-writing is enabled, and the appropriate tag-writing facilities are available.

db :

a RhythmDB.

entry :

a RhythmDBEntry.

Returns :

whether the entries metadata can be changed.

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 :

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_get_playback_uri ()

char*               rhythmdb_entry_get_playback_uri     (RhythmDBEntry *entry);

entry :

Returns :


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

RHYTHMDB_ENTRY_GET_TYPE_DATA()

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

e :

t :


rhythmdb_entry_delete ()

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

Delete entry entry from the database, sending notification of it's 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);

db :

entry :


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.

entry :

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.

data :

user data to pass to the function.

rhythmdb_entry_count ()

gint64              rhythmdb_entry_count                (RhythmDB *db);

db :

a RhythmDB.

Returns :

the number of entries in the database.

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

data :

user data to pass to the function.

rhythmdb_entry_count_by_type ()

gint64              rhythmdb_entry_count_by_type        (RhythmDB *db,
                                                         RhythmDBEntryType entry_type);

db :

a RhythmDB.

entry_type :

a RhythmDBEntryType.

Returns :

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

rhythmdb_entry_keyword_add ()

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

Adds a keyword to an entry.

db :

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 :

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 :

entry :

a RhythmDBEntry.

keyword :

the keyword to check for.

Returns :

whether the keyword had been added to the entry.

rhythmdb_do_full_query ()

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

db :

results :

... :


rhythmdb_do_full_query_parsed ()

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

db :

results :

query :


rhythmdb_do_full_query_async ()

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

db :

results :

... :


rhythmdb_do_full_query_async_parsed ()

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

db :

results :

query :


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()

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);

db :

query :

type :

prop :

value :


rhythmdb_query_append_prop_multiple ()

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

db :

query :

propid :

items :


rhythmdb_query_concatenate ()

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

query1 :

query2 :


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()

rhythmdb_query_preprocess ()

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

db :

query :


rhythmdb_query_serialize ()

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

db :

query :

node :


rhythmdb_query_deserialize ()

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

db :

node :

Returns :


rhythmdb_query_to_string ()

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

db :

a RhythmDB instance

query :

a query.

Returns :

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

rhythmdb_query_is_time_relative ()

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

db :

query :

Returns :


rhythmdb_nice_elt_name_from_propid ()

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

db :

propid :

Returns :


rhythmdb_propid_from_nice_elt_name ()

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

db :

name :

Returns :


rhythmdb_emit_entry_added ()

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

db :

entry :


rhythmdb_emit_entry_deleted ()

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

db :

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);

db :

entry :

Returns :


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_is_busy ()

gboolean            rhythmdb_is_busy                    (RhythmDB *db);

db :

a RhythmDB.

Returns :

whether the RhythmDB has events to process.

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_entry_register_type ()

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

Registers a new RhythmDBEntryType. This should be called to create a new entry type for non-permanent sources.

db :

a RhythmDB

name :

optional name for the entry type

Returns :

the new RhythmDBEntryType.

rhythmdb_entry_type_get_by_name ()

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

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

db :

a RhythmDB

name :

name of the type to look for

Returns :

the RhythmDBEntryType

rhythmdb_entry_song_get_type ()

RhythmDBEntryType   rhythmdb_entry_song_get_type        (void);

Returns :


rhythmdb_entry_podcast_post_get_type ()

RhythmDBEntryType   rhythmdb_entry_podcast_post_get_type
                                                        (void);

Returns :


rhythmdb_entry_podcast_feed_get_type ()

RhythmDBEntryType   rhythmdb_entry_podcast_feed_get_type
                                                        (void);

Returns :


rhythmdb_entry_import_error_get_type ()

RhythmDBEntryType   rhythmdb_entry_import_error_get_type
                                                        (void);

Returns :


rhythmdb_entry_ignore_get_type ()

RhythmDBEntryType   rhythmdb_entry_ignore_get_type      (void);

Returns :


rhythmdb_get_property_type ()

GType               rhythmdb_get_property_type          (RhythmDB *db,
                                                         guint property_id);

db :

property_id :

Returns :


rhythmdb_entry_ref ()

RhythmDBEntry*      rhythmdb_entry_ref                  (RhythmDBEntry *entry);

Increase the reference count of the entry.

entry :

a RhythmDBEntry.

Returns :


rhythmdb_entry_unref ()

void                rhythmdb_entry_unref                (RhythmDBEntry *entry);

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

entry :

a RhythmDBEntry.

Property Details

The "dry-run" property

  "dry-run"                  gboolean              : Read / Write

Whether or not changes should be saved.

Default value: FALSE


The "name" property

  "name"                     gchar*                : Read / Write

name.

Default value: NULL


The "no-update" property

  "no-update"                gboolean              : Read / Write

Whether or not to update the database.

Default value: FALSE

Signal Details

The "entry-added" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        gpointer       user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "entry-changed" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        gpointer       arg2,
                                                        gpointer       user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "entry-deleted" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        gpointer       user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "entry-extra-metadata-gather" signal

void                user_function                      (RhythmDB         *rhythmdb,
                                                        RhythmDBEntry    *arg1,
                                                        RBStringValueMap *arg2,
                                                        gpointer          user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "entry-extra-metadata-notify" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        gchar         *arg2,
                                                        GValue        *arg3,
                                                        gpointer       user_data)      : Run Last / Has Details

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

arg3 :

user_data :

user data set when the signal handler was connected.

The "entry-extra-metadata-request" signal

GValue*             user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        gpointer       user_data)      : Run Last / Has Details

rhythmdb :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

Returns :


The "entry-keyword-added" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        RBRefString   *arg2,
                                                        gpointer       user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "entry-keyword-removed" signal

void                user_function                      (RhythmDB      *rhythmdb,
                                                        RhythmDBEntry *arg1,
                                                        RBRefString   *arg2,
                                                        gpointer       user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.

The "load-complete" signal

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

rhythmdb :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "missing-plugins" signal

gboolean            user_function                      (RhythmDB *rhythmdb,
                                                        GStrv    *arg1,
                                                        GStrv    *arg2,
                                                        GClosure *arg3,
                                                        gpointer  user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

arg3 :

user_data :

user data set when the signal handler was connected.

Returns :


The "read-only" signal

void                user_function                      (RhythmDB *rhythmdb,
                                                        gboolean  arg1,
                                                        gpointer  user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "save-complete" signal

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

rhythmdb :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "save-error" signal

void                user_function                      (RhythmDB *rhythmdb,
                                                        gchar    *arg1,
                                                        gpointer  arg2,
                                                        gpointer  user_data)      : Run Last

rhythmdb :

the object which received the signal.

arg1 :

arg2 :

user_data :

user data set when the signal handler was connected.