doc/poddoc/module.pod

=head1 Modules

Ermyth has an easy to use module framework. It is rather strict when it comes
to module initialisation but apart from that, you are free to put in anything
you like. It is not recommended to create module dependencies but if you must,
you can use the C<REGISTER_DEPENDENCY> macro to force the system to unload
your module if the module yours depends on is unloaded.

=head2 Writing a module

First, you need the module header

   #include "atheme.h"
   #include <ermyth/module.h>

And the mandatory rcsid line

   static char const rcsid[] = "$Id$";

Then, you register your module with REGISTER_MODULE.

   REGISTER_MODULE ("avada/kedavra", false, "Lord Voldemort");

=over

=item "avada/kedavra"

This is the module name, it is arbitrary and used by the C<loadmodule>
configuration directive to load it.

=item false

A boolean declaring whether or not this module needs to be protected from
unloading. Giving this a true value prohibits unloading.

=item "Lord Voldemort"

The module vendor. This may be a person or a group of programmers. Most
modules in Ermyth have been written by The Ermyth Team and the Atheme
Development Group.

=back

Next, you can put in any other program code you like.

   void
   kill_harry_potter (void *)
   {
     puts ("Avada kedavra!");
   }

Last, you will need to define the initialisation and deinitialisation routines.
_modinit returns C<true> if the module was loaded successfully and C<false> if
it was not. If it was not, its state will be "not loaded" which means, it
cannot be unloaded. Be aware that if your module fails, you will need to
manually clean up and revert changes that _modinit did up to the exit point,
as _moddeinit does not get called on failure.

   bool
   _modinit (module *m)
   {
     puts ("I am going to kill Harry Potter!");

     // Kill harry potter every five minutes
     event_add ("kill potter", kill_harry_potter, NULL, 300);

     // Module loaded successfully
     return true;
   }

   void
   _moddeinit ()
   {
     puts ("Whahaha, I win!");
   }

=head2 Using the module

That's it. Now you have a working module. You can load it in the configuration
with the C<loadmodule> directive:

   loadmodule "avada/kedavra";

=head2 The module API

The modules class provides an interface to the module API.

=over

=item bool modules::provides (char const * const name)

This returns true if the module called C<name> has been registered. Returns
false otherwise.

=item faultcode_t modules::enable (char const * const name)

Enables a module.

Returns C<fault_nosuch_target> if the named module was not registered.

Returns C<fault_nochange> if the module was already loaded.

Returns C<fault_failed> if the module's C<_modinit ()> failed.

Returns C<fault_ok> if the module was enabled successfully.

=item faultcode_t modules::disable (char const * const name)

Disables a module.

Returns C<fault_nosuch_target> if the named module was not registered.

Returns C<fault_nochange> if the module was not loaded.

Returns C<fault_noprivs> if the module is protected.

Returns C<fault_ok> if the module was disabled successfully.

=item module *modules::find (char const * const name)

Returns a pointer to a module struct if the named module was registered.
Returns C<NULL> otherwise.

=item void modules::cleanup ()

Unload all modules and delete their access structures. After this, the module
API will be completely defunct. It is and should only be done on shutdown.

=item REGISTER_MODULE (char const * const name, bool protected, char const * const vendor)

This macro should come after the rcsid line and before the definition of
_modinit and _moddeinit, as it declares these two functions.

=item REGISTER_DEPENDENCY (char const * const thismod, char const * const othermod)

Records a module dependency of thismod => othermod. If othermod gets unloaded,
thismod gets unloaded as well.

=item modules::list_type

This is a typedef of std::vector<module *> that is used for the module list.

=item modules::list_type const &modules::list ()

Returns the vector containing all module access objects. You can iterate over
them like operserv/modlist does but you can not change its contents.

