Xfmedia Plugin Guide
--------------------

Xfmedia's plugin system is very new, and will probably change a bit, but
here's a quick overview of how it works.

* Header files *

The header files a plugin author is going to care about are:
xfmedia/xfmedia-plugin.h - Provides the plugin object itself.
xfmedia/xfmedia-interface.h - Provides various functions to interact with
    the playback engine.  The functions in this file will definitely change
    before 1.0.
xfmedia/xfmedia-settings.h - Provides a means to store settings in Xfmedia's
    XML settings file.
xfmedia/xfmedia-playlist.h - Provides a means to interact with Xfmedia's
    playlist.
xfmedia/xfmedia-remote-client.h - Provides functions for remotely controlling
    another Xfmedia instance.

The first one, xfmedia-plugin.h defines the interface for the XfmediaPlugin
object.  You should not create one of these on your own; Xfmedia will create
one for you and give it to you.  You should use the set and get methods
to manipulate the various metadata that the plugin object exports.  If
you want to store "user data" with the plugin, I suggest using
g_object_set_data() and g_object_get_data().  Just come up with a unique
string to use to identify your data.

The XfmediaPlugin object also contains a number of signals that are all
fired *after* the specified action occurs.  The one exception is the
"unloading" signal, which is fired right before your plugin gets unloaded.
You should do any plugin-specific cleanup by connecting to this signal.

NB: You should NEVER EVER EVER connect to any signals except those provided
by XfmediaPlugin.  Useful signals from e.g. XfmediaPlaylist will be forwarded
to a corresponding XfmediaPlugin signal.  If you connect directly to
XfmediaPlaylist, and your plugin is later unloaded, Xfmedia will crash the next
time the signal is emitted.

The second header, xfmedia-interface.h, contains functions that can be
used to control Xfmedia's playback engine, as well as get information
about the currently-loaded stream.  This file will probably be the most
volatile, as it mainly contains functions that will be available once
XfmediaMainwin is turned into a GtkWidget subclass.

Thirdly, xfmedia-settings.h can be used to store persistent data across
Xfmedia sessions.  The settings functions take a "key" value that
corresponds to a slash-separated path, which, in the current implementation,
is stored in a hierarchical XML file.  The paths "/xfmedia/general/" and
"/xfmedia/playlist/" are reserved for internal use, but you are welcome
to use "/xfmedia/plugins/your-plugin-name/" as a root path to store your
plugin's settings.  Be sure to use the "add" functions first to add a
default value if your plugin has never been loaded before.  Calling one of
the "add" functions multiple times is safe, and will not overwrite any
existing settings.

The xfmedia-playlist.h file contains functions related to the playlist object.
Feel free to use any of the functions provided to manipulate the playlist.
Not to beat the issue to death, but do not, under any circumstances, connect
to the XfmediaPlaylist object's signals.  Use the corresponding signals in
XfmediaPlugin.

The xfmedia-remote-client.h file allows you to remotely control another
running instance of Xfmedia.  I'm not entirely sure how this will be useful
to plugins, but it's there if you can find a use.


* Creating a Plugin *

Xfmedia plugins are shared objects that are dynamically probed and loaded
at runtime.  There are two required functions that need to be exported
by your plugin, and one optional function.

The first is xfmedia_plugin_check_version().  There is no reason to create
this function yourself; you can define and declare it using the
XFMEDIA_PLUGIN_DECL macro provided in xfmedia-plugin.h.  Please don't
override this with something else; if I change the Xfmedia plugin API, and
your plugin still loads, it will likely cause Xfmedia to crash.

The second required function is xfmedia_plugin_get().  This is something
you need to provide.  Its signature should be:

G_MODULE_EXPORT gboolean xfmedia_plugin_get(XfmediaPlugin *plugin,
		GError **error);

The |plugin| pointer is created by Xfmedia, and you should use the
xfmedia_plugin_*() family of functions to set metadata for your plugin.  Also
connect any signals that you're interested in watching.  The |error| pointer
is a place to store any errors you encounter while initialising your plugin.
At present, this error message is printed to stderr, but eventually Xfmedia
may pop up an error dialog.  When finished with initialisation, you should
return TRUE to indicate that all is well, or FALSE to indicate that there
was a problem and that Xfmedia should unload your plugin.

There is an optional function which can be used to display a settings
panel for your plugin:

G_MODULE_EXPORT GtkWidget *xfmedia_plugin_get_settings(XfmediaPlugin *plugin);

If you don't wish your plugin to provide a settings panel, simply return
NULL here.  Otherwise, create the settings panel and return the toplevel
Gtk box widget.  Do NOT return a GtkWindow.  Ideally, you should return a
GtkHBox or GtkVBox (or something like that).  I have not yet implemented
support in Xfmedia for plugin settings panels, so right now this won't
atually do anything.


* Compiling Your Plugin *

Xfmedia provides a pkg-config file called xfmedia-plugin.pc.  You'll need
to test for it using the PKG_CHECK_MODULES() macro in your configure.ac
(or, if you're using xfce4-dev-tools, you can use XDT_CHECK_PACKAGE()).
Assuming you use XFMEDIA_PLUGIN as the macro name, you can use
@XFMEDIA_PLUGIN_CFLAGS@ and @XFMEDIA_PLUGIN_LIBS@ in your Makefile.am.  Those
substitutions should take care of all include path and library dependencies
that are required by Xfmedia, including linking to Glib, GObject, GThread,
Gtk+, libxfce4util, and libxfcegui4.


* Plugin API Versioning *

Since I'm not finished with the plugin API (and I likely won't be for a while),
the plugin API is versioned using major, minor, and micro version numbers:

* The major version indicates a backward-incompatible change.  Plugins written
  for a previous (or future) major version will likely not work with the
  current major version, and will not be loaded by Xfmedia.
* The minor version indicates a backward-compatibile addition or change to
  the API.  Plugins written for a previous minor version will continue to work
  (and be loaded) as Xfmedia supports a higher minor version API.  Plugins
  compiled for a newer version of the API than Xfmedia supports will not be
  loaded.
* The micro version indicates bugfixes to the plugin system, and involves
  no changes to the API whatsoever.  Essentially, the micro version is
  irrelevant and is only there for completeness.

From your perspective, you need not worry about the API version all that
much.  The XFMEDIA_PLUGIN_DECL will take care of exporting a function to
Xfmedia that will allow it to check the version number of the API used
to compile your plugin.

I think that's about it for now.  I'll add to this as I come up with more
information.