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: module.pod,v 1.1 2007-08-28 17:14:43 pippijn Exp $";

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 fault::code 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 fault::code 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.2
Committed:	Thu Aug 30 19:56:18 2007 UTC (19 years, 2 months ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+11 -11 lines
Log Message:	- put faultcodes into their own namespace - removed old files - limited header garbage in atheme.h - macros to inline bools for connection_t::is_* - put some connection_t functions into the connection_t class
#	Content
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: module.pod,v 1.1 2007-08-28 17:14:43 pippijn Exp $";
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 fault::code 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 fault::code 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