ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/tech/4.html
Revision: 3389
Committed: Fri Apr 25 14:12:15 2014 UTC (9 years, 10 months ago) by michael
Content type: text/html
File size: 53048 byte(s)
Log Message:
- Imported ircservices-5.1.24

File Contents

# Content
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Style-Type" content="text/css"/>
6 <style type="text/css">@import "style.css";</style>
7 <title>IRC Services Technical Reference Manual - 4. Module system</title>
8 </head>
9
10 <body>
11 <h1 class="title" id="top">IRC Services Technical Reference Manual</h1>
12
13 <h2 class="section-title">4. The module system</h2>
14
15 <p class="section-toc">
16 4-1. <a href="#s1">The module concept</a>
17 <br/>4-2. <a href="#s2">Structure of a module</a>
18 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-2-1. <a href="#s2-1">Required symbols</a>
19 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-2-2. <a href="#s2-2">Utility macros and functions</a>
20 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-2-3. <a href="#s2-3">Dynamic versus static modules</a>
21 <br/>4-3. <a href="#s3">Module management</a>
22 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-1. <a href="#s3-1">Module loading</a>
23 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-2. <a href="#s3-2">Module configuration</a>
24 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-3. <a href="#s3-3">Module unloading</a>
25 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-4. <a href="#s3-4">Searching for a module</a>
26 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-5. <a href="#s3-5">Locking a module in memory</a>
27 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-3-6. <a href="#s3-6">Global initialization and cleanup</a>
28 <br/>4-4. <a href="#s4">External symbols</a>
29 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-4-1. <a href="#s4-1">Exporting symbols</a>
30 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-4-2. <a href="#s4-2">Importing symbols</a>
31 <br/>4-5. <a href="#s5">Callbacks</a>
32 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-5-1. <a href="#s5-1">Registering callbacks</a>
33 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-5-2. <a href="#s5-2">Hooking into callbacks</a>
34 <br/>&nbsp;&nbsp;&nbsp;&nbsp;4-5-3. <a href="#s5-3">Calling callbacks</a>
35 <br/>4-6. <a href="#s6">Adding a module to Services</a>
36 </p>
37
38 <p class="backlink"><a href="3.html">Previous section: Communication (socket) handling</a> |
39 <a href="index.html">Table of Contents</a> |
40 <a href="5.html">Next section: IRC server interface</a></p>
41
42 <!------------------------------------------------------------------------>
43 <hr/>
44
45 <h3 class="subsection-title" id="s1">4-1. The module concept</h3>
46
47 <p>The module system was introduced in Services 5.0, partly to allow
48 greater flexibility in configuring Services, partly to simplify the process
49 of extending Services, and partly to help clarify the boundaries between
50 distinct sets of functionality. Rather than merge every conceivable
51 function into a single monolithic program, Services was divided into a
52 comparatively small core and a number of modules which each implemented
53 distinct sets of features. These modules could then be developed
54 separately from the core and from each other, without concern for the
55 effects of changes in other parts of the program.</p>
56
57 <p>Aside from providing a cleaner program structure, modules make it
58 simpler to implement different variations on a particular feature. A good
59 example of this is the protocol modules (discussed in
60 <a href="5.html">section 5</a>); rather than a complex set of <tt>#if</tt>
61 and <tt>#else</tt> directives to handle differences between IRC server
62 types, a separate protocol module can be written for each type of IRC
63 server; this results in a certain amount of code duplication for similar
64 protocols, but makes the code for each protocol much more maintainable, and
65 allows the code for a single protocol to be changed easily without worrying
66 that it will break processing for other protocols.</p>
67
68 <p>Modules also make it easier to add new features to Services, whether as
69 part of the Services package or as third-party additions. By connecting to
70 the Services core and standard modules through a set of well-defined
71 callbacks, no changes need to be made to the main source code when the
72 module is updated, and vice versa. The compilation system (see
73 <a href="10.html#s3-2">section 10-3-2</a>) also makes it easy for users to
74 add modules on their own, by simply "dropping in" the source code for the
75 new module; Services will automatically find the module and compile it.</p>
76
77 <p>Below, <a href="#s2">section 4-2</a> discusses the basic structure of a
78 module, along with other background issues; <a href="#s3">section 4-3</a>
79 discusses how modules are managed, including the details of module loading,
80 configuration, and unloading; <a href="#s4">section 4-4</a> discusses how
81 to make symbols available to other modules and use symbols from other
82 modules; and <a href="#s5">section 4-5</a> covers callbacks.</p>
83
84 <p class="backlink"><a href="#top">Back to top</a></p>
85
86 <!------------------------------------------------------------------------>
87 <hr/>
88
89 <h3 class="subsection-title" id="s2">4-2. Structure of a module</h3>
90
91 <p>From the viewpoint of the Services core, a module is a single unit of
92 functionality with a known interface. The only direct accesses made to
93 module data are to a limited number of functions and variables (as
94 described in <a href="#s2-1">section 4-2-1</a> below); all other module
95 interactions occur through callbacks, which it is the module's
96 responsibility to install as necessary.</p>
97
98 <p>A typical module, therefore, will use its initialization routine (one of
99 the directly-accessed functions) to install callback functions, enabling it
100 to respond to events such as messages from the IRC server or connections on
101 a socket. After performing any other necessary setup actions, the
102 initialization routine returns control to the Services core, which will
103 then call the module's callback functions as appropriate. The bulk of a
104 module is thus usually contained in these callback functions or their
105 helper routines.</p>
106
107 <p class="backlink"><a href="#top">Back to top</a></p>
108
109
110 <h4 class="subsubsection-title" id="s2-1">4-2-1. Required and optional symbols</h4>
111
112 <p>Modules are required to define two variables, used by the module loader:
113 <b><tt>int32&nbsp;module_version</tt></b>, initialized to the value
114 of the macro <tt>MODULE_VERSION_CODE</tt>, and
115 <b><tt>Module&nbsp;**_this_module_ptr</tt></b>, a pointer to a variable
116 which will receive the module's handle (see <a href="#s3">section 4-3</a>
117 for information on module handles). However, both of these variables are
118 normally defined by <tt>modules.h</tt> when compiling the module's main
119 file (the source file with the same base name as the module object file),
120 so ordinarily there is no need to be concerned about these variables.</p>
121
122 <p>Modules may optionally define two functions, which the module loader
123 will call when the module is loaded and unloaded, respectively:</p>
124
125 <dl>
126 <dt><tt>int <b>init_module</b>()</tt></dt>
127 <dd>Performs any initialization operations necessary for the module,
128 returning nonzero on success, zero on failure. This function is
129 called during the module loading process (see
130 <a href="#s3-1">section 4-3-1</a>); if it returns failure, the
131 module load is aborted.</dd>
132
133 <dt><tt>int <b>exit_module</b>(int <i>shutdown</i>)</tt></dt>
134 <dd>Performs any cleanup operations necessary for the module. If
135 <tt><i>shutdown</i></tt> is zero, then the function is being called
136 for an unload operation during normal program processing; if
137 <tt>exit_module()</tt> returns zero, then the unload is aborted (a
138 nonzero return value indicates permission to unload the module).
139 If <tt><i>shutdown</i></tt> is nonzero, then the function is being
140 called because the program is shutting down; in this case, the
141 function must perform all necessary shutdown operations (returning
142 zero to cancel the unload is not permitted). <i>Implementation
143 note: The <tt><i>shutdown</i></tt> parameter was included primarily
144 for the protocol modules, due to some shortcuts taken on the
145 assumption that only one protocol module would be used during any
146 given execution.</i></dd>
147 </dl>
148
149 <p>Modules may also optionally define
150 <b><tt>ConfigDirective&nbsp;module_config[]</tt></b> (this must be an
151 array, not a pointer), containing configuration information for the module
152 which will be processed by the module loader. The use of this array is
153 described in <a href="#s3-2">section 4-3-2</a>.</p>
154
155 <p class="backlink"><a href="#top">Back to top</a></p>
156
157
158 <h4 class="subsubsection-title" id="s2-2">4-2-2. Utility macros and functions</h4>
159
160 <p>The header file <tt>modules.h</tt>, which must be included by all module
161 source files, includes a few macros for convenience in writing modules:</p>
162
163 <dl>
164 <dt><tt><b>THIS_MODULE</b></tt></dt>
165 <dd>Evaluates to the module handle for this module. This can be used,
166 for example, if a module wants to pass its handle explicitly to
167 another module, but it is more commonly used by other macros in
168 <tt>modules.h</tt> to automatically pass the module's handle to
169 various module-related routines (see below).</dd>
170
171 <dt><tt><b>MODULE_NAME</b></tt></dt>
172 <dd>Evaluates to a string containing the module's name; the value
173 should be treated as constant but not literal. (Internally, it is
174 simply the result of <tt>get_module_name(THIS_MODULE)</tt>.)</dd>
175
176 <dt><tt><b>MODULE_VERSION_CODE</b></tt></dt>
177 <dd>Evaluates to a numeric code indicating the Services version number.
178 The version number consists of four parts: major version number,
179 minor version number, release status (alpha, beta/prerelease, or
180 final), and release number. These are passed to the macro to
181 produce a number indicating the version, where greater values
182 indicate later versions. For example:
183 <div class="code"> MODULE_VERSION_CODE(5,0,MODULE_VERSION_FINAL,4)
184 &lt; MODULE_VERSION_CODE(5,1,MODULE_VERSION_ALPHA,3)
185 &lt; MODULE_VERSION_CODE(5,1,MODULE_VERSION_BETA,2)
186 &lt; MODULE_VERSION_CODE(5,1,MODULE_VERSION_FINAL,1)</div>
187 because version 5.0 is earlier than version 5.1, alpha releases
188 are earlier than beta releases, and beta releases are earlier than
189 final releases. (These values correspond to the versions 5.0.4,
190 5.1a3, 5.1pre2, and 5.1.1 respectively.) While this value is
191 primarily used to set the <tt>module_version</tt> required
192 variable, as described above, it can also be used in conditional
193 compilation when compatibility with multiple versions of Services
194 is desired.</dd>
195 </dl>
196
197 <p>In addition, many of the routines described in this section take a
198 <tt><i>module</i></tt> or <tt><i>caller</i></tt> parameter, so that the
199 module subsystem knows which module is making the call; however, macros are
200 used to hide this parameter from the module source code, both to improve
201 readability of the code and to avoid potential errors from passing the
202 wrong parameter. These functions are:</p>
203 <ul>
204 <li><tt>add_callback()</tt> (and <tt>add_callback_pri()</tt>)</li>
205 <li><tt>call_callback()</tt> (and variations)</li>
206 <li><tt>module_log()</tt> (and variations; declared in <tt>log.h</tt>)</li>
207 <li><tt>register_callback()</tt></li>
208 <li><tt>remove_callback()</tt></li>
209 <li><tt>unregister_callback()</tt></li>
210 <li><tt>unuse_module()</tt></li>
211 <li><tt>use_module()</tt></li>
212 </ul>
213
214 <p class="backlink"><a href="#top">Back to top</a></p>
215
216
217 <h4 class="subsubsection-title" id="s2-3">4-2-3. Dynamic versus static modules</h4>
218
219 <p>It is possible for modules to be compiled either <i>dynamically</i>, so
220 that the module is loaded into memory only when used, or <i>statically</i>,
221 building all modules into the main executable file. The decision of which
222 to use is made by the user via the <tt>configure</tt> script, and cannot be
223 controlled by individual modules. In general, modules will behave exactly
224 the same whether compiled dynamically or statically; however, it is
225 important to be aware of particular behaviors with each method, to avoid
226 problems that cause the module to fail when using one method or the other.</p>
227
228 <p><i>Dynamic linking</i> involves compiling each module into an
229 independent loadable object file, which is then loaded into memory as
230 needed using the system's <tt>dlopen()</tt> family of functions. (If
231 these functions are not available, dynamic modules cannot be used; the
232 <tt>configure</tt> script will detect this and select static modules
233 automatically.) Any direct references to symbols not defined in the
234 module, such as core Services routines, will be marked as unresolved
235 references in the object file. As a result, it is possible to compile a
236 module that references a nonexistent symbol&mdash;for example, accidentally
237 typing <tt>str<b>mc</b>p</tt> instead of <tt>str<b>cm</b>p</tt>&mdash;and
238 the error will not be detected until an attempt is made to load the module.</p>
239
240 <p><i>Static linking</i>, on the other hand, results in every module being
241 linked together with the core code to produce a single executable file.
242 This means that every symbol in the Services core&mdash;and in other
243 modules&mdash;will be available for use. Static linking can detect
244 references to nonexistent symbols at compile time, unlike dynamic linking,
245 but will not generate an error if one module references a symbol from
246 another. For example, if a protocol module erroneously references a symbol
247 from one of the pseudoclients directly (rather than using the symbol lookup
248 method described in <a href="#s4-2">section 4-4-2</a>), the protocol module
249 will fail to load when using dynamic linking unless the appropriate
250 pseudoclient module is loaded first. (Since the current design of Services
251 requires that a protocol module be loaded first, this would result in
252 Services not being able to run at all.)</p>
253
254 <p>When using modules composed of two or more source files that share
255 internal-use symbols, static linking can cause spurious errors at link
256 time. This is because, even though the symbols are only used internally,
257 they are still included in the final object file for the module; thus, if
258 two separate modules happen to use the same name for a function or
259 variable, the final link will report a "duplicate symbol" error. This is
260 an actual problem with the NickServ and ChanServ modules, both of which
261 include various internal utility routines in a separate source file, and as
262 a result some ChanServ routines have to be renamed (see
263 <a href="7.html#s4-1-1-rename">the relevant part of section 7-4-1-1</a>).</p>
264
265 <p>Additionally, when using static linking, module-global variables will
266 always retain their values between a module unload and a subsequent module
267 load; when using dynamic linking, it is system-dependent whether the values
268 will be retained or reset to their initial values. Thus it is important
269 that a module's cleanup routine not only free all resources used by the
270 module, but also reset all variables to appropriate values for the next
271 call to the initialization routine.</p>
272
273 <p>For these reasons, it is best to test modules using both dynamic and
274 static linking, to ensure that unintended errors are not introduced.</p>
275
276
277 <p class="backlink"><a href="#top">Back to top</a></p>
278
279 <!------------------------------------------------------------------------>
280 <hr/>
281
282 <h3 class="subsection-title" id="s3">4-3. Module management</h3>
283
284 <p>The module subsystem uses the routines described in this section to
285 manage modules, performing loading, configuration and unloading as well as
286 checking whether a module is loaded or locking modules into memory.</p>
287
288 <p>Most module subsystem routines take or return a <i>module handle</i>, a
289 value of type <tt>Module&nbsp;*</tt>, to identify a particular module. The
290 <tt>Module</tt> type is declared as simply <tt>struct Module_</tt> in
291 <tt>modules.h</tt>, rendering the type opaque to callers. Internally,
292 <tt>struct Module_</tt> is used to hold information about each loaded
293 module, and has the following fields:</p>
294
295 <dl>
296 <dt><tt>Module *<b>next</b>, *<b>prev</b></tt></dt>
297 <dd>Used to maintain the linked list of loaded modules.</dd>
298
299 <dt><tt>char *<b>name</b></tt></dt>
300 <dd>The module's name, set to the pathname used to load the module (for
301 example, "<tt>nickserv/main</tt>").</dd>
302
303 <dt><tt>ConfigDirective *<b>modconfig</b></tt></dt>
304 <dd>The value of the symbol <tt>module_config</tt> in this module, or
305 <tt>NULL</tt> if the <tt>module_config</tt> symbol does not exist.</dd>
306
307 <dt><tt>Module ***<b>this_module_pptr</b></tt></dt>
308 <dd>The value of the symbol <tt>_this_module_ptr</tt> in this module.
309 (This is the <i>address</i> of the <tt>_this_module_ptr</tt>
310 variable, which itself is a pointer to a variable of type
311 <tt>Module&nbsp;*</tt>, so the type of this field is
312 <tt>Module&nbsp;***</tt>.)</dd>
313
314 <dt><tt>const int32 *<b>module_version_ptr</b></tt></dt>
315 <dd>The value of the symbol <tt>module_version</tt> in this module
316 (again, the address of the variable, not its value).</dd>
317
318 <dt><tt>void *<b>dllhandle</b></tt></dt>
319 <dd>The handle returned by the system <tt>dlopen()</tt> function. For
320 static linking, this instead points to an internal structure with
321 the module data.</dd>
322
323 <dt><tt>CallbackList *<b>callbacks</b></tt>
324 <br/><tt>int <b>callbacks_count</b></tt></dt>
325 <dd>A variable-length array containing the callbacks registered by this
326 module.</dd>
327
328 <dt><tt>const Module **<b>users</b></tt>
329 <br/><tt>int <b>users_count</b></tt></dt>
330 <dd>A variable-length array containing handles of modules which have
331 called <tt>use_module()</tt> for this module.</dd>
332 </dl>
333
334 <p>Loaded modules are kept as a doubly-linked list, with the list head in
335 the file-scope variable <tt>modulelist</tt>. This list always contains at
336 least one entry: a dummy entry for the Services core, defined in the
337 variable <tt>coremodule</tt>.</p>
338
339 <p>The module management routines are:</p>
340
341 <dl>
342 <dt><tt>Module *<b>load_module</b>(const char *<i>modulename</i>)</tt></dt>
343 <dd>Loads the given module and returns a pointer to its module handle,
344 or <tt>NULL</tt> on failure. Described in <a href="#s3-1">section
345 4-3-1</a>.</dd>
346
347 <dt><tt>int <b>unload_module</b>(Module *<i>module</i>)</tt></dt>
348 <dd>Unloads the given module. Returns nonzero if the module was
349 successfully unloaded, zero if not. Described in
350 <a href="#s3-3">section 4-3-3</a>.</dd>
351
352 <dt><tt>Module *<b>find_module</b>(const char *<i>modulename</i>)</tt></dt>
353 <dd>Returns a handle for the module whose name is given by
354 <tt><i>modulename</i></tt>. If no such module has been loaded,
355 returns <tt>NULL</tt>. Described in <a href="#s3-4">section
356 4-3-4</a>.</dd>
357
358 <dt><tt>void <b>use_module</b>(Module *<i>module</i>)</tt></dt>
359 <dd>Marks the given module as "in use", preventing it from being
360 unloaded. Described in <a href="#s3-5">section 4-3-5</a>.</dd>
361
362 <dt><tt>void <b>unuse_module</b>(Module *<i>module</i>)</tt></dt>
363 <dd>Releases the lock on a module set by <tt>use_module()</tt>.
364 Described in <a href="#s3-5">section 4-3-5</a>.</dd>
365
366 <dt><tt>void <b>modules_init</b>()</tt></dt>
367 <dd>Initializes the module subsystem. Described in
368 <a href="#s3-6">section 4-3-6</a>.</dd>
369
370 <dt><tt>void <b>modules_cleanup</b>()</tt></dt>
371 <dd>Shuts down the module subsystem. Described in
372 <a href="#s3-6">section 4-3-6</a>.</dd>
373 </dl>
374
375 <p class="backlink"><a href="#top">Back to top</a></p>
376
377
378 <h4 class="subsubsection-title" id="s3-1">4-3-1. Module loading</h4>
379
380 <p>A module can be loaded by calling the <tt>load_module()</tt> routine.
381 This routine takes a single parameter, a string giving the name of the
382 module to load (such as "nickserv/main"), and returns the handle for the
383 newly-loaded module or <tt>NULL</tt> on failure. The routine:</p>
384
385 <ul>
386 <li class="spaced">Calls <tt>internal_load_module()</tt> to load the module
387 into memory. This helper routine takes care of performing the
388 actual module load (or lookup, when modules are linked statically)
389 and filling in the <tt>Module</tt> structure; see below for
390 details.</li>
391
392 <li class="spaced">Links the new <tt>Module</tt> structure into the loaded
393 module list.</li>
394
395 <li class="spaced">Calls the core's <tt>configure()</tt> routine to
396 configure module settings; see <a href="#s3-2">section 4-3-2</a>
397 for details.</li>
398
399 <li class="spaced">Calls <tt>internal_init_module()</tt> to perform module
400 initialization. This returns nonzero (success) if the module's
401 initialization function, <tt>module_init()</tt>, returns success
402 (or does not exist).</li>
403
404 <li class="spaced">Calls the "<tt>load module</tt>" callback, a module
405 callback (see <a href="#s5">section 4-5</a>) used to signal that a
406 new module has been loaded.</li>
407
408 <li class="spaced">Finally, performs a check to ensure that a valid
409 protocol module is loaded. This is a kludge to ensure that a
410 protocol module is loaded before any other modules, since some
411 modules alter their initialization behavior depending on the
412 protocol in use. See also <a href="5.html#s1">section 5-1</a>.</li>
413 </ul>
414
415 <p>The actual low-level work of loading the module and initializing the
416 <tt>Module</tt> structure is handled by the <tt>internal_load_module()</tt>
417 helper routine mentioned above. This routine:</p>
418
419 <ul>
420 <li class="spaced">Ensures that the name given (which, when using dynamic
421 linking, becomes part of the file pathname) does not contain
422 <tt>../</tt>", to avoid attempts by malicious code to access files
423 outside the Services data directory.</li>
424
425 <li class="spaced">Checks whether the module has already been loaded,
426 returning an error if so.</li>
427
428 <li class="spaced">Calls <tt>my_dlopen()</tt> (see below) to actually load
429 the module into memory.</li>
430
431 <li class="spaced">Allocates a new <tt>Module</tt> structure, filling in
432 the system module handle and module name.</li>
433
434 <li class="spaced">Looks up the <tt>_this_module_ptr</tt> symbol in the
435 module, returning an error if the symbol is not found, and stores
436 the symbol's value in the <tt>this_module_pptr</tt> field of the
437 <tt>Module</tt> structure. The variable pointed to by
438 <tt>_this_module_ptr</tt> is then set to the module handle,
439 allowing the <tt>THIS_MODULE</tt> macro to work.
440
441 <p>To perform the lookup, <tt>internal_load_module()</tt> first
442 calls <tt>check_module_symbol()</tt> to get the symbol value.
443 Then, if dynamic linking is in use, the returned value is checked
444 the <tt>this_module_pptr</tt> field of each module in the loaded
445 module list to see whether the same address has been used for a
446 different module. This latter check is required because of a
447 problem (on some systems) with the system function
448 <tt>dlsym()</tt>, used for looking up symbols when dynamic linking
449 is in use: if the requested symbol is not present in the requested
450 module but is present in another module, <tt>dlsym()</tt> may
451 return the symbol from the other module (see <a href="#s4-2">section
452 4-4-2</a> for details).</p>
453
454 <p>Note that the implementation used with static linking does not
455 have this problem, rendering the check unnecessary. In fact,
456 attempting to perform the check with static linking can actually
457 cause problems on some systems. This is due to constant merging
458 performed by linkers, which results in distinct modules
459 legitimately having the same value for such a symbol. This has
460 been observed with the <tt>module_version</tt> symbol (see below),
461 so the check is disabled when static linking is in use.</p></li>
462
463 <li class="spaced">Looks up the <tt>module_version</tt> symbol in the
464 module, returning an error if the symbol is not found or the 32-bit
465 value that it points to does not match the value of the
466 <tt>MODULE_VERSION_CODE</tt> macro, and stores the symbol value
467 (variable address) in the <tt>module_version_ptr</tt> field of the
468 <tt>Module</tt> structure.</li>
469
470 <li class="spaced">Looks up the <tt>module_config</tt> symbol in the
471 module, setting the <tt>modconfig</tt> field of the <tt>Module</tt>
472 structure to the symbol's value (or <tt>NULL</tt> if the symbol is
473 not found).</li>
474
475 <li class="spaced">Returns the new <tt>Module</tt> structure.</li>
476 </ul>
477
478 <p>The <tt>my_dlopen()</tt> function referred to above is one of four
479 wrappers for the system dynamic linking functions: <tt>dlopen()</tt>,
480 <tt>dlclose()</tt>, <tt>dlsym()</tt>, and <tt>dlerror()</tt>. When using
481 dynamic linking, the wrapper functions essentially just call their system
482 counterparts, although <tt>my_dlopen()</tt> generates the actual pathname
483 from the module name (prepending the module directory pathname and
484 appending the shared object extension "<tt>.so</tt>"), and
485 <tt>my_dlsym()</tt> includes workarounds for systems that prepend symbol
486 names with underscores and that do not handle <tt>dlsym(NULL,...)</tt>.
487 When static linking is in use, the wrapper functions instead search through
488 the pregenerated module and symbol lists for the requested module or symbol
489 (<tt>dlclose()</tt> does nothing, and <tt>dlerror()</tt> uses a static
490 error message variable to hold the value to return). See
491 <a href="10.html#s3-2">section 10-3-2</a>) for details on the generation of
492 these lists.</p>
493
494 <p>Note that <tt>load_module()</tt> (and its counterpart,
495 <tt>unload_module()</tt>) are only intended to be called by the Services
496 core to load modules specified by <tt>LoadModule</tt> directives in
497 <tt>ircservices.conf</tt>. Modules should never attempt to load other
498 modules on their own, since the user may have intentionally chosen not to
499 load certain modules; instead, an error should be generated if a required
500 module is not available.</p>
501
502 <p class="backlink"><a href="#top">Back to top</a></p>
503
504
505 <h4 class="subsubsection-title" id="s3-2">4-3-2. Module configuration</h4>
506
507 <p>Configuration of modules is performed through the same routine,
508 <tt>configure()</tt>, that handles the Services core configuration;
509 however, a different file is used, <tt>modules.conf</tt> rather than
510 <tt>ircservices.conf</tt>, and each module's configuration directives must
511 be enclosed by the <tt>Module</tt> and <tt>EndModule</tt> meta-directives.
512 (Configuration files and the <tt>configure()</tt> routine are described in
513 detail in <a href="2.html#s3-2">section 2-3-2</a>.)</p>
514
515 <p>Each module can define configuration directives to be parsed by the
516 configuration file reader by creating an array of <tt>ConfigDirective</tt>
517 entries named <tt>module_config</tt>. <tt>load_module()</tt> will check
518 for this symbol and, if found, pass it to <tt>configure()</tt>, as
519 described above; thus, the variables corresponding to the configuration
520 directives will have already been set when the module's
521 <tt>init_module()</tt> function is called. The directives will likewise be
522 reprocessed automatically during reconfiguration; however, it may be
523 necessary for the module to detect changes in configuration variables (such
524 as the nickname of a pseudoclient). For this purpose, the module can hook
525 into the "<tt>reconfigure</tt>" callback, which is called once before
526 reconfiguration takes place and once after (see
527 <a href="c.html#s2">appendix C</a> for details on the callback).</p>
528
529 <p>All configuration variables will be reset to their initial values when
530 the module is unloaded, so the module's <tt>exit_module()</tt> routine does
531 not need to take any particular actions with respect to such variables.</p>
532
533 <p class="backlink"><a href="#top">Back to top</a></p>
534
535
536 <h4 class="subsubsection-title" id="s3-3">4-3-3. Module unloading</h4>
537
538 <p>Loaded modules are unloaded from memory with the <tt>unload_module()</tt>
539 routine. This routine, which is implemented in a separate
540 <tt>internal_unload_module()</tt> routine to allow passing a
541 <tt><i>shutdown</i></tt> parameter to the module's cleanup function,
542 performs the reverse of <tt>load_module()</tt>'s operations, returning
543 nonzero if the module is successfully unloaded, zero if not. The routine:</p>
544
545 <ul>
546 <li class="spaced">Checks whether the module is in use (locked) by another
547 module (see <a href="#s3-5">section 4-3-5</a>), returning failure
548 if so.</li>
549
550 <li class="spaced">Calls the module's <tt>exit_module()</tt> function (if
551 it exists) with a parameter of zero, indicating that the unload
552 request is explicit rather than part of the program shutdown
553 process. The unload fails if the function returns zero
554 (failure).</li>
555
556 <li class="spaced">Removes the module from the global module list, ensuring
557 that other modules cannot access it during the unload procedure
558 (particularly when the "<tt>unload module</tt>" callback is
559 called).</li>
560
561 <li class="spaced">Checks that the module has not left any other modules in
562 a locked state, by calling <tt>use_module()</tt> without a
563 corresponding <tt>unuse_module()</tt> (see <a href="#s3-5">section
564 4-3-5</a>). If it has, a warning message is logged and the
565 offending locks are removed.</li>
566
567 <li class="spaced">Checks that the module has not left any callback
568 functions hooked into other modules' (or the core's) callbacks. If
569 it has, a warning message is logged and the offending functions are
570 removed.</li>
571
572 <li class="spaced">Checks that the module has not left any callbacks of its
573 own registered. If it has, a warning message is logged and the
574 offending callbacks are removed.</li>
575
576 <li class="spaced">Calls the "<tt>unload module</tt>" callback, passing the
577 handle for the module that is being unloaded.</li>
578
579 <li class="spaced">Calls <tt>deconfigure()</tt> for the module's
580 configuration directives (if any), restoring configuration
581 variables to their original values.</li>
582
583 <li class="spaced">Frees resources used by the <tt>Module</tt> structure,
584 and calls <tt>my_dlclose()</tt> to unload the module at the system
585 level.</li>
586 </ul>
587
588 <p>Aside from <tt>unload_module()</tt>, modules are also unloaded during
589 the shutdown process (see <a href="#s3-6">section 4-3-6</a>).</p>
590
591 <p class="backlink"><a href="#top">Back to top</a></p>
592
593
594 <h4 class="subsubsection-title" id="s3-4">4-3-4. Searching for a module</h4>
595
596 <p>If one module needs to access another, it can do so with the
597 <tt>find_module()</tt> routine. This routine takes a module name as
598 parameter, searches through the loaded module list for a module whose name
599 exactly matches the given name (case-sensitively), and returns the handle
600 for that module (<tt>NULL</tt> if no matching module is found).</p>
601
602 <p><tt>find_module()</tt> is used most commonly when one module wants to
603 use functionality provided by another; for example, the module implementing
604 the ChanServ pseudoclient (<tt>chanserv/main</tt>) uses it to retrieve the
605 handle for the NickServ module (<tt>nickserv/main</tt>). Note, however,
606 that in cases where the module being searched for is not required, it may
607 not be present at initialization time; in this case, it is better to hook
608 into the core's "<tt>load module</tt>" and "<tt>unload module</tt>"
609 callbacks, and only use <tt>find_module()</tt> to check whether the desired
610 module has already been loaded when <tt>init_module()</tt> is called. For
611 example, the MemoServ module, <tt>memoserv/main</tt>, takes this approach
612 with respect to the <tt>chanserv/main</tt> module when deciding whether to
613 enable channel memos.</p>
614
615 <p class="backlink"><a href="#top">Back to top</a></p>
616
617
618 <h4 class="subsubsection-title" id="s3-5">4-3-5. Locking a module in memory</h4>
619
620 <p>If one module requires another in order to function properly, the
621 "user" module can request that the "used" module not be unloaded. This is
622 accomplished by calling the <tt>use_module()</tt> routine, passing the
623 "used" module as the <tt><i>module</i></tt> parameter; this causes the
624 specified module to be locked in memory. When the module is no longer
625 needed (for example, when the "user" module's <tt>exit_module()</tt>
626 routine is being called for unloading), <tt>unuse_module()</tt> unlocks the
627 module, allowing it to be unloaded normally.</p>
628
629 <p>One problem that can arise when locking resources is the case of a
630 circular lock dependency: if module A has locked module B, but module B has
631 also locked module A, then neither of them can be unloaded until one or the
632 other module releases its lock; if the modules only release their locks at
633 cleanup time, there would be no way to unload them. In order to prevent
634 situations like this, <tt>use_module()</tt> checks for such circular
635 dependencies and issues a warning if one is detected (in the form of a
636 "BUG" message written to the log file). Naturally, it is also not
637 permitted for a module to attempt to lock itself.</p>
638
639 <p>Note that both of these routines are internally named with a preceding
640 underscore (<tt>_use_module()</tt>, <tt>_unuse_module()</tt>) and take a
641 second parameter, <tt>const Module *<i>caller</i></tt>, which is used to
642 ensure that modules do not leave stale locks around when they are unloaded
643 (as described in <a href="#s3-3">section 4-3-3</a>). However, these are
644 hidden by macros which automatically pass <tt>THIS_MODULE</tt> as the
645 <tt><i>caller</i></tt> parameter.</p>
646
647 <p class="backlink"><a href="#top">Back to top</a></p>
648
649
650 <h4 class="subsubsection-title" id="s3-6">4-3-6. Global initialization and cleanup</h4>
651
652 <p>Before calling any module-related routines, the module subsystem must be
653 initialized by calling <tt>modules_init()</tt>, which obtains the system
654 handle for the program itself (when using dynamic linking) and sets up the
655 three module subsystem callbacks: "<tt>load module</tt>",
656 "<tt>reconfigure</tt>", and "<tt>unload module</tt>".</p>
657
658 <p>Likewise, the <tt>modules_cleanup()</tt> routine must be called when the
659 program shuts down. Aside from removing the callbacks mentioned above,
660 <tt>modules_cleanup()</tt> checks that other parts of the Services core
661 have removed any callbacks they registered, and calls the internal routine
662 <tt>unload_all_modules()</tt> to walk the loaded module list and unload
663 each module. In this case, each module's <tt>exit_module()</tt> function
664 is called with a nonzero <tt><i>shutdown</i></tt> value, indicating that
665 the program is shutting down and the module must clean up after itself.
666 (The module will be unloaded regardless of the return value of
667 <tt>exit_module()</tt>.)</p>
668
669 <p class="backlink"><a href="#top">Back to top</a></p>
670
671 <!------------------------------------------------------------------------>
672 <hr/>
673
674 <h3 class="subsection-title" id="s4">4-4. External symbols</h3>
675
676 <p>While some modules only require Services core functions to operate, most
677 interact with other modules. This necessitates a way of accessing
678 functions and data provided by outside modules.</p>
679
680 <p class="backlink"><a href="#top">Back to top</a></p>
681
682
683 <h4 class="subsubsection-title" id="s4-1">4-4-1. Exporting symbols</h4>
684
685 <p>A module can designate certain symbols (functions or variables) to be
686 exported, so that other modules can access them as described in the next
687 section. This is done using one of three macros, depending on what is
688 being exported:</p>
689
690 <ul>
691 <li><b><tt>EXPORT_FUNC(<i>symbol</i>)</tt></b> (for functions)</li>
692 <li><b><tt>EXPORT_VAR(<i>type</i>,<i>symbol</i>)</tt></b> (for ordinary
693 variables)</li>
694 <li><b><tt>EXPORT_ARRAY(<i>eltype</i>,<i>symbol</i>)</tt></b> (for arrays;
695 <tt><i>eltype</i></tt> is the type of an element of the array)</li>
696 </ul>
697
698 <p>These macros do not expand to anything themselves, but are used by the
699 compilation process (see <a href="10.html#s3-2">section 10-3-2</a>) to
700 generate lists of exported symbols when using static linking. Even without
701 these macros, the symbols will still (if not declared <tt>static</tt>) be
702 recorded in the object file, but since there is no way to access the
703 program's symbols when using static linking&mdash;and in fact, the symbols
704 may have been stripped from the executable file by the user&mdash;the
705 macros must be used in order for <tt>get_module_symbol()</tt> (see
706 <a href="#s4-2">section 4-4-2</a> below) to be able to retrieve the
707 symbol's value.</p>
708
709 <p>Note that the symbols used by the module subsystem
710 (<tt>module_version</tt> and so on, as described in <a href="#s2-1">section
711 4-2-1</a>) are automatically made available to the module subsystem, and
712 need not be explicitly exported. This is done by the <tt>Makefile</tt>
713 controlling module compilation, as described in
714 <a href="10.html#s3-2">section 10-3-2</a>.</p>
715
716 <p class="backlink"><a href="#top">Back to top</a></p>
717
718
719 <h4 class="subsubsection-title" id="s4-2">4-4-2. Importing symbols</h4>
720
721 <p>There are two methods of accessing symbols located in other modules: by
722 calling <tt>get_module_symbol()</tt> or <tt>check_module_symbol()</tt>, or
723 by referencing the symbol directly. Each has its benefits and
724 disadvantages.</p>
725
726 <p><tt>get_module_symbol()</tt> and <tt>check_module_symbol()</tt> allow a
727 caller to retrieve the value of a given symbol in a specified (or any)
728 module. The functions are declared as follows (note that
729 <tt>get_module_symbol()</tt> is declared internally as
730 <tt>_get_module_symbol()</tt> and takes a hidden <tt><i>caller</i></tt>
731 parameter, but these are hidden by a macro in <tt>modules.h</tt>):</p>
732
733 <div class="code">void *<b>get_module_symbol</b>(Module *<i>module</i>,
734 const char *<i>symname</i>)
735 int <b>check_module_symbol</b>(Module *<i>module</i>,
736 const char *<i>symname</i>,
737 void **<i>resultptr</i>,
738 const char **<i>errorptr</i>)</div>
739
740 <p>Both of these functions retrieve the value of the symbol
741 <tt><i>symname</i></tt> in the module <tt><i>module</i></tt>; if
742 <tt><i>module</i></tt> is <tt>NULL</tt>, the symbol is searched for in all
743 loaded modules (if defined in more than one module, then an arbitrary
744 module is used for the lookup). If the symbol is not defined in
745 <tt><i>module</i></tt> but is defined in another module, then the result of
746 the lookup is defined to be either <tt>NULL</tt> or the value of the symbol
747 in the module in which it is defined. This undesirable behavior
748 unfortunately cannot be avoided due to identical behavior by (at least) the
749 glibc library used on Linux. When using static linking, the functions
750 always return <tt>NULL</tt> for this case.</p>
751
752 <p>The difference between their two functions is how they deal with the
753 case of a nonexistent symbol. <tt>get_module_symbol()</tt> is intended for
754 use when the symbol is assumed to exist; it returns the symbol's value
755 directly if it exist, and logs a warning and returns <tt>NULL</tt>
756 otherwise. The danger of using this for symbols that may legitimately not
757 exist (other than generating spurious log messages) is that it is possible
758 for a symbol to have the value zero (<tt>NULL</tt>), which would be
759 indistinguishable from a symbol lookup failure.
760 <tt>check_module_symbol()</tt>, on the other hands, takes two extra
761 parameters, a pointer to a variable in which the result is to be stored
762 on success and a pointer to a variable in which the relevant error message
763 is to be stored on failure (either or both of which may be <tt>NULL</tt>),
764 and returns nonzero on success, zero on failure. On success, the variable
765 pointed to by <tt><i>resultptr</i></tt> is set to the value of the pointer,
766 and the variable pointed to by <tt><i>errorptr</i></tt> is left unchanged;
767 on failure, the variable pointed to by <tt><i>errorptr</i></tt> is set to a
768 human-readable error string, and the variable pointed to by
769 <tt><i>resultptr</i></tt> is left unchanged.</p>
770
771 <p>Note that the "value of the symbol" here is the value in linker terms;
772 in other words, when using these functions to access a variable, the value
773 of the symbol is the <i>address</i> of the variable, not its value. To
774 access the value of the <tt>s_NickServ</tt> string variable in an
775 unspecified module, for example, one would write code like:</p>
776
777 <div class="code">char **p_s_NickServ = get_module_symbol(NULL, "s_NickServ");
778 if (p_s_NickServ) {
779 notice(*p_s_NickServ, user->nick, "message");
780 } else {
781 /* Unable to resolve s_NickServ */
782 }</div>
783
784 <p>It is also important to keep in mind that the value of such variables
785 may change, or the module containing the variable may be unloaded, at any
786 time. Accesses should therefore always be done by looking up the symbol,
787 ensuring that the symbol exists, and referencing it through the returned
788 pointer. Since this can incur significant overhead, however, another
789 option (when the module name is known) is to use the "<tt>load module</tt>"
790 and "<tt>unload module</tt>" callbacks to watch for the module to be loaded
791 or unloaded; a single <tt>get_module_symbol()</tt> or
792 <tt>check_module_symbol()</tt> will then suffice, and the returned variable
793 pointer can be saved locally until the module is later unloaded. Many of
794 the modules distributed with Services take this approach.</p>
795
796 <p>The other method of accessing symbols in other modules is to simply
797 reference the symbol as if it was an ordinary external variable or
798 function. Doing this avoids the overhead of looking up the symbol every
799 time it is to be used, or monitoring the relevant module for loads and
800 unloads. However, it also requires the module containing the symbol to be
801 loaded before the module that uses it; if the modules are not loaded in the
802 correct order, <tt>load_module()</tt> will report an "unresolved symbol"
803 error. For example, if module A exports a symbol <tt>symA</tt> which
804 module B accesses directly, attempting to load module B before module A
805 will cause an "unresolved symbol" error for <tt>symA</tt>, without giving
806 module B a chance to manually resolve the symbol. As a general rule,
807 therefore, it is recommended to avoid direct references to symbols from
808 other modules, unless the other module can be reasonably expected to be
809 loaded first (for example, many of the pseudoclients' sub-modules access
810 symbols from their respective core modules in this fashion).</p>
811
812 <p class="backlink"><a href="#top">Back to top</a></p>
813
814 <!------------------------------------------------------------------------>
815 <hr/>
816
817 <h3 class="subsection-title" id="s5">4-5. Callbacks</h3>
818
819 <p><i>Callbacks</i> are a method of allowing modules to signal other
820 modules when certain events occur. A module first establishes a callback
821 by registering it, giving it a name unique among all callbacks for that
822 module (two callbacks in different modules can share the same name). Other
823 modules can use that name to refer to the callback, and add functions to be
824 called when the callback's event occurs (also referred to as <i>hooking
825 into</i> the callback). The module which added the callback can then
826 instruct the module subsystem to call each of those functions in turn when
827 the requisite event occurs.</p>
828
829 <p>The Services core also sets up a number of callbacks which can be hooked
830 into by modules as necessary. A full list of callbacks available in the
831 Services core and standard modules can be found in <a href="c.html">Appendix
832 C</a>.</p>
833
834 <p class="backlink"><a href="#top">Back to top</a></p>
835
836
837 <h4 class="subsubsection-title" id="s5-1">4-5-1. Registering callbacks</h4>
838
839 <p>A module that wishes to register a new callback can do so with the
840 <tt>register_callback()</tt> routine (internally
841 <tt>_register_callback()</tt>):</p>
842
843 <div class="code">int <b>register_callback</b>([Module *<i>module</i>,] const char *<i>name</i>)</div>
844
845 <p>This routine checks to ensure that the given module has not already
846 registered a callback of the same name (by calling <tt>find_callback()</tt>,
847 an internal helper function that looks for a callback by name in a given
848 module), then adds the callback to the module's callback table with an
849 empty callback function list. The return value is the ID value assigned to
850 the callback (a value used when calling or removing the callback, both for
851 efficiency and to eliminate the possibility of mistyping the callback name
852 string when referring to it internally); a return value of -1 signals an
853 error. Note that the module's <tt>THIS_MODULE</tt> macro (which evaluates
854 to <tt>NULL</tt> when called by the core) is automatically passed to the
855 function by the <tt>register_callback()</tt> macro in <tt>modules.h</tt>,
856 like the <tt><i>caller</i></tt> parameter to <tt>use_module()</tt> and
857 <tt>unuse_module()</tt>.</p>
858
859 <p>When the callback is no longer needed, it can be unregistered by
860 calling <tt>unregister_callback()</tt> (internally
861 <tt>_unregister_callback()</tt>):</p>
862
863 <div class="code">int <b>unregister_callback</b>([Module *<i>module</i>,] int <i>id</i>)</div>
864
865 <p>The routine returns 1 if the callback was found and freed, 0 if the ID
866 value given was invalid.</p>
867
868 <p class="backlink"><a href="#top">Back to top</a></p>
869
870
871 <h4 class="subsubsection-title" id="s5-2">4-5-2. Hooking into callbacks</h4>
872
873 <p>Once a callback has been registered, other modules can add functions to
874 or remove functions from the callback with the <tt>add_callback()</tt>,
875 <tt>add_callback_pri()</tt>, and <tt>remove_callback()</tt> functions
876 (internally <tt>_add_callback_pri()</tt> and
877 <tt>_remove_callback</tt>&mdash;<tt>add_callback()</tt> is defined in terms
878 of <tt>add_callback_pri()</tt>):</p>
879
880 <div class="code">int <b>add_callback</b>(Module *<i>module</i>,
881 const char *<i>name</i>,
882 callback_t <i>callback</i>,
883 [const Module *<i>caller</i>])
884 int <b>add_callback_pri</b>(Module *<i>module</i>,
885 const char *<i>name</i>,
886 callback_t <i>callback</i>,
887 int <i>priority</i>,
888 [const Module *<i>caller</i>])
889 int <b>remove_callback</b>(Module *<i>module</i>,
890 const char *<i>name</i>,
891 callback_t <i>callback</i>,
892 [const Module *<i>caller</i>])</div>
893
894 <p>The type of a callback function is defined as <tt>callback_t</tt>:</p>
895
896 <div class="code">typedef int (*callback_t)()</div>
897
898 <p>The number and type of parameters passed to the function depends on the
899 particular callback, and thus the <tt>callback_t</tt> type is not a true
900 prototype. The <tt>int</tt> return value is used both to return a result
901 from the callback function itself and to control execution of the list of
902 callback functions, with a nonzero value terminating execution, as
903 described in <a href="#s5-3">section 4-5-3</a> below.</p>
904
905 <p><tt>add_callback()</tt> and <tt>add_callback_pri()</tt> add the given
906 function to the selected callback, returning nonzero on success, zero on
907 error. In the case of <tt>add_callback_pri()</tt>, the callback function
908 can be given a numeric priority; callback functions with higher priority
909 values are called before those with lower values, and callback functions
910 with the same priority value are called in the same order they were added.
911 <tt>add_callback()</tt> is equivalent to <tt>add_callback_pri()</tt> with a
912 priority of zero, and in fact is implemented as a macro that does exactly
913 that. <i>Implementation note: Priorities were added to allow the
914 <tt>operserv/sessions</tt> module to have its "<tt>user check</tt>"
915 callback function, which increments the user count for a session if the
916 user passes the session check, called last. This is arguably a bad design
917 decision, as it would be better (if less efficient) to move the session
918 count incrementing to the "<tt>user create</tt>" callback, and the current
919 method cannot stop another module from adding a callback function at an
920 even lower priority and causing the session count to "leak" if the
921 lower-priority function rejects the user.</i></p>
922
923 <p><tt>remove_callback()</tt> removes the given function from the selected
924 callback, returning nonzero if the function was found and successfully
925 removed, else zero. <tt>remove_callback()</tt> deliberately does not
926 generate a log warning when used with a callback function that has not been
927 added, in order to simplify modules' cleanup routines (so that they can
928 call <tt>remove_callback()</tt> for all callbacks that may have potentially
929 been added without having to keep track of which ones were in fact
930 added).</p>
931
932 <p class="backlink"><a href="#top">Back to top</a></p>
933
934
935 <h4 class="subsubsection-title" id="s5-3">4-5-3. Calling callbacks</h4>
936
937 <p>A module can instruct the module subsystem to call all callback
938 functions for a particular callback with the <tt>call_callback()</tt> set
939 of functions (actually macros, with the implementing function internally
940 named <tt>_call_callback_5()</tt>):</p>
941
942 <div class="code">int <b>call_callback</b>([Module *<i>module</i>,] int <i>id</i>)
943 int <b>call_callback_1</b>([Module *<i>module</i>,] int <i>id</i>,
944 void *<i>arg1</i>)
945 int <b>call_callback_2</b>([Module *<i>module</i>,] int <i>id</i>,
946 void *<i>arg1</i>, void *<i>arg2</i>)
947 int <b>call_callback_3</b>([Module *<i>module</i>,] int <i>id</i>,
948 void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>)
949 int <b>call_callback_4</b>([Module *<i>module</i>,] int <i>id</i>,
950 void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>,
951 void *<i>arg4</i>)
952 int <b>call_callback_5</b>([Module *<i>module</i>,] int <i>id</i>,
953 void *<i>arg1</i>, void *<i>arg2</i>, void *<i>arg3</i>,
954 void *<i>arg4</i>, void *<i>arg5</i>)</div>
955
956 <p>As with <tt>register_module()</tt> and <tt>unregister_module()</tt>,
957 the module handle of the calling module is automatically passed in the
958 hidden <tt><i>module</i></tt> parameter.</p>
959
960 <p>These functions all call the selected callback (specified by callback
961 ID value, as returned from <tt>register_callback()</tt>), and differ only
962 in the number of parameters passed to the callback. The parameters
963 <tt><i>arg1</i></tt> through <tt><i>arg5</i></tt> are passed to the
964 callback functions unchanged; the parameters are declared as the (more or
965 less) generic type <tt>void&nbsp;*</tt>, but may be of any type, as the
966 <tt>call_callback()</tt> macros take care of converting the parameters to
967 <tt>void&nbsp;*</tt> to avoid type conversion warnings (but see
968 <a href="11.html#s1">section 11-1</a> for problems with this method of
969 passing parameters). It is the callback function's responsibility to
970 ensure that it is declared with the correct parameter list.</p>
971
972 <p>After checking the validity of the module and callback ID parameters,
973 <tt>call_callback()</tt> calls each callback function that has been added
974 to the callback, in priority and time order (see <a href="#s5-2">section
975 4-5-2</a> about calling order). If any callback function returns a nonzero
976 value, <tt>call_callback()</tt> stops immediately and returns that value,
977 skipping the rest of the callback functions; if all callback functions
978 return zero (or if there are no callback functions for the given callback),
979 zero is returned. (-1 is returned if the callback ID is invalid.) Thus,
980 callbacks should be designed so that a return value of zero from a callback
981 function means "continue processing" and a nonzero value means "stop
982 processing or take some other action".</p>
983
984 <p class="backlink"><a href="#top">Back to top</a></p>
985
986 <!------------------------------------------------------------------------>
987 <hr/>
988
989 <h3 class="subsection-title" id="s6">4-6. Adding a module to Services</h3>
990
991 <p>Adding a new module to Services consists generally of the following
992 steps:</p>
993
994 <ul>
995 <li>Create a subdirectory for the module under the <tt>modules</tt>
996 directory.</li>
997 <li>Write the module itself.</li>
998 <li>Create a Makefile for the module (see <a href="10.html#s3-2">section
999 10-3-2</a>).</li>
1000 </ul>
1001
1002 <p>For submodules of pre-existing modules, like new NickServ or ChanServ
1003 features, the module can naturally go in the appropriate pre-existing
1004 directory instead, with the corresponding Makefile modified to compile the
1005 new module.</p>
1006
1007 <p>For modules intended to be distributed separately from Services itself,
1008 it is sufficient to distribute the subdirectory containing the module
1009 source code and Makefile; by copying that directory into the <tt>modules</tt>
1010 directory of a fresh Services distribution, the module Makefile will
1011 automatically detect it and compile the module without any further
1012 intervention on the part of the user. (See also
1013 <a href="../3.html#10">section 3-10 of th user's manual</a>.)</p>
1014
1015 <p>In addition to this section, sections <a href="2.html#s2">2-2</a>
1016 (concerning utility functions) and <a href="2.html#s4">2-4</a> (concerning
1017 logging), along with <a href="c.html">Appendix C</a> (containing a list of
1018 core and standard module callbacks), provide useful information for module
1019 development. Additionally, the following sections of this manual can be
1020 helpful in writing different types of modules:</p>
1021
1022 <ul>
1023 <li><b>Protocol modules:</b> sections <a href="5.html">5</a> and
1024 <a href="2.html#s5">2-5</a>, and particularly section
1025 <a href="5.html#s6-14">5-6-14</a>, which discusses the Unreal
1026 protocol module in detail.</li>
1027 <li><b>Database modules:</b> sections <a href="6.html">6</a> and
1028 <a href="2.html#s9-2">2-9-2</a>.</li>
1029 <li><b>Pseudoclient modules:</b> sections <a href="7.html">7</a>,
1030 <a href="2.html#s6">2-6</a>, <a href="2.html#s8">2-8</a>,
1031 <a href="2.html#s10">2-10</a>, and <a href="6.html#s2">6-2</a>.</li>
1032 </ul>
1033
1034 <p class="backlink"><a href="#top">Back to top</a></p>
1035
1036 <!------------------------------------------------------------------------>
1037 <hr/>
1038
1039 <p class="backlink"><a href="3.html">Previous section: Communication (socket) handling</a> |
1040 <a href="index.html">Table of Contents</a> |
1041 <a href="5.html">Next section: IRC server interface</a></p>
1042
1043 </body>
1044 </html>