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