rhythmdb/rhythmdb.h

   1  /*
   2  *  arch-tag: Header for RhythmDB - Rhythmbox backend queryable database
   3  *
   4  *  Copyright (C) 2003,2004 Colin Walters <walters@rhythmbox.org>
   5  *
   6  *  This program is free software; you can redistribute it and/or modify
   7  *  it under the terms of the GNU General Public License as published by
   8  *  the Free Software Foundation; either version 2 of the License, or
   9  *  (at your option) any later version.
  10  *
  11  *  This program is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  *  GNU General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU General Public License
  17  *  along with this program; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA.
  19  *
  20  */
  21
  22 #ifndef RHYTHMDB_H
  23 #define RHYTHMDB_H
  24
  25 #include <glib.h>
  26 #include <glib-object.h>
  27 #include <stdarg.h>
  28 #include <libxml/tree.h>
  29
  30 #include "config.h"
  31 #include "rhythmdb-query-results.h"
  32
  33 G_BEGIN_DECLS
  34
  35 struct RhythmDB_;
  36 typedef struct RhythmDB_ RhythmDB;
  37
  38 #define RHYTHMDB_TYPE      (rhythmdb_get_type ())
  39 #define RHYTHMDB(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE, RhythmDB))
  40 #define RHYTHMDB_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), RHYTHMDB_TYPE, RhythmDBClass))
  41 #define RHYTHMDB_IS(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE))
  42 #define RHYTHMDB_IS_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RHYTHMDB_TYPE))
  43 #define RHYTHMDB_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RHYTHMDB_TYPE, RhythmDBClass))
  44
  45 struct RhythmDBEntry_;
  46 typedef struct RhythmDBEntry_ RhythmDBEntry;
  47 GType rhythmdb_entry_get_type (void);
  48
  49 #define RHYTHMDB_TYPE_ENTRY      (rhythmdb_entry_get_type ())
  50 #define RHYTHMDB_ENTRY(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE_ENTRY, RhythmDBEntry))
  51 #define RHYTHMDB_IS_ENTRY(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE_ENTRY))
  52
  53
  54 typedef void (*RhythmDBEntryActionFunc) (RhythmDBEntry *entry, gpointer data);
  55 typedef char* (*RhythmDBEntryStringFunc) (RhythmDBEntry *entry, gpointer data);
  56 typedef gboolean (*RhythmDBEntryCanSyncFunc) (RhythmDB *db, RhythmDBEntry *entry, gpointer data);
  57 typedef void (*RhythmDBEntrySyncFunc) (RhythmDB *db, RhythmDBEntry *entry, GError **error, gpointer data);
  58
  59 typedef struct {
  60         char                            *name;
  61
  62         guint                           entry_type_data_size;
  63
  64         /* virtual functions here */
  65         RhythmDBEntryActionFunc         post_entry_create;
  66         gpointer                        post_entry_create_data;
  67         GDestroyNotify                  post_entry_create_destroy;
  68
  69         RhythmDBEntryActionFunc         pre_entry_destroy;
  70         gpointer                        pre_entry_destroy_data;
  71         GDestroyNotify                  pre_entry_destroy_destroy;
  72
  73         RhythmDBEntryStringFunc         get_playback_uri;
  74         gpointer                        get_playback_uri_data;
  75         GDestroyNotify                  get_playback_uri_destroy;
  76
  77         RhythmDBEntryCanSyncFunc        can_sync_metadata;
  78         gpointer                        can_sync_metadata_data;
  79         GDestroyNotify                  can_sync_metadata_destroy;
  80
  81         RhythmDBEntrySyncFunc           sync_metadata;
  82         gpointer                        sync_metadata_data;
  83         GDestroyNotify                  sync_metadata_destroy;
  84 } RhythmDBEntryType_;
  85 typedef RhythmDBEntryType_ *RhythmDBEntryType;
  86
  87 GType rhythmdb_entry_type_get_type (void);
  88 #define RHYTHMDB_TYPE_ENTRY_TYPE        (rhythmdb_entry_type_get_type ())
  89 #define RHYTHMDB_ENTRY_TYPE(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE_ENTRY_TYPE, RhythmDBEntryType_))
  90 #define RHYTHMDB_IS_ENTRY_TYPE(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE_ENTRY_TYPE))
  91
  92
  93
  94 typedef GPtrArray RhythmDBQuery;
  95 GType rhythmdb_query_get_type (void);
  96 #define RHYTHMDB_TYPE_QUERY     (rhythmdb_query_get_type ())
  97 #define RHYTHMDB_QUERY(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE_QUERY, RhythmDBQuery))
  98 #define RHYTHMDB_IS_QUERY(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE_QUERY))
  99
 100
 101 #define RHYTHMDB_ENTRY_TYPE_SONG (rhythmdb_entry_song_get_type ())
 102 #define RHYTHMDB_ENTRY_TYPE_IRADIO_STATION (rhythmdb_entry_iradio_get_type ())
 103 #define RHYTHMDB_ENTRY_TYPE_PODCAST_POST (rhythmdb_entry_podcast_post_get_type ())
 104 #define RHYTHMDB_ENTRY_TYPE_PODCAST_FEED (rhythmdb_entry_podcast_feed_get_type ())
 105 #define RHYTHMDB_ENTRY_TYPE_IMPORT_ERROR (rhythmdb_entry_import_error_get_type ())
 106 #define RHYTHMDB_ENTRY_TYPE_IGNORE (rhythmdb_entry_ignore_get_type ())
 107 #define RHYTHMDB_ENTRY_TYPE_INVALID (GINT_TO_POINTER (-1))
 108
 109 typedef enum
 110 {
 111         RHYTHMDB_QUERY_END,
 112         RHYTHMDB_QUERY_DISJUNCTION,
 113         RHYTHMDB_QUERY_SUBQUERY,
 114
 115         /* general */
 116         RHYTHMDB_QUERY_PROP_EQUALS,
 117
 118         /* string */
 119         RHYTHMDB_QUERY_PROP_LIKE,
 120         RHYTHMDB_QUERY_PROP_NOT_LIKE,
 121         RHYTHMDB_QUERY_PROP_PREFIX,
 122         RHYTHMDB_QUERY_PROP_SUFFIX,
 123
 124         /* numerical */
 125         RHYTHMDB_QUERY_PROP_GREATER,
 126         RHYTHMDB_QUERY_PROP_LESS,
 127
 128         /* synthetic query types, translated into non-synthetic ones internally */
 129         RHYTHMDB_QUERY_PROP_CURRENT_TIME_WITHIN,
 130         RHYTHMDB_QUERY_PROP_CURRENT_TIME_NOT_WITHIN,
 131         RHYTHMDB_QUERY_PROP_YEAR_EQUALS,
 132         RHYTHMDB_QUERY_PROP_YEAR_GREATER,
 133         RHYTHMDB_QUERY_PROP_YEAR_LESS,
 134 } RhythmDBQueryType;
 135
 136 /* If you modify this enum, don't forget to modify rhythmdb_prop_get_type */
 137 typedef enum
 138 {
 139         RHYTHMDB_PROP_TYPE = 0,
 140         RHYTHMDB_PROP_TITLE,
 141         RHYTHMDB_PROP_GENRE,
 142         RHYTHMDB_PROP_ARTIST,
 143         RHYTHMDB_PROP_ALBUM,
 144         RHYTHMDB_PROP_TRACK_NUMBER,
 145         RHYTHMDB_PROP_DISC_NUMBER,
 146         RHYTHMDB_PROP_DURATION,
 147         RHYTHMDB_PROP_FILE_SIZE,
 148         RHYTHMDB_PROP_LOCATION,
 149         RHYTHMDB_PROP_MOUNTPOINT,
 150         RHYTHMDB_PROP_MTIME,
 151         RHYTHMDB_PROP_FIRST_SEEN,
 152         RHYTHMDB_PROP_LAST_SEEN,
 153         RHYTHMDB_PROP_RATING,
 154         RHYTHMDB_PROP_PLAY_COUNT,
 155         RHYTHMDB_PROP_LAST_PLAYED,
 156         RHYTHMDB_PROP_BITRATE,
 157         RHYTHMDB_PROP_DATE,
 158         RHYTHMDB_PROP_TRACK_GAIN,
 159         RHYTHMDB_PROP_TRACK_PEAK,
 160         RHYTHMDB_PROP_ALBUM_GAIN,
 161         RHYTHMDB_PROP_ALBUM_PEAK,
 162         RHYTHMDB_PROP_MIMETYPE,
 163         RHYTHMDB_PROP_TITLE_SORT_KEY,
 164         RHYTHMDB_PROP_GENRE_SORT_KEY,
 165         RHYTHMDB_PROP_ARTIST_SORT_KEY,
 166         RHYTHMDB_PROP_ALBUM_SORT_KEY,
 167         RHYTHMDB_PROP_TITLE_FOLDED,
 168         RHYTHMDB_PROP_GENRE_FOLDED,
 169         RHYTHMDB_PROP_ARTIST_FOLDED,
 170         RHYTHMDB_PROP_ALBUM_FOLDED,
 171         RHYTHMDB_PROP_LAST_PLAYED_STR,
 172         RHYTHMDB_PROP_HIDDEN,
 173         RHYTHMDB_PROP_PLAYBACK_ERROR,
 174         RHYTHMDB_PROP_FIRST_SEEN_STR,
 175         RHYTHMDB_PROP_LAST_SEEN_STR,
 176
 177         /* synthetic properties */
 178         RHYTHMDB_PROP_SEARCH_MATCH,
 179         RHYTHMDB_PROP_YEAR,
 180
 181         /* Podcast properties */
 182         RHYTHMDB_PROP_STATUS,
 183         RHYTHMDB_PROP_DESCRIPTION,
 184         RHYTHMDB_PROP_SUBTITLE,
 185         RHYTHMDB_PROP_SUMMARY,
 186         RHYTHMDB_PROP_LANG,
 187         RHYTHMDB_PROP_COPYRIGHT,
 188         RHYTHMDB_PROP_IMAGE,
 189         RHYTHMDB_PROP_POST_TIME,
 190
 191         RHYTHMDB_NUM_PROPERTIES
 192 } RhythmDBPropType;
 193
 194 enum {
 195         RHYTHMDB_PODCAST_STATUS_COMPLETE = 100,
 196         RHYTHMDB_PODCAST_STATUS_ERROR = 101,
 197         RHYTHMDB_PODCAST_STATUS_WAITING = 102,
 198         RHYTHMDB_PODCAST_STATUS_PAUSED = 103,
 199 };
 200
 201 GType rhythmdb_query_type_get_type (void);
 202 GType rhythmdb_prop_type_get_type (void);
 203
 204 #define RHYTHMDB_TYPE_QUERY_TYPE (rhythmdb_query_type_get_type ())
 205 #define RHYTHMDB_TYPE_PROP_TYPE (rhythmdb_prop_type_get_type ())
 206
 207 typedef struct {
 208         guint type;
 209         guint propid;
 210         GValue *val;
 211         GPtrArray *subquery;
 212 } RhythmDBQueryData;
 213
 214 typedef struct {
 215         RhythmDBPropType prop;
 216         GValue old;
 217         GValue new;
 218 } RhythmDBEntryChange;
 219
 220 const char *rhythmdb_entry_get_string   (RhythmDBEntry *entry, RhythmDBPropType propid);
 221 char *rhythmdb_entry_dup_string (RhythmDBEntry *entry, RhythmDBPropType propid);
 222 gboolean rhythmdb_entry_get_boolean     (RhythmDBEntry *entry, RhythmDBPropType propid);
 223 guint64 rhythmdb_entry_get_uint64       (RhythmDBEntry *entry, RhythmDBPropType propid);
 224 gulong rhythmdb_entry_get_ulong         (RhythmDBEntry *entry, RhythmDBPropType propid);
 225 double rhythmdb_entry_get_double        (RhythmDBEntry *entry, RhythmDBPropType propid);
 226 gpointer rhythmdb_entry_get_pointer     (RhythmDBEntry *entry, RhythmDBPropType propid);
 227
 228 RhythmDBEntryType rhythmdb_entry_get_entry_type (RhythmDBEntry *entry);
 229
 230
 231
 232 typedef enum
 233 {
 234         RHYTHMDB_ERROR_ACCESS_FAILED,
 235 } RhythmDBError;
 236
 237 #define RHYTHMDB_ERROR (rhythmdb_error_quark ())
 238
 239 GQuark rhythmdb_error_quark (void);
 240
 241 typedef struct RhythmDBPrivate RhythmDBPrivate;
 242
 243 struct RhythmDB_
 244 {
 245         GObject parent;
 246
 247         RhythmDBPrivate *priv;
 248 };
 249
 250 typedef struct
 251 {
 252         GObjectClass parent;
 253
 254         /* signals */
 255         void    (*entry_added)          (RhythmDB *db, RhythmDBEntry *entry);
 256         void    (*entry_changed)        (RhythmDB *db, RhythmDBEntry *entry, GSList *changes); /* list of RhythmDBEntryChanges */
 257         void    (*entry_deleted)        (RhythmDB *db, RhythmDBEntry *entry);
 258         void    (*load_complete)        (RhythmDB *db);
 259         void    (*save_complete)        (RhythmDB *db);
 260         void    (*load_error)           (RhythmDB *db, const char *uri, const char *msg);
 261         void    (*save_error)           (RhythmDB *db, const char *uri, const GError *error);
 262         void    (*read_only)            (RhythmDB *db, gboolean readonly);
 263
 264         /* virtual methods */
 265
 266         void            (*impl_load)            (RhythmDB *db, gboolean *dead);
 267         void            (*impl_save)            (RhythmDB *db);
 268
 269         void            (*impl_entry_new)       (RhythmDB *db, RhythmDBEntry *entry);
 270
 271         gboolean        (*impl_entry_set)       (RhythmDB *db, RhythmDBEntry *entry,
 272                                          guint propid, const GValue *value);
 273
 274         void            (*impl_entry_get)       (RhythmDB *db, RhythmDBEntry *entry,
 275                                                  guint propid, GValue *value);
 276
 277         void            (*impl_entry_delete)    (RhythmDB *db, RhythmDBEntry *entry);
 278
 279         void            (*impl_entry_delete_by_type) (RhythmDB *db, RhythmDBEntryType type);
 280
 281         RhythmDBEntry * (*impl_lookup_by_location)(RhythmDB *db, const char *uri);
 282
 283         gboolean        (*impl_evaluate_query)  (RhythmDB *db, GPtrArray *query, RhythmDBEntry *entry);
 284
 285         void            (*impl_entry_foreach)   (RhythmDB *db, GFunc func, gpointer data);
 286
 287         void            (*impl_do_full_query)   (RhythmDB *db, GPtrArray *query,
 288                                                  RhythmDBQueryResults *results,
 289                                                  gboolean *cancel);
 290 } RhythmDBClass;
 291
 292
 293 GType           rhythmdb_get_type       (void);
 294
 295 RhythmDB *      rhythmdb_new            (const char *name);
 296
 297 void            rhythmdb_shutdown       (RhythmDB *db);
 298
 299 void            rhythmdb_load           (RhythmDB *db);
 300
 301 void            rhythmdb_save           (RhythmDB *db);
 302 void            rhythmdb_save_async     (RhythmDB *db);
 303
 304 void            rhythmdb_start_action_thread    (RhythmDB *db);
 305
 306 void            rhythmdb_commit         (RhythmDB *db);
 307
 308 gboolean        rhythmdb_entry_is_editable (RhythmDB *db, RhythmDBEntry *entry);
 309
 310 RhythmDBEntry * rhythmdb_entry_new      (RhythmDB *db, RhythmDBEntryType type, const char *uri);
 311 RhythmDBEntry * rhythmdb_entry_example_new      (RhythmDB *db, RhythmDBEntryType type, const char *uri);
 312
 313 void            rhythmdb_add_uri        (RhythmDB *db, const char *uri);
 314 void            rhythmdb_add_uri_with_type      (RhythmDB *db, const char *uri, RhythmDBEntryType type);
 315
 316 void            rhythmdb_entry_get      (RhythmDB *db, RhythmDBEntry *entry, RhythmDBPropType propid, GValue *val);
 317 void            rhythmdb_entry_set      (RhythmDB *db, RhythmDBEntry *entry,
 318                                          guint propid, const GValue *value);
 319 void            rhythmdb_entry_set_nonotify     (RhythmDB *db, RhythmDBEntry *entry,
 320                                                  guint propid, const GValue *value);
 321 void            rhythmdb_entry_set_uninserted   (RhythmDB *db, RhythmDBEntry *entry,
 322                                                  guint propid, const GValue *value);
 323
 324 char *          rhythmdb_entry_get_playback_uri (RhythmDBEntry *entry);
 325
 326 gpointer        rhythmdb_entry_get_type_data (RhythmDBEntry *entry, guint expected_size);
 327 #define         RHYTHMDB_ENTRY_GET_TYPE_DATA(e,t)       ((t*)rhythmdb_entry_get_type_data((e),sizeof(t)))
 328
 329 void            rhythmdb_entry_delete   (RhythmDB *db, RhythmDBEntry *entry);
 330 void            rhythmdb_entry_delete_by_type (RhythmDB *db,
 331                                                RhythmDBEntryType type);
 332 void            rhythmdb_entry_move_to_trash (RhythmDB *db,
 333                                               RhythmDBEntry *entry);
 334
 335
 336 RhythmDBEntry * rhythmdb_entry_lookup_by_location (RhythmDB *db, const char *uri);
 337
 338 gboolean        rhythmdb_evaluate_query         (RhythmDB *db, GPtrArray *query,
 339                                                  RhythmDBEntry *entry);
 340
 341 void            rhythmdb_entry_foreach          (RhythmDB *db,
 342                                                  GFunc func,
 343                                                  gpointer data);
 344
 345 /**
 346  * Returns a freshly allocated GtkTreeModel which represents the query.
 347  * The extended arguments alternate between RhythmDBQueryType args
 348  * and their values. Items are prioritized like algebraic expressions, and
 349  * implicitly ANDed. Here's an example:
 350  *
 351 rhythmdb_do_full_query (db,
 352                         RHYTHMDB_QUERY_PROP_EQUALS,
 353                                 RHYTHMDB_PROP_ARTIST, "Pink Floyd",
 354                 RHYTHMDB_QUERY_DISJUNCTION,
 355                         RHYTHMDB_QUERY_PROP_EQUALS,
 356                                 RHYTHMDB_PROP_GENRE, "Classical",
 357                         RHYTHMDB_QUERY_PROP_GREATER,
 358                                 RHYTHMDB_PROP_RATING, 5,
 359         RHYTHMDB_QUERY_END);
 360  * Which means: artist = Pink Floyd OR (genre = Classical AND rating >= 5)
 361  */
 362 void            rhythmdb_do_full_query                  (RhythmDB *db,
 363                                                          RhythmDBQueryResults *results,
 364                                                          ...);
 365 void            rhythmdb_do_full_query_parsed           (RhythmDB *db,
 366                                                          RhythmDBQueryResults *results,
 367                                                          GPtrArray *query);
 368
 369 void            rhythmdb_do_full_query_async            (RhythmDB *db,
 370                                                          RhythmDBQueryResults *results,
 371                                                          ...);
 372
 373 void            rhythmdb_do_full_query_async_parsed     (RhythmDB *db,
 374                                                          RhythmDBQueryResults *results,
 375                                                          GPtrArray *query);
 376
 377 void            rhythmdb_entry_sync_mirrored            (RhythmDB *db, RhythmDBEntry *entry, guint propid);
 378
 379 GPtrArray *     rhythmdb_query_parse                    (RhythmDB *db, ...);
 380 void            rhythmdb_query_append                   (RhythmDB *db, GPtrArray *query, ...);
 381 void            rhythmdb_query_append_prop_multiple     (RhythmDB *db, GPtrArray *query, RhythmDBPropType propid, GList *items);
 382 void            rhythmdb_query_concatenate              (GPtrArray *query1, GPtrArray *query2);
 383 void            rhythmdb_query_free                     (GPtrArray *query);
 384 GPtrArray *     rhythmdb_query_copy                     (GPtrArray *array);
 385 void            rhythmdb_query_preprocess               (RhythmDB *db, GPtrArray *query);
 386
 387 void            rhythmdb_query_serialize                (RhythmDB *db, GPtrArray *query,
 388                                                          xmlNodePtr node);
 389
 390 GPtrArray *     rhythmdb_query_deserialize              (RhythmDB *db, xmlNodePtr node);
 391
 392 gboolean        rhythmdb_query_is_time_relative         (RhythmDB *db, GPtrArray *query);
 393
 394 const xmlChar * rhythmdb_nice_elt_name_from_propid      (RhythmDB *db, RhythmDBPropType propid);
 395 int             rhythmdb_propid_from_nice_elt_name      (RhythmDB *db, const xmlChar *name);
 396
 397 void            rhythmdb_emit_entry_added               (RhythmDB *db, RhythmDBEntry *entry);
 398 void            rhythmdb_emit_entry_deleted             (RhythmDB *db, RhythmDBEntry *entry);
 399
 400 gboolean        rhythmdb_is_busy                        (RhythmDB *db);
 401 char *          rhythmdb_compute_status_normal          (gint n_songs, glong duration,
 402                                                          guint64 size,
 403                                                          const char *singular,
 404                                                          const char *plural);
 405
 406
 407 RhythmDBEntryType rhythmdb_entry_register_type          (const char *name);
 408 RhythmDBEntryType rhythmdb_entry_type_get_by_name       (const char *name);
 409
 410 RhythmDBEntryType rhythmdb_entry_song_get_type          (void);
 411 RhythmDBEntryType rhythmdb_entry_iradio_get_type        (void);
 412 RhythmDBEntryType rhythmdb_entry_podcast_post_get_type  (void);
 413 RhythmDBEntryType rhythmdb_entry_podcast_feed_get_type  (void);
 414 RhythmDBEntryType rhythmdb_entry_import_error_get_type  (void);
 415 RhythmDBEntryType rhythmdb_entry_ignore_get_type        (void);
 416
 417 GType rhythmdb_get_property_type (RhythmDB *db, guint property_id);
 418
 419 void rhythmdb_entry_ref (RhythmDB *db, RhythmDBEntry *entry);
 420 void rhythmdb_entry_unref (RhythmDB *db, RhythmDBEntry *entry);
 421
 422 G_END_DECLS
 423
 424 #endif /* __RHYTHMBDB_H */