plugin.cpp

00001 
00002 /***************************************************************************
00003  *  plugin.cpp - Interface for a Fawkes plugin, some method have a base
00004  *               implementation that can be overridden in special situations.
00005  *
00006  *  Created: Sat Sep 16 17:04:55 2006
00007  *  Copyright  2007  Tim Niemueller [www.niemueller.de]
00008  *
00009  ****************************************************************************/
00010 
00011 /*  This program is free software; you can redistribute it and/or modify
00012  *  it under the terms of the GNU General Public License as published by
00013  *  the Free Software Foundation; either version 2 of the License, or
00014  *  (at your option) any later version. A runtime exception applies to
00015  *  this software (see LICENSE.GPL_WRE file mentioned below for details).
00016  *
00017  *  This program is distributed in the hope that it will be useful,
00018  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  *  GNU Library General Public License for more details.
00021  *
00022  *  Read the full text in the LICENSE.GPL_WRE file in the doc directory.
00023  */
00024 
00025 #include <core/plugin.h>
00026 #include <core/threading/thread.h>
00027 #include <cstring>
00028 #include <cstdlib>
00029 
00030 namespace fawkes {
00031 
00032 /** @class Plugin <core/plugin.h>
00033  * Plugin interface class.
00034  * Derive this class to create a new Fawkes plugin. There is not much that
00035  * you have to do to get a basic plugin working. The base plugin will already
00036  * handle all the important details.
00037  *
00038  * To implement a plugin create a new class that inherits from Plugin. Call
00039  * the Plugin constructor with the proper parameters in your derivate's
00040  * constructor. Then in your constructor fill the thread_list member with
00041  * the threads that your plugin needs. Instantiate all threads that your
00042  * plugin may ever need during its lifetime, creating (blocked timing)
00043  * threads during the life time of a plugin is not allowed. After the
00044  * constructor the thread list has to be considered to be sealed.
00045  * At the end of the file add a line like
00046  * @code
00047  * EXPORT_PLUGIN(PluginClass)
00048  * @endcode
00049  * where PluginClass is the class name of your plugin. This will create the
00050  * proper glue code to make this class loadable as plugin by Fawkes.
00051  *
00052  * @see ThreadList
00053  *
00054  * @ingroup FCL
00055  * @author Tim Niemueller
00056  */
00057 
00058 /* IMPLEMENTOR'S NOTE:
00059  * I'm aware that we do not link libfawkescore against libfawkesconfig, so why
00060  * do we put the reference to fawkes::Configuration here? Two things to consider:
00061  * 1. We only pass through the pointer, nothing more. We do not need to know about
00062  * the declaration or definition!
00063  * 2. We want to keep plugin.(h|cpp) in libfawkescore, rather than in
00064  * libfawkesplugin to keep the minimum requirements for plugins low.
00065  */
00066 
00067 /** Constructor.
00068  * Pass the name of your plugin to this ctor.
00069  * @param config configuration
00070  */
00071 Plugin::Plugin(Configuration *config)
00072 {
00073   this->config = config;
00074   _name_alloc = NULL;
00075   _name = "PluginNameNotSet";
00076 }
00077 
00078 /** Virtual destructor */
00079 Plugin::~Plugin()
00080 {
00081   for (ThreadList::iterator i = thread_list.begin(); i != thread_list.end(); ++i) {
00082     delete *i;
00083   }
00084   if (_name_alloc) free(_name_alloc);
00085 }
00086 
00087 
00088 /** Determines if the plugin can be unloaded.
00089  * This method tells the plugin loader if this plugin can be unloaded. Use
00090  * with care. No plugins but core plugins should return true. Only override
00091  * this if needed. The default behaviour if not overridden is to return false.
00092  * @return true, if the plugin cannot be unloaded, false otherwise. The default
00093  * implementation returns false.
00094  */
00095 bool
00096 Plugin::persistent()
00097 {
00098   return false;
00099 }
00100 
00101 /** Get a list of threads.
00102  * This function shall return a list of threads. See the FawkesThreadManager
00103  * for supported special types of threads. This method is called only once
00104  * right after the plugin has been initialised. You may not change the
00105  * list afterwards by adding or removing threads. Especially you may not delete
00106  * the threads!
00107  * @return list of threads.
00108  */
00109 ThreadList &
00110 Plugin::threads()
00111 {
00112   return thread_list;
00113 }
00114 
00115 
00116 /** Set plugin name.
00117  * Set the name of this plugin. This method should never be called from user code,
00118  * but only from the plugin loding/initialization system.
00119  * @param name new name
00120  */
00121 void
00122 Plugin::set_name(const char *name)
00123 {
00124   if ( _name_alloc )  free(_name_alloc);
00125 
00126   thread_list.set_name("%s", name);
00127 
00128   _name_alloc = strdup(name);
00129   if ( ! _name_alloc ) {
00130     // We do not want to throw an exception here
00131     _name = "OutOfMemoryForPluginName";
00132   } else {
00133     _name = _name_alloc;
00134   }
00135 }
00136 
00137 
00138 /** Get the name of the plugin.
00139  * @return name of the plugin
00140  */
00141 const char *
00142 Plugin::name() const
00143 {
00144   return _name;
00145 }
00146 
00147 
00148 } // end namespace fawkes

Generated on Tue Feb 22 13:31:25 2011 for Fawkes API by  doxygen 1.4.7