Fawkes API  Fawkes Development Version
plugin.h
1 
2 /***************************************************************************
3  * plugin.h - Interface for a Fawkes plugin
4  *
5  * Created: Wed Aug 23 15:19:13 2006
6  * Copyright 2006-2007 Tim Niemueller [www.niemueller.de]
7  *
8  ****************************************************************************/
9 
10 /* This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version. A runtime exception applies to
14  * this software (see LICENSE.GPL_WRE file mentioned below for details).
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Library General Public License for more details.
20  *
21  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22  */
23 
24 #ifndef __CORE_PLUGIN_H_
25 #define __CORE_PLUGIN_H_
26 
27 #include <core/threading/thread_list.h>
28 
29 namespace fawkes {
30 
31 class Configuration;
32 
33 class Plugin {
34  public:
35 
37  virtual ~Plugin();
38 
39  void set_name(const char *name);
40  const char * name() const;
41  ThreadList & threads();
42 
43  virtual bool persistent();
44 
45  protected:
46  /** Thread list member. Initialise this list with the threads that this
47  * plugin will use. These threads must exist for the whole life time of
48  * the thread. Use sleeping threads if you need to turn on and off threads
49  * dynamically. You may not add threads later to the list, as the list
50  * is shortly after the constructor sealed.
51  * @see ThreadList
52  */
54 
55  /** Fawkes configuration. You can use the configuration to add certain threads
56  * depending on the requested feature set. Use it only in your constructor.
57  */
59 
60  private:
61  char *_name_alloc;
62  const char *_name;
63 };
64 
65 /** Plugin loader function for the shared library
66  * Do not use directly, rather use the EXPORT_PLUGIN macro.
67  * @relates fawkes::Plugin
68  */
69 typedef Plugin * (* PluginFactoryFunc) (fawkes::Configuration *);
70 
71 /** Plugin destructor function for the shared library.
72  * Do not use directly, rather use the EXPORT_PLUGIN macro.
73  * @param plugin plugin to destroy
74  * @relates fawkes::Plugin
75  */
76 typedef void (* PluginDestroyFunc) (Plugin *plugin);
77 
78 
79 /** Plugin description function for the shared library.
80  * @return short string describing the plugin.
81  */
82 typedef const char * (* PluginDescriptionFunc) ();
83 
84 /** Plugin depdendency function for the shared library.
85  * @return short string with a comma separated list of plugins that this
86  * plugin depends on.
87  */
88 typedef const char * (* PluginDependenciesFunc) ();
89 
90 
91 /** Plugin factory function for this plugin.
92  * @return an instance of ExamplePlugin
93  */
94 #define PLUGIN_FACTORY(plugin_class) \
95  extern "C" \
96  fawkes::Plugin * \
97  plugin_factory(fawkes::Configuration *config) \
98  { \
99  return new plugin_class(config); \
100  }
101 
102 
103 /** Plugin destruction function for this plugin.
104  * @param plugin The plugin that is to be destroyed. Do not use this plugin
105  * afterwards
106  */
107 #define PLUGIN_DESTROY(plugin_class) \
108  extern "C" \
109  void \
110  plugin_destroy(plugin_class *plugin) \
111  { \
112  delete plugin; \
113  }
114 
115 
116 /** Plugin description.
117  * Use this macro to set a short description of the plugi
118  * @param info_string a short string describing the plugin
119  */
120 #define PLUGIN_DESCRIPTION(info_string) \
121  extern "C" const char _plugin_description[] \
122  __attribute((__section__(".fawkes_plugin"))) \
123  __attribute((__used__)) = info_string; \
124  \
125  extern "C" \
126  const char * \
127  plugin_description() \
128  { \
129  return _plugin_description; \
130  }
131 
132 
133 
134 /** Set plugin dependencies.
135  * @param plugin_list a string with a comma-separated list
136  * of plugins that this plugin depends on.
137  */
138 #define PLUGIN_DEPENDS(plugin_list) \
139  extern "C" const char _plugin_dependencies[] \
140  __attribute((__section__(".fawkes_plugin"))) \
141  __attribute((__used__)) = info_string; \
142  \
143  extern "C" \
144  const char * \
145  plugin_depends() \
146  { \
147  return _plugin_dependencies; \
148  }
149 
150 
151 
152 /** Export plugin.
153  * This will create appropriate plugin factory and destroy functions.
154  */
155 #define EXPORT_PLUGIN(plugin_class) \
156  PLUGIN_FACTORY(plugin_class) \
157  \
158  PLUGIN_DESTROY(plugin_class)
159 
160 
161 } // end namespace fawkes
162 
163 #endif
Plugin interface class.
Definition: plugin.h:33
void set_name(const char *name)
Set plugin name.
Definition: plugin.cpp:122
Fawkes library namespace.
void(* PluginDestroyFunc)(Plugin *plugin)
Plugin destructor function for the shared library.
Definition: plugin.h:76
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
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