Add an example server plugin

* configure.ac: Add an --enable-example-plugins option.
* autogen.sh: Add --enable-example-plugins
* examples/: Add an example server plugin implemented in Vala.
* src/librygel-core/rygel-plugin.vala:
* src/librygel-core/rygel-plugin.vala: Document the name, title,
  and description parameters used by the example.

11 files changed, 199 insertions, 0 deletions

diff --git a/autogen.sh b/autogen.sh
index 6c37024a..a2348ce1 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -38,5 +38,6 @@ REQUIRED_LIBTOOL_VERSION=2.2.6 \
 REQUIRED_INTLTOOL_VERSION=0.40.0 \
 bash gnome-autogen.sh --enable-vala --enable-valadoc --enable-maintainer-mode --enable-debug \
                  --enable-tests --enable-test-plugin \
+                 --enable-example-plugins \
                  --enable-mediathek-plugin --enable-gst-launch-plugin \
                  --enable-strict-valac "$@"
diff --git a/configure.ac b/configure.ac
index a3e24c4e..5c5db75f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -106,6 +106,12 @@ AS_IF([test "x$with_media_engine" = "xgstreamer"],
         RYGEL_DISABLE_PLUGIN([media-export])
         RYGEL_DISABLE_PLUGIN([gst-launch])
       ])
+ 
+dnl Example plugins:     
+AC_ARG_ENABLE([example-plugins],
+              AS_HELP_STRING([--enable-example-plugins],[enable example plugins]),,
+              enable_example_plugins=no)
+AM_CONDITIONAL([BUILD_EXAMPLE_PLUGINS], [test "x$[]enable_example_plugins" = "xyes"])
 
 dnl Explicitly add stamp files for targets that are not plugins
 RYGEL_ADD_STAMP([src/librygel-core/librygel_core_2_0_la_vala.stamp])
@@ -303,6 +309,8 @@ rygel-server-2.0.pc
 rygel-renderer-gst-2.0.pc
 tests/Makefile
 examples/Makefile
+examples/server-plugins/Makefile
+examples/server-plugins/vala/Makefile
 ])
 AC_OUTPUT
 
@@ -321,6 +329,7 @@ echo "
         preferences ui:         ${HAVE_GTK}
         Media Engine:           ${with_media_engine}
     Plugins:
+        examples:               ${enable_example_plugins}
         test:                   ${enable_test_plugin}
         tracker:                ${enable_tracker_plugin}
         mediathek:              ${enable_mediathek_plugin}
diff --git a/data/rygel.conf b/data/rygel.conf
index fc9a2078..3bf84c19 100644
--- a/data/rygel.conf
+++ b/data/rygel.conf
@@ -134,6 +134,12 @@ videotestoverlay-launch=videotestsrc ! timeoverlay ! ffenc_mpeg2video ! mpegtsmu
 [Test]
 enabled=false
 
+[ExampleServerPluginVala]
+enabled=false
+
+[ExampleRendererPluginVala]
+enabled=false
+
 [MPRIS]
 enabled=false
 
diff --git a/examples/Makefile.am b/examples/Makefile.am
index 6bf68a7a..c69c70f8 100644
--- a/examples/Makefile.am
+++ b/examples/Makefile.am
@@ -1,3 +1,13 @@
+# Avoid using the example plugins dirs at all
+# if they are not enabled, to avoid
+# installing them.
+if BUILD_EXAMPLE_PLUGINS
+EXAMPLE_PLUGINS = server-plugins
+endif
+
+SUBDIRS = $(EXAMPLE_PLUGINS)
+
+
 include ../common.am
 
 AM_CFLAGS += \
