[rhythmbox] rhythmdb: add an entry type method for processing availability changes

[Jonathan Matthew <jmatthew src gnome org>]

commit ef12187bd117501306ad7d2e615fc13f64f4474a
Author: Jonathan Matthew <jonathan d14n org>
Date:   Sun Aug 8 22:12:17 2010 +1000

    rhythmdb: add an entry type method for processing availability changes
    
    Availability changes are things like filesystems being mounted and unmounted,
    results of checking for files on startup, and 'resource not found' errors when
    trying to play an entry.  The exact behaviour we want varies between entry types,
    and so far we've mostly just done what's right for normal song entries.

 rhythmdb/rhythmdb-entry-type.c |   70 ++++++++++++++++++++++++++++++++++++++++
 rhythmdb/rhythmdb-entry-type.h |   22 ++++++++++--
 2 files changed, 88 insertions(+), 4 deletions(-)
---
diff --git a/rhythmdb/rhythmdb-entry-type.c b/rhythmdb/rhythmdb-entry-type.c
index 4973bd8..8828d32 100644
--- a/rhythmdb/rhythmdb-entry-type.c
+++ b/rhythmdb/rhythmdb-entry-type.c
@@ -65,6 +65,11 @@ G_DEFINE_TYPE (RhythmDBEntryType, rhythmdb_entry_type, G_TYPE_OBJECT)
  * This is the base class for database entry type classes, which provide
  * some aspects of the behaviour of database entry types.  There are different
  * entry types for songs, radio streams, podcast feeds and episodes, and so on.
+ *
+ * Plugins written in Python or Vala can create new entry types by subclassing
+ * and overriding any methods required.  Plugins written in C can create a new
+ * instance of the RhythmDBEntryType base class and use its function pointer
+ * members rather than subclassing.
  */
 
 /**
@@ -106,6 +111,28 @@ rhythmdb_entry_get_playback_uri (RhythmDBEntry *entry)
 }
 
 /**
+ * rhythmdb_entry_update_availability:
+ * @entry: a #RhythmDBEntry
+ * @avail: an availability event
+ *
+ * Updates @entry to reflect its new availability.
+ */
+void
+rhythmdb_entry_update_availability (RhythmDBEntry *entry, RhythmDBEntryAvailability avail)
+{
+	RhythmDBEntryType *etype = rhythmdb_entry_get_entry_type (entry);
+	RhythmDBEntryTypeClass *klass = RHYTHMDB_ENTRY_TYPE_GET_CLASS (etype);
+
+	if (etype->update_availability) {
+		(etype->update_availability) (etype, entry, avail);
+	} else if (klass->get_playback_uri) {
+		(klass->update_availability) (etype, entry, avail);
+	} else {
+		/* do nothing? */
+	}
+}
+
+/**
  * rhythmdb_entry_created:
  * @entry: a newly created #RhythmDBEntry
  *
@@ -363,6 +390,17 @@ rhythmdb_entry_type_class_init (RhythmDBEntryTypeClass *klass)
 
 #define ENUM_ENTRY(NAME, DESC) { NAME, "" #NAME "", DESC }
 
+/**
+ * RhythmDBEntryCategory:
+ * @RHYTHMDB_ENTRY_NORMAL: Normal files on disk
+ * @RHYTHMDB_ENTRY_STREAM: Endless streams (eg shoutcast)
+ * @RHYTHMDB_ENTRY_CONTAINER: Containers for other entries (eg podcast feeds)
+ * @RHYTHMDB_ENTRY_VIRTUAL: Things Rhythmbox shouldn't normally deal with
+ *
+ * Categories used to group entry types.  These are used in a few places to control
+ * handling of entries.
+ */
+
 GType
 rhythmdb_entry_category_get_type (void)
 {
@@ -384,3 +422,35 @@ rhythmdb_entry_category_get_type (void)
 
 	return etype;
 }
