plugin.h

00001 
00002 /***************************************************************************
00003  *  plugin.h - Interface for a Fawkes plugin
00004  *
00005  *  Created: Wed Aug 23 15:19:13 2006
00006  *  Copyright  2006-2007  Tim Niemueller [www.niemueller.de]
00007  *
00008  ****************************************************************************/
00009 
00010 /*  This program is free software; you can redistribute it and/or modify
00011  *  it under the terms of the GNU General Public License as published by
00012  *  the Free Software Foundation; either version 2 of the License, or
00013  *  (at your option) any later version. A runtime exception applies to
00014  *  this software (see LICENSE.GPL_WRE file mentioned below for details).
00015  *
00016  *  This program is distributed in the hope that it will be useful,
00017  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  *  GNU Library General Public License for more details.
00020  *
00021  *  Read the full text in the LICENSE.GPL_WRE file in the doc directory.
00022  */
00023 
00024 #ifndef __CORE_PLUGIN_H_
00025 #define __CORE_PLUGIN_H_
00026 
00027 #include <core/threading/thread_list.h>
00028 
00029 namespace fawkes {
00030 
00031 class Configuration;
00032 
00033 class Plugin {
00034  public:
00035 
00036   Plugin(Configuration *config);
00037   virtual ~Plugin();
00038 
00039   void          set_name(const char *name);
00040   const char *  name() const;
00041   ThreadList &  threads();
00042 
00043   virtual bool          persistent();
00044 
00045  protected:
00046   /** Thread list member. Initialise this list with the threads that this
00047    * plugin will use. These threads must exist for the whole life time of
00048    * the thread. Use sleeping threads if you need to turn on and off threads
00049    * dynamically. You may not add threads later to the list, as the list
00050    * is shortly after the constructor sealed.
00051    * @see ThreadList
00052    */
00053   ThreadList thread_list;
00054 
00055   /** Fawkes configuration. You can use the configuration to add certain threads
00056    * depending on the requested feature set. Use it only in your constructor.
00057    */
00058   Configuration *config;
00059 
00060  private:
00061   char       *_name_alloc;
00062   const char *_name;
00063 };
00064 
00065 /** Plugin loader function for the shared library
00066  * Do not use directly, rather use the EXPORT_PLUGIN macro.
00067  * @relates fawkes::Plugin
00068  */
00069 typedef Plugin *  (* PluginFactoryFunc)  (fawkes::Configuration *);
00070 
00071 /** Plugin destructor function for the shared library.
00072  * Do not use directly, rather use the EXPORT_PLUGIN macro.
00073  * @param plugin plugin to destroy
00074  * @relates fawkes::Plugin
00075  */
00076 typedef void      (* PluginDestroyFunc)  (Plugin *plugin);
00077 
00078 
00079 /** Plugin description function for the shared library.
00080  * @return short string describing the plugin.
00081  */
00082 typedef const char *  (* PluginDescriptionFunc) ();
00083 
00084 /** Plugin depdendency function for the shared library.
00085  * @return short string with a comma separated list of plugins that this
00086  * plugin depends on.
00087  */
00088 typedef const char *  (* PluginDependenciesFunc) ();
00089 
00090 
00091 /** Plugin factory function for this plugin.
00092  * @return an instance of ExamplePlugin
00093  */
00094 #define PLUGIN_FACTORY(plugin_class)                    \
00095   extern "C"                                            \
00096   Plugin *                                              \
00097   plugin_factory(fawkes::Configuration *config)         \
00098   {                                                     \
00099     return new plugin_class(config);                    \
00100   }
00101 
00102 
00103 /** Plugin destruction function for this plugin.
00104  * @param plugin The plugin that is to be destroyed. Do not use this plugin
00105  *        afterwards
00106  */
00107 #define PLUGIN_DESTROY(plugin_class)                    \
00108   extern "C"                                            \
00109   void                                                  \
00110   plugin_destroy(plugin_class *plugin)                  \
00111   {                                                     \
00112     delete plugin;                                      \
00113   }
00114 
00115 
00116 /** Plugin description.
00117  * Use this macro to set a short description of the plugi
00118  * @param info_string a short string describing the plugin
00119  */
00120 #define PLUGIN_DESCRIPTION(info_string)                 \
00121   extern "C"                                            \
00122   const char *                                          \
00123   plugin_description()                                  \
00124   {                                                     \
00125     return info_string;                                 \
00126   }
00127 
00128 /** Set plugin dependencies.
00129  * @param plugin_list a string with a comma-separated list
00130  * of plugins that this plugin depends on.
00131  */
00132 #define PLUGIN_DEPENDS(plugin_list)                     \
00133   extern "C"                                            \
00134   const char *                                          \
00135   plugin_depends()                                      \
00136   {                                                     \
00137     return plugin_list;                                 \
00138   }
00139 
00140 
00141 
00142 /** Export plugin.
00143  * This will create appropriate plugin factory and destroy functions.
00144  */
00145 #define EXPORT_PLUGIN(plugin_class) \
00146   PLUGIN_FACTORY(plugin_class)      \
00147                                     \
00148   PLUGIN_DESTROY(plugin_class)
00149 
00150 
00151 } // end namespace fawkes
00152 
00153 #endif