diff --git a/examples/server-plugins/Makefile.am b/examples/server-plugins/Makefile.am
new file mode 100644
index 00000000..ecd5d25a
--- /dev/null
+++ b/examples/server-plugins/Makefile.am
@@ -0,0 +1,2 @@
+SUBDIRS = vala
+
diff --git a/examples/server-plugins/vala/Makefile.am b/examples/server-plugins/vala/Makefile.am
new file mode 100644
index 00000000..4e270346
--- /dev/null
+++ b/examples/server-plugins/vala/Makefile.am
@@ -0,0 +1,20 @@
+include $(top_srcdir)/common.am
+
+plugin_LTLIBRARIES = librygel-example-server-plugin.la
+
+AM_CFLAGS += -DG_LOG_DOMAIN='"ExampleServerPlugin"'
+
+librygel_example_server_plugin_la_SOURCES = \
+	example-server-plugin.vala \
+	example-root-container.vala
+
+librygel_example_server_plugin_la_VALAFLAGS = \
+	--pkg gstreamer-0.10 \
+	$(RYGEL_COMMON_SERVER_PLUGIN_VALAFLAGS)
+
+librygel_example_server_plugin_la_LIBADD = \
+	$(LIBGSTREAMER_LIBS) \
+	$(RYGEL_COMMON_SERVER_LIBS)
+	
+librygel_example_server_plugin_la_LDFLAGS = \
+  $(RYGEL_PLUGIN_LINKER_FLAGS)
diff --git a/examples/server-plugins/vala/example-root-container.vala b/examples/server-plugins/vala/example-root-container.vala
new file mode 100644
index 00000000..8c5cdc86
--- /dev/null
+++ b/examples/server-plugins/vala/example-root-container.vala
@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2012 Intel Corporation
+ *
+ * This file is part of Rygel.
+ *
+ * Rygel is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * Rygel is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/**
+ * Our derived MediaContainer.
+ * In this example, we just derive from the SimpleContainer,
+ * but a real-world server plugin might need something more sophisticated.
+ */
+public class Rygel.Example.RootContainer : Rygel.SimpleContainer {
+    public RootContainer (string title) {
+        base.root (title);
+
+        /*
+         * Add media items to be served from this container via UPnP,
+         * using the standard AudioItem, ImageItem, MusicItem and 
+         * VideoItem classes, with URIs.
+         * A real server plugin would probably want to populate the container
+         * dynamically, for instance by monitoring a directory on the file system.
+         *
+         * Plugins may alternatively derive their own item classes, overriding 
+         * create_stream_source(). For instance, this could allow the plugin
+         * to server content from a database rather than from the file system.
+         */
+        var item = new MusicItem ("test 1", this, "Test 1");
+        item.add_uri ("file:///home/murrayc/Music/Madness/05_Baggy_Trousers.mp3");
+        item.mime_type = "audio/mpeg";
+        this.add_child_item(item);
+         
+        item = new MusicItem ("test 2", this, "Test 2");
+        item.add_uri ("file:///home/murrayc/Music/08%20Busload%20of%20Faith.mp3");
+        item.mime_type = "audio/mpeg";
+        this.add_child_item(item);
+    }
+}
+
+
diff --git a/examples/server-plugins/vala/example-server-plugin.vala b/examples/server-plugins/vala/example-server-plugin.vala
new file mode 100644
index 00000000..e0b0cfaa
--- /dev/null
+++ b/examples/server-plugins/vala/example-server-plugin.vala
@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2012 Intel Corporation
+ *
+ * This file is part of Rygel.
+ *
+ * Rygel is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * Rygel is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+using Rygel;
+using GUPnP;
+
+public void module_init (PluginLoader loader) {
+    if (loader.plugin_disabled (Rygel.Example.ServerPlugin.NAME)) {
+        message ("Plugin '%s' disabled by user, ignoring..",
+                 Rygel.Example.ServerPlugin.NAME);
+
+        return;
+    }
+
+    var plugin = new Rygel.Example.ServerPlugin ();
+    loader.add_plugin (plugin);
+}
+
+
+/*
+ * Our derived Plugin class.
+ * This mostly just instantiates and assigns our derived RootContainer class,
+ * where most work is usually done.
+ *
+ * To use this plugin, you must enable it in your rygel.conf file like so:
+ * [ExampleServerPluginVala]
+ * enabled=false
+ */
+public class Rygel.Example.ServerPlugin : Rygel.MediaServerPlugin {
+    /*
+     * The non-human-readable name for the service:
+     * Note that this should currently not contain spaces.
+     * See https://bugzilla.gnome.org/show_bug.cgi?id=679673
+     */ 
+    public const string NAME = "ExampleServerPluginVala";
+
+    /* Optional human-readable name for the service: */
+    public const string TITLE = "Example Server Plugin Vala";
+
+    /* Optional human-readable description for the service: */
+    public const string DESCRIPTION = "An example Rygel server plugin implemented in vala.";
+
+    public ServerPlugin () {
+    
+        /*
+         * Use our derived container:
+         */
+        var root_container = new RootContainer (TITLE);
+
+        base (root_container, NAME, DESCRIPTION);
+    }
+}
diff --git a/src/librygel-core/rygel-plugin.vala b/src/librygel-core/rygel-plugin.vala
index d8259cc5..c48e52e6 100644
--- a/src/librygel-core/rygel-plugin.vala
+++ b/src/librygel-core/rygel-plugin.vala
@@ -75,6 +75,20 @@ public class Rygel.Plugin : GUPnP.ResourceFactory {
 
     public ArrayList<IconInfo> default_icons;
 
+    /*
+     * TODO: Document the format of the template file, such as which tags/attributes
+     * should be present, which should be present but empty, and which
+     * tags should not be present.
+     */
+
+    /** 
+     * Create an instance of the plugin.
+     *
+     * @param desc_path The path of a template file for an XML description of the UPnP service.
+     * @param name The non-human-readable name for the plugin and its service, used in UPnP messages and in the Rygel configuration file.
+     * @param title An optional human-readable name (friendlyName) of the UPnP service provided by the plugin. If the title is empty then the name will be used.
+     * @param description An optional human-readable description (modelDescription) of the UPnP service provided by the plugin.
+     */
     public Plugin (string  desc_path,
                    string  name,
                    string? title,
diff --git a/src/librygel-renderer/rygel-media-renderer-plugin.vala b/src/librygel-renderer/rygel-media-renderer-plugin.vala
index 0e36d2e5..be206aaf 100644
--- a/src/librygel-renderer/rygel-media-renderer-plugin.vala
+++ b/src/librygel-renderer/rygel-media-renderer-plugin.vala
@@ -35,6 +35,13 @@ public class Rygel.MediaRendererPlugin : Rygel.Plugin {
                                 BuildConfig.DATA_DIR +
                                 "/xml/MediaRenderer2.xml";
 
+    /**
+     * Create an instance of the plugin.
+     *
+     * @param name The non-human-readable name for the plugin and its renderer, used in UPnP messages and in the Rygel configuration file.
+     * @param title An optional human-readable name (friendlyName) of the UpnP renderer provided by the plugin. If the title is empty then the name will be used.
+     * @param description An optional human-readable description (modelDescription) of the UPnP renderer provided by the plugin.
+     */
     public MediaRendererPlugin (string  name,
                                 string? title,
                                 string? description = null) {
diff --git a/src/librygel-server/rygel-media-server-plugin.vala b/src/librygel-server/rygel-media-server-plugin.vala
index cbea5077..58424540 100644
--- a/src/librygel-server/rygel-media-server-plugin.vala
+++ b/src/librygel-server/rygel-media-server-plugin.vala
@@ -33,6 +33,14 @@ public abstract class Rygel.MediaServerPlugin : Rygel.Plugin {
 
     public MediaContainer root_container;
 
+    /**
+     * Create an instance of the plugin.
+     * The plugin's service will have the same title as its root container.
+     *
+     * @param root_container The container that should be served by this plugin's service.
+     * @param name The non-human-readable name for the plugin and its service, used in UPnP messages and in the Rygel configuration file.
+     * @param description An optional human-readable description (modelDescription) of the UPnP service provided by the plugin.
+     */
     public MediaServerPlugin (MediaContainer root_container,
                               string         name,
                               string?        description = null) {