+
+/**
+ * RhythmDBEntryAvailability:
+ * @RHYTHMDB_ENTRY_AVAIL_CHECKED: File was checked and found present
+ * @RHYTHMDB_ENTRY_AVAIL_MOUNTED: Filesystem holding the file was mounted
+ * @RHYTHMDB_ENTRY_AVAIL_UNMOUNTED: Filesystem holding the file was unmounted
+ * @RHYTHMDB_ENTRY_AVAIL_NOT_FOUND: File was checked or played and could not be found
+ *
+ * Various events that can result in changes to the entry's availability.
+ */
+
+GType
+rhythmdb_entry_availability_get_type (void)
+{
+	static GType etype = 0;
+
+	if (etype == 0)
+	{
+		static const GEnumValue values[] =
+		{
+			ENUM_ENTRY (RHYTHMDB_ENTRY_AVAIL_CHECKED, "checked"),
+			ENUM_ENTRY (RHYTHMDB_ENTRY_AVAIL_MOUNTED, "mounted"),
+			ENUM_ENTRY (RHYTHMDB_ENTRY_AVAIL_UNMOUNTED, "unmounted"),
+			ENUM_ENTRY (RHYTHMDB_ENTRY_AVAIL_NOT_FOUND, "not-found"),
+			{ 0, 0, 0 }
+		};
+
+		etype = g_enum_register_static ("RhythmDBEntryAvailability", values);
+	}
+
+	return etype;
+}
diff --git a/rhythmdb/rhythmdb-entry-type.h b/rhythmdb/rhythmdb-entry-type.h
index c725301..e27e373 100644
--- a/rhythmdb/rhythmdb-entry-type.h
+++ b/rhythmdb/rhythmdb-entry-type.h
@@ -40,12 +40,23 @@ G_BEGIN_DECLS
 GType rhythmdb_entry_category_get_type (void);
 #define RHYTHMDB_TYPE_ENTRY_CATEGORY (rhythmdb_entry_category_get_type ())
 typedef enum {
-	RHYTHMDB_ENTRY_NORMAL,		/* anything that doesn't match the other categories */
-	RHYTHMDB_ENTRY_STREAM,		/* endless streams (eg shoutcast) */
-	RHYTHMDB_ENTRY_CONTAINER,	/* things that point to other entries (eg podcast feeds) */
-	RHYTHMDB_ENTRY_VIRTUAL		/* import errors, ignored files */
+	RHYTHMDB_ENTRY_NORMAL,
+	RHYTHMDB_ENTRY_STREAM,
+	RHYTHMDB_ENTRY_CONTAINER,
+	RHYTHMDB_ENTRY_VIRTUAL
 } RhythmDBEntryCategory;
 
+/* entry availability events */
+
+GType rhythmdb_entry_availability_get_type (void);
+#define RHYTHMDB_TYPE_ENTRY_AVAILABILITY (rhythmdb_entry_availability_get_type ())
+typedef enum {
+	RHYTHMDB_ENTRY_AVAIL_CHECKED,
+	RHYTHMDB_ENTRY_AVAIL_MOUNTED,
+	RHYTHMDB_ENTRY_AVAIL_UNMOUNTED,
+	RHYTHMDB_ENTRY_AVAIL_NOT_FOUND
+} RhythmDBEntryAvailability;
+
 /* entry type */
 
 typedef struct _RhythmDBEntryType RhythmDBEntryType;
@@ -71,6 +82,7 @@ struct _RhythmDBEntryType {
 	void		(*destroy_entry) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
 
 	char *		(*get_playback_uri) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
+	void		(*update_availability) (RhythmDBEntryType *etype, RhythmDBEntry *entry, RhythmDBEntryAvailability avail);
 
 	gboolean	(*can_sync_metadata) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
 	void		(*sync_metadata) (RhythmDBEntryType *etype, RhythmDBEntry *entry, GSList *changes, GError **error);
@@ -86,6 +98,7 @@ struct _RhythmDBEntryTypeClass {
 	void		(*destroy_entry) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
 
 	char *		(*get_playback_uri) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
+	void		(*update_availability) (RhythmDBEntryType *etype, RhythmDBEntry *entry, RhythmDBEntryAvailability avail);
 
 	gboolean	(*can_sync_metadata) (RhythmDBEntryType *etype, RhythmDBEntry *entry);
 	void		(*sync_metadata) (RhythmDBEntryType *etype, RhythmDBEntry *entry, GSList *changes, GError **error);
@@ -96,6 +109,7 @@ GType		rhythmdb_entry_type_get_type (void);
 const char *	rhythmdb_entry_type_get_name (RhythmDBEntryType *etype);
 
 char *		rhythmdb_entry_get_playback_uri (RhythmDBEntry *entry);
+void		rhythmdb_entry_update_availability (RhythmDBEntry *entry, RhythmDBEntryAvailability avail);
 void 		rhythmdb_entry_created (RhythmDBEntry *entry);
 void 		rhythmdb_entry_pre_destroy (RhythmDBEntry *entry);
 gboolean 	rhythmdb_entry_can_sync_metadata (RhythmDBEntry *entry);