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
28#include <cstdlib>
29#include <cstring>
30
31namespace fawkes {
32
33/** @class Plugin <core/plugin.h>
34 * Plugin interface class.
35 * Derive this class to create a new Fawkes plugin. There is not much that
36 * you have to do to get a basic plugin working. The base plugin will already
37 * handle all the important details.
38 *
39 * To implement a plugin create a new class that inherits from Plugin. Call
40 * the Plugin constructor with the proper parameters in your derivate's
41 * constructor. Then in your constructor fill the thread_list member with
42 * the threads that your plugin needs. Instantiate all threads that your
43 * plugin may ever need during its lifetime, creating (blocked timing)
44 * threads during the life time of a plugin is not allowed. After the
45 * constructor the thread list has to be considered to be sealed.
46 * At the end of the file add a line like
47 * @code
48 * EXPORT_PLUGIN(PluginClass)
49 * @endcode
50 * where PluginClass is the class name of your plugin. This will create the
51 * proper glue code to make this class loadable as plugin by Fawkes.
52 *
53 * @see ThreadList
54 *
55 * @ingroup FCL
56 * @author Tim Niemueller
57 */
58
59/* IMPLEMENTOR'S NOTE:
60 * I'm aware that we do not link libfawkescore against libfawkesconfig, so why
61 * do we put the reference to fawkes::Configuration here? Two things to consider:
62 * 1. We only pass through the pointer, nothing more. We do not need to know about
63 * the declaration or definition!
64 * 2. We want to keep plugin.(h|cpp) in libfawkescore, rather than in
65 * libfawkesplugin to keep the minimum requirements for plugins low.
66 */
67
68/** Constructor.
69 * Pass the name of your plugin to this ctor.
70 * @param config configuration
71 */
73{
74 this->config = config;
75 _name_alloc = NULL;
76 _name = "PluginNameNotSet";
77}
78
79/** Virtual destructor */
81{
82 for (ThreadList::iterator i = thread_list.begin(); i != thread_list.end(); ++i) {
83 delete *i;
84 }
85 if (_name_alloc)
86 free(_name_alloc);
87}
88
89/** Determines if the plugin can be unloaded.
90 * This method tells the plugin loader if this plugin can be unloaded. Use
91 * with care. No plugins but core plugins should return true. Only override
92 * this if needed. The default behaviour if not overridden is to return false.
93 * @return true, if the plugin cannot be unloaded, false otherwise. The default
94 * implementation returns false.
95 */
96bool
98{
99 return false;
100}
101
102/** Get a list of threads.
103 * This function shall return a list of threads. See the FawkesThreadManager
104 * for supported special types of threads. This method is called only once
105 * right after the plugin has been initialised. You may not change the
106 * list afterwards by adding or removing threads. Especially you may not delete
107 * the threads!
108 * @return list of threads.
109 */
112{
113 return thread_list;
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 */
121void
122Plugin::set_name(const char *name)
123{
124 if (_name_alloc)
125 free(_name_alloc);
126
128
129 _name_alloc = strdup(name);
130 if (!_name_alloc) {
131 // We do not want to throw an exception here
132 _name = "OutOfMemoryForPluginName";
133 } else {
134 _name = _name_alloc;
135 }
136}
137
138/** Get the name of the plugin.
139 * @return name of the plugin
140 */
141const char *
143{
144 return _name;
145}
146
147} // end namespace fawkes
Interface for configuration handling.
Definition: config.h:68
virtual bool persistent()
Determines if the plugin can be unloaded.
Definition: plugin.cpp:97
void set_name(const char *name)
Set plugin name.
Definition: plugin.cpp:122
Plugin(Configuration *config)
Constructor.
Definition: plugin.cpp:72
ThreadList thread_list
Thread list member.
Definition: plugin.h:53
ThreadList & threads()
Get a list of threads.
Definition: plugin.cpp:111
virtual ~Plugin()
Virtual destructor.
Definition: plugin.cpp:80
Configuration * config
Fawkes configuration.
Definition: plugin.h:58
const char * name() const
Get the name of the plugin.
Definition: plugin.cpp:142
List of threads.
Definition: thread_list.h:56
void set_name(const char *format,...)
Set name of thread.
Fawkes library namespace.