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
  57 typedef struct {
  58         /* virtual functions here */
  59         RhythmDBEntryActionFunc         post_entry_create;
  60         gpointer                        post_entry_create_data;
  61         GDestroyNotify                  post_entry_create_destroy;
  62
  63         RhythmDBEntryActionFunc         pre_entry_destroy;
  64         gpointer                        pre_entry_destroy_data;
  65         GDestroyNotify                  pre_entry_destroy_destroy;
  66
  67         RhythmDBEntryStringFunc         get_playback_uri;
  68         gpointer                        get_playback_uri_data;
  69         GDestroyNotify                  get_playback_uri_destroy;
  70 } RhythmDBEntryType_;
  71 typedef RhythmDBEntryType_ *RhythmDBEntryType;
  72
  73 GType rhythmdb_entry_type_get_type (void);
  74 #define RHYTHMDB_TYPE_ENTRY_TYPE        (rhythmdb_entry_type_get_type ())
  75 #define RHYTHMDB_ENTRY_TYPE(o)          (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE_ENTRY_TYPE, RhythmDBEntryType_))
  76 #define RHYTHMDB_IS_ENTRY_TYPE(o)       (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE_ENTRY_TYPE))
  77
  78
  79
  80 typedef GPtrArray RhythmDBQuery;
  81 GType rhythmdb_query_get_type (void);
  82 #define RHYTHMDB_TYPE_QUERY     (rhythmdb_query_get_type ())
  83 #define RHYTHMDB_QUERY(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE_QUERY, RhythmDBQuery))
  84 #define RHYTHMDB_IS_QUERY(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), RHYTHMDB_TYPE_QUERY))
  85
  86
  87 #define RHYTHMDB_ENTRY_TYPE_SONG (rhythmdb_entry_song_get_type ())
  88 #define RHYTHMDB_ENTRY_TYPE_IRADIO_STATION (rhythmdb_entry_iradio_get_type ())
  89 #define RHYTHMDB_ENTRY_TYPE_PODCAST_POST (rhythmdb_entry_podcast_post_get_type ())
  90 #define RHYTHMDB_ENTRY_TYPE_PODCAST_FEED (rhythmdb_entry_podcast_feed_get_type ())
  91 #define RHYTHMDB_ENTRY_TYPE_IMPORT_ERROR (rhythmdb_entry_import_error_get_type ())
  92 #define RHYTHMDB_ENTRY_TYPE_IGNORE (rhythmdb_entry_ignore_get_type ())
  93 #define RHYTHMDB_ENTRY_TYPE_INVALID (GINT_TO_POINTER (-1))
  94
  95 typedef enum
  96 {
  97         RHYTHMDB_QUERY_END,
  98         RHYTHMDB_QUERY_DISJUNCTION,
  99         RHYTHMDB_QUERY_SUBQUERY,
 100
 101         /* general */
 102         RHYTHMDB_QUERY_PROP_EQUALS,
 103
 104         /* string */
 105         RHYTHMDB_QUERY_PROP_LIKE,
 106         RHYTHMDB_QUERY_PROP_NOT_LIKE,
 107         RHYTHMDB_QUERY_PROP_PREFIX,
 108         RHYTHMDB_QUERY_PROP_SUFFIX,
 109
 110         /* numerical */
 111         RHYTHMDB_QUERY_PROP_GREATER,
 112         RHYTHMDB_QUERY_PROP_LESS,
 113
 114         /* synthetic query types, translated into non-synthetic ones internally */
 115         RHYTHMDB_QUERY_PROP_CURRENT_TIME_WITHIN,
 116         RHYTHMDB_QUERY_PROP_CURRENT_TIME_NOT_WITHIN,
 117         RHYTHMDB_QUERY_PROP_YEAR_EQUALS,
 118         RHYTHMDB_QUERY_PROP_YEAR_GREATER,
 119         RHYTHMDB_QUERY_PROP_YEAR_LESS,
 120 } RhythmDBQueryType;
 121
 122 /* If you modify this enum, don't forget to modify rhythmdb_prop_get_type */
 123 typedef enum
 124 {
 125         RHYTHMDB_PROP_TYPE = 0,
 126         RHYTHMDB_PROP_TITLE,
 127         RHYTHMDB_PROP_GENRE,
 128         RHYTHMDB_PROP_ARTIST,
 129         RHYTHMDB_PROP_ALBUM,
 130         RHYTHMDB_PROP_TRACK_NUMBER,
 131         RHYTHMDB_PROP_DISC_NUMBER,
 132         RHYTHMDB_PROP_DURATION,
 133         RHYTHMDB_PROP_FILE_SIZE,
 134         RHYTHMDB_PROP_LOCATION,
 135         RHYTHMDB_PROP_MOUNTPOINT,
 136         RHYTHMDB_PROP_MTIME,
 137         RHYTHMDB_PROP_FIRST_SEEN,
 138         RHYTHMDB_PROP_LAST_SEEN,
 139         RHYTHMDB_PROP_RATING,
 140         RHYTHMDB_PROP_PLAY_COUNT,
 141         RHYTHMDB_PROP_LAST_PLAYED,
 142         RHYTHMDB_PROP_BITRATE,
 143         RHYTHMDB_PROP_DATE,
 144         RHYTHMDB_PROP_TRACK_GAIN,
 145         RHYTHMDB_PROP_TRACK_PEAK,
 146         RHYTHMDB_PROP_ALBUM_GAIN,
 147         RHYTHMDB_PROP_ALBUM_PEAK,
 148         RHYTHMDB_PROP_MIMETYPE,
 149         RHYTHMDB_PROP_TITLE_SORT_KEY,
 150         RHYTHMDB_PROP_GENRE_SORT_KEY,
 151         RHYTHMDB_PROP_ARTIST_SORT_KEY,
 152         RHYTHMDB_PROP_ALBUM_SORT_KEY,
 153         RHYTHMDB_PROP_TITLE_FOLDED,
 154         RHYTHMDB_PROP_GENRE_FOLDED,
 155         RHYTHMDB_PROP_ARTIST_FOLDED,
 156         RHYTHMDB_PROP_ALBUM_FOLDED,
 157         RHYTHMDB_PROP_LAST_PLAYED_STR,
 158         RHYTHMDB_PROP_HIDDEN,
 159         RHYTHMDB_PROP_PLAYBACK_ERROR,
 160         RHYTHMDB_PROP_FIRST_SEEN_STR,
 161         RHYTHMDB_PROP_LAST_SEEN_STR,
 162
 163         /* synthetic properties */
 164         RHYTHMDB_PROP_SEARCH_MATCH,
 165         RHYTHMDB_PROP_YEAR,
 166
 167         /* Podcast properties */
 168         RHYTHMDB_PROP_STATUS,
 169         RHYTHMDB_PROP_DESCRIPTION,
 170         RHYTHMDB_PROP_SUBTITLE,
 171         RHYTHMDB_PROP_SUMMARY,
 172         RHYTHMDB_PROP_LANG,
 173         RHYTHMDB_PROP_COPYRIGHT,
 174         RHYTHMDB_PROP_IMAGE,
 175         RHYTHMDB_PROP_POST_TIME,
 176
 177         RHYTHMDB_NUM_PROPERTIES
 178 } RhythmDBPropType;
 179
 180 enum {
 181         RHYTHMDB_PODCAST_STATUS_COMPLETE = 100,
 182         RHYTHMDB_PODCAST_STATUS_ERROR = 101,
 183         RHYTHMDB_PODCAST_STATUS_WAITING = 102,
 184         RHYTHMDB_PODCAST_STATUS_PAUSED = 103,
 185 };
 186
 187 GType rhythmdb_query_type_get_type (void);
 188 GType rhythmdb_prop_type_get_type (void);
 189
 190 #define RHYTHMDB_TYPE_QUERY_TYPE (rhythmdb_query_type_get_type ())
 191 #define RHYTHMDB_TYPE_PROP_TYPE (rhythmdb_prop_type_get_type ())
 192
 193 typedef struct {
 194         guint type;
 195         guint propid;
 196         GValue *val;
 197         GPtrArray *subquery;
 198 } RhythmDBQueryData;
 199
 200 typedef struct {
 201         RhythmDBPropType prop;
 202         GValue old;
 203         GValue new;
 204 } RhythmDBEntryChange;
 205
 206 const char *rhythmdb_entry_get_string   (RhythmDBEntry *entry, RhythmDBPropType propid);
 207 char *rhythmdb_entry_dup_string (RhythmDBEntry *entry, RhythmDBPropType propid);
 208 gboolean rhythmdb_entry_get_boolean     (RhythmDBEntry *entry, RhythmDBPropType propid);
 209 guint64 rhythmdb_entry_get_uint64       (RhythmDBEntry *entry, RhythmDBPropType propid);
 210 gulong rhythmdb_entry_get_ulong         (RhythmDBEntry *entry, RhythmDBPropType propid);
 211 double rhythmdb_entry_get_double        (RhythmDBEntry *entry, RhythmDBPropType propid);
 212 gpointer rhythmdb_entry_get_pointer     (RhythmDBEntry *entry, RhythmDBPropType propid);
 213
 214 RhythmDBEntryType rhythmdb_entry_get_entry_type (RhythmDBEntry *entry);
 215
 216
 217
 218 typedef enum
 219 {
 220         RHYTHMDB_ERROR_ACCESS_FAILED,
 221 } RhythmDBError;
 222
 223 #define RHYTHMDB_ERROR (rhythmdb_error_quark ())
 224
 225 GQuark rhythmdb_error_quark (void);
 226
 227 typedef struct RhythmDBPrivate RhythmDBPrivate;
 228
 229 struct RhythmDB_
 230 {
 231         GObject parent;
 232
 233         RhythmDBPrivate *priv;
 234 };
 235
 236 typedef struct
 237 {
 238         GObjectClass parent;
 239
 240         /* signals */
 241         void    (*entry_added)          (RhythmDB *db, RhythmDBEntry *entry);
 242         void    (*entry_changed)        (RhythmDB *db, RhythmDBEntry *entry, GSList *changes); /* list of RhythmDBEntryChanges */
 243         void    (*entry_deleted)        (RhythmDB *db, RhythmDBEntry *entry);
 244         void    (*load_complete)        (RhythmDB *db);
 245         void    (*save_complete)        (RhythmDB *db);
 246         void    (*load_error)           (RhythmDB *db, const char *uri, const char *msg);
 247         void    (*save_error)           (RhythmDB *db, const char *uri, const GError *error);
 248         void    (*read_only)            (RhythmDB *db, gboolean readonly);
 249
 250         /* virtual methods */
 251
 252         void            (*impl_load)            (RhythmDB *db, gboolean *dead);
 253         void            (*impl_save)            (RhythmDB *db);
 254
 255         void            (*impl_entry_new)       (RhythmDB *db, RhythmDBEntry *entry);
 256
 257         gboolean        (*impl_entry_set)       (RhythmDB *db, RhythmDBEntry *entry,
 258                                          guint propid, const GValue *value);
 259
 260         void            (*impl_entry_get)       (RhythmDB *db, RhythmDBEntry *entry,
 261                                                  guint propid, GValue *value);
 262
 263         void            (*impl_entry_delete)    (RhythmDB *db, RhythmDBEntry *entry);
 264
 265         void            (*impl_entry_delete_by_type) (RhythmDB *db, RhythmDBEntryType type);
 266
 267         RhythmDBEntry * (*impl_lookup_by_location)(RhythmDB *db, const char *uri);
 268
 269         gboolean        (*impl_evaluate_query)  (RhythmDB *db, GPtrArray *query, RhythmDBEntry *entry);
 270
 271         void            (*impl_entry_foreach)   (RhythmDB *db, GFunc func, gpointer data);
 272
 273         void            (*impl_do_full_query)   (RhythmDB *db, GPtrArray *query,
 274                                                  RhythmDBQueryResults *results,
 275                                                  gboolean *cancel);
 276 } RhythmDBClass;
 277
 278
 279 GType           rhythmdb_get_type       (void);
 280
 281 RhythmDB *      rhythmdb_new            (const char *name);
 282
 283 void            rhythmdb_shutdown       (RhythmDB *db);
 284
 285 void            rhythmdb_load           (RhythmDB *db);
 286
 287 void            rhythmdb_save           (RhythmDB *db);
 288 void            rhythmdb_save_async     (RhythmDB *db);
 289
 290 void            rhythmdb_start_action_thread    (RhythmDB *db);
 291
 292 void            rhythmdb_commit         (RhythmDB *db);
 293
 294 gboolean        rhythmdb_entry_is_editable (RhythmDB *db, RhythmDBEntry *entry);
 295
 296 RhythmDBEntry * rhythmdb_entry_new      (RhythmDB *db, RhythmDBEntryType type, const char *uri);
 297 RhythmDBEntry * rhythmdb_entry_example_new      (RhythmDB *db, RhythmDBEntryType type, const char *uri);
 298
 299 void            rhythmdb_add_uri        (RhythmDB *db, const char *uri);
 300 void            rhythmdb_add_uri_with_type      (RhythmDB *db, const char *uri, RhythmDBEntryType type);
 301
 302 void            rhythmdb_entry_get      (RhythmDB *db, RhythmDBEntry *entry, RhythmDBPropType propid, GValue *val);
 303 void            rhythmdb_entry_set      (RhythmDB *db, RhythmDBEntry *entry,
 304                                          guint propid, const GValue *value);
 305 void            rhythmdb_entry_set_nonotify     (RhythmDB *db, RhythmDBEntry *entry,
 306                                                  guint propid, const GValue *value);
 307 void            rhythmdb_entry_set_uninserted   (RhythmDB *db, RhythmDBEntry *entry,
 308                                                  guint propid, const GValue *value);
 309
 310 char *          rhythmdb_entry_get_playback_uri (RhythmDBEntry *entry);
 311
 312 void            rhythmdb_entry_delete   (RhythmDB *db, RhythmDBEntry *entry);
 313 void            rhythmdb_entry_delete_by_type (RhythmDB *db,
 314                                                RhythmDBEntryType type);
 315 void            rhythmdb_entry_move_to_trash (RhythmDB *db,
 316                                               RhythmDBEntry *entry);
 317
 318
 319 RhythmDBEntry * rhythmdb_entry_lookup_by_location (RhythmDB *db, const char *uri);
 320
 321 gboolean        rhythmdb_evaluate_query         (RhythmDB *db, GPtrArray *query,
 322                                                  RhythmDBEntry *entry);
 323
 324 void            rhythmdb_entry_foreach          (RhythmDB *db,
 325                                                  GFunc func,
 326                                                  gpointer data);
 327
 328 /**
 329  * Returns a freshly allocated GtkTreeModel which represents the query.
 330  * The extended arguments alternate between RhythmDBQueryType args
 331  * and their values. Items are prioritized like algebraic expressions, and
 332  * implicitly ANDed. Here's an example:
 333  *
 334 rhythmdb_do_full_query (db,
 335                         RHYTHMDB_QUERY_PROP_EQUALS,
 336                                 RHYTHMDB_PROP_ARTIST, "Pink Floyd",
 337                 RHYTHMDB_QUERY_DISJUNCTION,
 338                         RHYTHMDB_QUERY_PROP_EQUALS,
 339                                 RHYTHMDB_PROP_GENRE, "Classical",
 340                         RHYTHMDB_QUERY_PROP_GREATER,
 341                                 RHYTHMDB_PROP_RATING, 5,
 342         RHYTHMDB_QUERY_END);
 343  * Which means: artist = Pink Floyd OR (genre = Classical AND rating >= 5)
 344  */
 345 void            rhythmdb_do_full_query                  (RhythmDB *db,
 346                                                          RhythmDBQueryResults *results,
 347                                                          ...);
 348 void            rhythmdb_do_full_query_parsed           (RhythmDB *db,
 349                                                          RhythmDBQueryResults *results,
 350                                                          GPtrArray *query);
 351
 352 void            rhythmdb_do_full_query_async            (RhythmDB *db,
 353                                                          RhythmDBQueryResults *results,
 354                                                          ...);
 355
 356 void            rhythmdb_do_full_query_async_parsed     (RhythmDB *db,
 357                                                          RhythmDBQueryResults *results,
 358                                                          GPtrArray *query);
 359
 360 void            rhythmdb_entry_sync_mirrored            (RhythmDB *db, RhythmDBEntry *entry, guint propid);
 361
 362 GPtrArray *     rhythmdb_query_parse                    (RhythmDB *db, ...);
 363 void            rhythmdb_query_append                   (RhythmDB *db, GPtrArray *query, ...);
 364 void            rhythmdb_query_append_prop_multiple     (RhythmDB *db, GPtrArray *query, RhythmDBPropType propid, GList *items);
 365 void            rhythmdb_query_concatenate              (GPtrArray *query1, GPtrArray *query2);
 366 void            rhythmdb_query_free                     (GPtrArray *query);
 367 GPtrArray *     rhythmdb_query_copy                     (GPtrArray *array);
 368 void            rhythmdb_query_preprocess               (RhythmDB *db, GPtrArray *query);
 369
 370 void            rhythmdb_query_serialize                (RhythmDB *db, GPtrArray *query,
 371                                                          xmlNodePtr node);
 372
 373 GPtrArray *     rhythmdb_query_deserialize              (RhythmDB *db, xmlNodePtr node);
 374
 375 const xmlChar * rhythmdb_nice_elt_name_from_propid      (RhythmDB *db, RhythmDBPropType propid);
 376 int             rhythmdb_propid_from_nice_elt_name      (RhythmDB *db, const xmlChar *name);
 377
 378 void            rhythmdb_emit_entry_added               (RhythmDB *db, RhythmDBEntry *entry);
 379 void            rhythmdb_emit_entry_deleted             (RhythmDB *db, RhythmDBEntry *entry);
 380
 381 gboolean        rhythmdb_is_busy                        (RhythmDB *db);
 382 char *          rhythmdb_compute_status_normal          (gint n_songs, glong duration,
 383                                                          guint64 size,
 384                                                          const char *singular,
 385                                                          const char *plural);
 386
 387
 388 RhythmDBEntryType rhythmdb_entry_register_type          (void);
 389
 390 RhythmDBEntryType rhythmdb_entry_song_get_type          (void);
 391 RhythmDBEntryType rhythmdb_entry_iradio_get_type        (void);
 392 RhythmDBEntryType rhythmdb_entry_podcast_post_get_type  (void);
 393 RhythmDBEntryType rhythmdb_entry_podcast_feed_get_type  (void);
 394 RhythmDBEntryType rhythmdb_entry_import_error_get_type  (void);
 395 RhythmDBEntryType rhythmdb_entry_ignore_get_type        (void);
 396
 397 GType rhythmdb_get_property_type (RhythmDB *db, guint property_id);
 398
 399 void rhythmdb_entry_ref (RhythmDB *db, RhythmDBEntry *entry);
 400 void rhythmdb_entry_unref (RhythmDB *db, RhythmDBEntry *entry);
 401
 402 G_END_DECLS
 403
 404 #endif /* __RHYTHMBDB_H */