=back
Revision:	1.1
Committed:	Tue Aug 28 17:14:43 2007 UTC (19 years, 1 month ago) by pippijn
Branch:	MAIN
Log Message:	added new files
#	User	Rev	Content
1	pippijn	1.1	=head1 Modules
2
3			Ermyth has an easy to use module framework. It is rather strict when it comes
4			to module initialisation but apart from that, you are free to put in anything
5			you like. It is not recommended to create module dependencies but if you must,
6			you can use the C<REGISTER_DEPENDENCY> macro to force the system to unload
7			your module if the module yours depends on is unloaded.
8
9			=head2 Writing a module
10
11			First, you need the module header
12
13			#include "atheme.h"
14			#include <ermyth/module.h>
15
16			And the mandatory rcsid line
17
18			static char const rcsid[] = "$Id$";
19
20			Then, you register your module with REGISTER_MODULE.
21
22			REGISTER_MODULE ("avada/kedavra", false, "Lord Voldemort");
23
24			=over
25
26			=item "avada/kedavra"
27
28			This is the module name, it is arbitrary and used by the C<loadmodule>
29			configuration directive to load it.
30
31			=item false
32
33			A boolean declaring whether or not this module needs to be protected from
34			unloading. Giving this a true value prohibits unloading.
35
36			=item "Lord Voldemort"
37
38			The module vendor. This may be a person or a group of programmers. Most
39			modules in Ermyth have been written by The Ermyth Team and the Atheme
40			Development Group.
41
42			=back
43
44			Next, you can put in any other program code you like.
45
46			void
47			kill_harry_potter (void *)
48			{
49			puts ("Avada kedavra!");
50			}
51
52			Last, you will need to define the initialisation and deinitialisation routines.
53			_modinit returns C<true> if the module was loaded successfully and C<false> if
54			it was not. If it was not, its state will be "not loaded" which means, it
55			cannot be unloaded. Be aware that if your module fails, you will need to
56			manually clean up and revert changes that _modinit did up to the exit point,
57			as _moddeinit does not get called on failure.
58
59			bool
60			_modinit (module *m)
61			{
62			puts ("I am going to kill Harry Potter!");
63
64			// Kill harry potter every five minutes
65			event_add ("kill potter", kill_harry_potter, NULL, 300);
66
67			// Module loaded successfully
68			return true;
69			}
70
71			void
72			_moddeinit ()
73			{
74			puts ("Whahaha, I win!");
75			}
76
77			=head2 Using the module
78
79			That's it. Now you have a working module. You can load it in the configuration
80			with the C<loadmodule> directive:
81
82			loadmodule "avada/kedavra";
83
84			=head2 The module API
85
86			The modules class provides an interface to the module API.
87
88			=over
89
90			=item bool modules::provides (char const * const name)
91
92			This returns true if the module called C<name> has been registered. Returns
93			false otherwise.
94
95			=item faultcode_t modules::enable (char const * const name)
96
97			Enables a module.
98
99			Returns C<fault_nosuch_target> if the named module was not registered.
100
101			Returns C<fault_nochange> if the module was already loaded.
102
103			Returns C<fault_failed> if the module's C<_modinit ()> failed.
104
105			Returns C<fault_ok> if the module was enabled successfully.
106
107			=item faultcode_t modules::disable (char const * const name)
108
109			Disables a module.
110
111			Returns C<fault_nosuch_target> if the named module was not registered.
112
113			Returns C<fault_nochange> if the module was not loaded.
114
115			Returns C<fault_noprivs> if the module is protected.
116
117			Returns C<fault_ok> if the module was disabled successfully.
118
119			=item module modules::find (char const const name)
120
121			Returns a pointer to a module struct if the named module was registered.
122			Returns C<NULL> otherwise.
123
124			=item void modules::cleanup ()
125
126			Unload all modules and delete their access structures. After this, the module
127			API will be completely defunct. It is and should only be done on shutdown.
128
129			=item REGISTER_MODULE (char const * const name, bool protected, char const * const vendor)
130
131			This macro should come after the rcsid line and before the definition of
132			_modinit and _moddeinit, as it declares these two functions.
133
134			=item REGISTER_DEPENDENCY (char const * const thismod, char const * const othermod)
135
136			Records a module dependency of thismod => othermod. If othermod gets unloaded,
137			thismod gets unloaded as well.
138
139			=item modules::list_type
140
141			This is a typedef of std::vector<module *> that is used for the module list.
142
143			=item modules::list_type const &modules::list ()
144
145			Returns the vector containing all module access objects. You can iterate over
146			them like operserv/modlist does but you can not change its contents.
147
148			=back