Fawkes API  Fawkes Development Version
plugin.cpp
1 
2 /***************************************************************************
3  * plugin.cpp - Interface for a Fawkes plugin, some method have a base
4  * implementation that can be overridden in special situations.
5  *
6  * Created: Sat Sep 16 17:04:55 2006
7  * Copyright 2007 Tim Niemueller [www.niemueller.de]
8  *
9  ****************************************************************************/
10 
11 /* This program is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version. A runtime exception applies to
15  * this software (see LICENSE.GPL_WRE file mentioned below for details).
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20  * GNU Library General Public License for more details.
21  *
22  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
23  */
24 
25 #include <core/plugin.h>
26 #include <core/threading/thread.h>
27 #include <cstring>
28 #include <cstdlib>
29 
30 namespace fawkes {
31 
32 /** @class Plugin <core/plugin.h>
33  * Plugin interface class.
34  * Derive this class to create a new Fawkes plugin. There is not much that
35  * you have to do to get a basic plugin working. The base plugin will already
36  * handle all the important details.
37  *
38  * To implement a plugin create a new class that inherits from Plugin. Call
39  * the Plugin constructor with the proper parameters in your derivate's
40  * constructor. Then in your constructor fill the thread_list member with
41  * the threads that your plugin needs. Instantiate all threads that your
42  * plugin may ever need during its lifetime, creating (blocked timing)
43  * threads during the life time of a plugin is not allowed. After the
44  * constructor the thread list has to be considered to be sealed.
45  * At the end of the file add a line like
46  * @code
47  * EXPORT_PLUGIN(PluginClass)
48  * @endcode
49  * where PluginClass is the class name of your plugin. This will create the
50  * proper glue code to make this class loadable as plugin by Fawkes.
51  *
52  * @see ThreadList
53  *
54  * @ingroup FCL
55  * @author Tim Niemueller
56  */
57 
58 /* IMPLEMENTOR'S NOTE:
59  * I'm aware that we do not link libfawkescore against libfawkesconfig, so why
60  * do we put the reference to fawkes::Configuration here? Two things to consider:
61  * 1. We only pass through the pointer, nothing more. We do not need to know about
62  * the declaration or definition!
63  * 2. We want to keep plugin.(h|cpp) in libfawkescore, rather than in
64  * libfawkesplugin to keep the minimum requirements for plugins low.
65  */
66 
67 /** Constructor.
68  * Pass the name of your plugin to this ctor.
69  * @param config configuration
70  */
72 {
73  this->config = config;
74  _name_alloc = NULL;
75  _name = "PluginNameNotSet";
76 }
77 
78 /** Virtual destructor */
80 {
81  for (ThreadList::iterator i = thread_list.begin(); i != thread_list.end(); ++i) {
82  delete *i;
83  }
84  if (_name_alloc) free(_name_alloc);
85 }
86 
87 
88 /** Determines if the plugin can be unloaded.
89  * This method tells the plugin loader if this plugin can be unloaded. Use
90  * with care. No plugins but core plugins should return true. Only override
91  * this if needed. The default behaviour if not overridden is to return false.
92  * @return true, if the plugin cannot be unloaded, false otherwise. The default
93  * implementation returns false.
94  */
95 bool
97 {
98  return false;
99 }
100 
101 /** Get a list of threads.
102  * This function shall return a list of threads. See the FawkesThreadManager
103  * for supported special types of threads. This method is called only once
104  * right after the plugin has been initialised. You may not change the
105  * list afterwards by adding or removing threads. Especially you may not delete
106  * the threads!
107  * @return list of threads.
108  */
109 ThreadList &
111 {
112  return thread_list;
113 }
114 
115 
116 /** Set plugin name.
117  * Set the name of this plugin. This method should never be called from user code,
118  * but only from the plugin loding/initialization system.
119  * @param name new name
120  */
121 void
122 Plugin::set_name(const char *name)
123 {
124  if ( _name_alloc ) free(_name_alloc);
125 
126  thread_list.set_name("%s", name);
127 
128  _name_alloc = strdup(name);
129  if ( ! _name_alloc ) {
130  // We do not want to throw an exception here
131  _name = "OutOfMemoryForPluginName";
132  } else {
133  _name = _name_alloc;
134  }
135 }
136 
137 
138 /** Get the name of the plugin.
139  * @return name of the plugin
140  */
141 const char *
143 {
144  return _name;
145 }
146 
147 
148 } // end namespace fawkes
void set_name(const char *name)
Set plugin name.
Definition: plugin.cpp:122
Fawkes library namespace.
ThreadList & threads()
Get a list of threads.
Definition: plugin.cpp:110
const char * name() const
Get the name of the plugin.
Definition: plugin.cpp:142
List of threads.
Definition: thread_list.h:57
ThreadList thread_list
Thread list member.
Definition: plugin.h:53
Plugin(Configuration *config)
Constructor.
Definition: plugin.cpp:71
Configuration * config
Fawkes configuration.
Definition: plugin.h:58
void set_name(const char *format,...)
Set name of thread.
virtual ~Plugin()
Virtual destructor.
Definition: plugin.cpp:79
Interface for configuration handling.
Definition: config.h:67
virtual bool persistent()
Determines if the plugin can be unloaded.
Definition: plugin.cpp:96