Fawkes API Fawkes Development Version
|
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