/[cvs]/eggdrop1.9/doc/MODULES
ViewVC logotype

Contents of /eggdrop1.9/doc/MODULES

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.11 - (show annotations) (download)
Mon Aug 13 19:12:28 2001 UTC (18 years, 2 months ago) by guppy
Branch: MAIN
Changes since 1.10: +1 -5 lines
Removed more references to seen.mod and wire.mod

1 EGGDROP MODULE INFORMATION 19 Feb 2000
2
3
4 INDEX
5
6 I WHAT ARE MODULES?
7 II WHY USE MODULES?
8 III HOW TO USE MODULES?
9 IV CURRENT MODULES
10 V PROGRAMMING MODULES
11 VI WHAT TO DO WITH A MODULE?
12
13
14 I. WHAT ARE MODULES?
15
16 Modules are portions of code which are loaded seperately to the
17 bot itself, which provided extra services. eg. filesys module
18 provides the entire file system.
19
20
21 II. WHY USE MODULES?
22
23 It allows the core eggdrop, that which is minimally required to be
24 reduced, and allows C coders to add their own ehancements to the
25 bot without recompiling the whole thing.
26
27
28 III. HOW TO USE MODULES
29
30 Run ./configure as normal, then 'make' to make the eggdrop
31 with module support, this will also compile the modules.
32
33 The list of modules compiled is adjustable by
34
35 (a) specifying `--disable-mod-MODULE' parameters to the configure
36 script, where MODULE is the module you want to disable.
37
38 (b) the interactive module selection tool called during a normal
39 ./configure run. (this may be disabled by specifying the
40 parameter `--disable-modconf')
41
42 (c) calling `make reconfig' after a successful configure run,
43 which calls the interactive module selection tool again.
44
45 Next do one of two things to load the module:
46
47 from the partyline (as an owner) type:
48 .loadmod <module-name>
49 or in a tcl script:
50 loadmodule <module-name>
51
52 module-name is the part BEFORE .so, e.g filesys.so module
53 you type '.loadmod filesys'.
54
55 Normally you will want to add the loadmodule statement to your
56 bot's configuration file instead of typing it every time the bot
57 start.
58
59 To see your currently running modules type '.module'.
60
61
62 IV. CURRENT MODULES
63
64 assoc : Assoc support.
65 blowfish : Encryption support needed for encrypting your users' passwords.
66 This module can't be unloaded once it's loaded.
67 channels : Provides channel related support for the bot, without it, it
68 will just sit on irc, it can respond to msg & ctcp commands,
69 but that's all.
70 compress : This module provides an zlib support for compress transfer of
71 files via the botnet. For Example, compressed userfile transfers
72 are possible now.
73 console : This module provides storage of console settings when you exit
74 the bot (or .store).
75 ctcp : This provides the normal ctcp replies that you'd expect.
76 dns : This module provides asynchronous dns support which avoids
77 blocking on dns lookups. Especially useful for busy hub bots.
78 filesys : The file system. If you unload it all users currently using
79 the it will be disconnected from the bot.
80 irc : This module provides ALL NORMAL IRC INTERACTION, if you want
81 the normal join & maintain channels stuff, this is the module.
82 notes : This provides support for storing of notes for users from each
83 other. Notes between currently online users is supported in
84 the core, this is only for storing the notes for later
85 retrieval, direct user->user notes are built-in.
86 server : This provides the core server support (removing this is
87 equivalent to the old NO_IRC define).
88 share : Userfile sharing.
89 transfer : Handles the transfer of files via botnet or dcc, this is
90 REQUIRED for file sharing.
91 woobie : Just a fun, bizarre test module which serves as an example for
92 module programming.
93
94
95 V. PROGRAMMING MODULES
96
97 WARNING:
98 This section is very likely to be out of date. It was not updated
99 for quite some time. The most reliable way to learn about module
100 programming is to take a deep look at the other available modules.
101
102 Note: This is for a simple module of 1 source file, if you're doing a
103 multiple source file module, you shouldn't need to read this
104 anyway ;)
105
106 (a) Create a src/mod/MODULE.mod directory in your eggdrop distro
107 (where MODULE is the module name) and cd to it.
108
109 (b) Copy the file `Makefile' from src/mod/woobie.mod and replace all
110 occurences of `woobie' with your module name. This should ensure
111 that your module gets compiled.
112
113 (c) Next you want to create a file called MODULE.c (again MODULE is the
114 module name), and here's where the work starts :)
115
116 (1) Things you need to include in your source code.
117
118 (i) #define MODULE_NAME "module-name"
119
120 You MUST use this, it's required by several short cuts in the
121 code, it's gotta be the name you will be using in .loadmod
122
123 (ii) #define MAKING_MODULENAME
124 You MUST also include this, or else the module won't work.
125 MODULENAME is the name of your module(MODULE_NAME), but in
126 caps
127
128 (iii) #include "../module.h"
129
130 This provides all the accessible functions in eggdrop,
131 examine closely src/mod/module.h to find a list of functions
132 available.
133
134 (iv) and other standard c include files you might need (Note
135 stdio.h string.h stdlib.h & sys/types.h are already included)
136
137 (v) Function *global;
138
139 This variable provides access to all the eggdrop functions, without
140 it you can't call any eggdrop functions (heck, the module wont
141 even load)
142
143 (2) CORE functions every module needs.
144
145 *SIDENOTE* I suggest in a single source file module you define all
146 functions/variables (except global & module_start) as static, this will
147 drastically reduce the size of modules on decent systems.
148
149 In each of these cases MODULE = module name
150
151 (i) char *MODULE_start(Function *func_table)
152 - this module is called when the module is first loaded,
153 you MUST do serveral things in this function
154 (a) global = func_table; (so you can make eggdrop calls)
155 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
156 this records details about the module for other modules
157 & eggdrop itself to access, major is a major version number,
158 minor is a minor version number, MODULE_table is a function
159 table (see below)
160 (c) module_depend(MODULE_NAME, "another-module", major, minor);
161 this lets eggdrop know that your module NEEDS "another-module"
162 of major version 'major' and at least minor version 'minor'
163 to run and hence should try to load it if it's not already here
164 this will return 1 on success, or 0 if it cant be done
165 (at which stage you should return an error)
166 (d) any other initialization stuff you desire, see below for
167 various things you can do.
168 (e) a return value of some sort, returning NULL implies the module
169 loaded successfully, and so the bot can continue.
170 return a non-NULL STRING is an error message, the module
171 (and any other dependant modules) will stop loading
172 and an error will be returned.
173
174 (ii) static Function *MODULE_table = {
175 MODULE_start,
176 MODULE_close,
177 MODULE_expmem,
178 MODULE_report,
179 any_other_functions,
180 you_want_to_export
181 };
182 ok, it's not a function, it's a list of functions, which any
183 other module can call up, so you can provide services for other
184 modules (eg transfer has raw_dcc_send in it's table to allow
185 the filesys to send files to others)
186 the first 4 functions are FIXED, you MUST have them, they
187 provide important system info.
188
189 (iii) static char *MODULE_close ()
190 - this is called when the module is unloaded..
191 apart from tidying any relevant data (I suggest you be thorough,
192 we don't want any trailing garbage from modules) you MUST do the
193 following:
194 (a) module_undepend(MODULE_NAME);
195 this lets eggdrop know your module no longer depends on
196 any other modules.
197 (b) return a value, NULL implies success, non-NULL STRING implies
198 the module cannot be unloaded for some reason and hence
199 the bot should leave it in (see blowfish for an example)
200
201 (iv) static int MODULE_expmem ()
202 this should tally all memory you allocate/deallocate within
203 the module (using modmalloc & modfree), it's used by memory
204 debugging to track memory faults, and by .status to total up
205 memory usage.
206
207 (v) static void MODULE_report (int idx)
208 this should provide a relatively short report of module status
209 (for .module/.status)
210
211 (c) AVAILABLE FUNCTIONS - this is what ppl want no? :)
212 (i) reliable ones, you can RELY on these functions being available,
213 they may move in the tables for the moment (since it's a work
214 in progress) but they will be there...
215 This is just a short list of the ones you need to make
216 a mildly useful module, a goodly portion of the remaining
217 eggdrop functions are avaliable, check src/mod/module.h for
218 info.
219
220 void *nmalloc (int a); - allocates a bytes
221 void nfree (void *a); - frees a modmalloc'd block
222 context; - actually a #define, records the current
223 - possition in execution, for debugging
224 void dprintf (int idx,char *format, ... ) - just like normal printf,
225 outputs to a dcc/socket/server,
226 idx is a normal dcc idx OR if < 0 is a sock #
227 OR one of: DP_LOG (send to log file)
228 DP_STDOUT (send to stdout)
229 DP_MODE (send via mode queue to sever) *fast*
230 DP_SERVER (send via normal queue to sever) *normal*
231 DP_HELP (send via help queue to sever) - use this
232 for mass outputs to users
233
234 int module_register ( char *module_name,
235 Function *function_table,
236 int major, int minor )
237 - see above for what/who/why/etc
238 const module_entry *module_find ( char *module_name, int major, int minor);
239 - look for a module, (matching major, >= minor) and return
240 info about it....members of module_entry...
241 char *name; - module name (duh)
242 int major; - real major version
243 int minor; - real minor version
244 Function *funcs; - function table (see above)
245
246 int module_depend ( char *module_name, char *needed_module,
247 int major, int minor )
248 - marks your module (module_name) as needing needed_module
249 (matching major, >= minor) and tries to load said module
250 if it's not already loaded. returns 1 on success
251 int module_undepend ( char *module_name)
252 - marks your module as no longer needing any of it's
253 dependancies
254 void module_rename (char *old_module_name, char *new_module_name)
255 - renames a module, this works so that for exmaple, you
256 could have efnet.so, undernet.so, ircnet.so & dalnet.so
257 and they called all rename themselves as server.so which
258 is what you really want
259
260 void add_hook (int hook_num, Function *funcs)
261 void del_hook (int hook_num, Function *funcs)
262
263 used for adding removing hooks into eggdrop code, on various events, these
264 functions are called, depending on the hook
265
266 valid hooks:
267
268 HOOK_SECONDLY - called every second
269 HOOK_MINUTELY - called every minute
270 HOOK_5MINUTELY - called every 5 minutes
271 HOOK_HOURLY - called every hour, (at hourly-updates minutes past)
272 HOOK_DAILY - called every day, when the logfiles are switched
273 HOOK_READ_USERFILE - called when the userfile is read
274 HOOK_USERFILE - called when the userfile is written
275 HOOK_PRE_REHASH - called just *before* rehash
276 HOOK_REHASH - called just after rehash
277 HOOK_IDLE - called whenever the dcc connections have been idle
278 for a whole second
279 HOOK_BACKUP - called when a user/channel file backup is done
280 HOOK_LOADED - called when eggdrop is first loaded
281
282 char *module_load ( char *module_name ); tries to load the given module,
283 returns 0 on success, or an error msg
284
285 char *module_unload ( char *module_name ); tries to unload the given module,
286 returns as above.
287
288 void add_tcl_commands(tcl_cmds *tab);
289 void rem_tcl_commands(tcl_cmds *tab);
290 provides a quick way to load & unload a list of tcl commands, the
291 table is in the form :
292 { char *func_name, Function *function_to_call }
293 these are normal tcl commands (as done in tcl*.c)
294 use { 0, 0 } to indicate the end of the list
295
296 void add_tcl_ints(tcl_ints *);
297 void rem_tcl_ints(tcl_ints *);
298 provides a way to add/remove links from c variables to tcl variables
299 (add checks to see if the tcl already exists and copies it over the C one)
300 format of table is :
301 { char *variable_name, int *variable, int readonly }
302 terminate with {0,0,0};
303
304 void add_tcl_strings(tcl_strings *);
305 void rem_tcl_strings(tcl_strings *);
306 provides a way to add/remove links from c strings to tcl strings
307 (also copies exists tcl values)
308 format:
309 { char * variable_name, char *string, int length, int flags }
310 terminate with { 0, 0, 0, 0 }
311 length: set to 0 if you want a const string.
312 flags: use STR_DIR if you want a / constantly appended,
313 use STR_PROTECT if you want the variable on set in the configfile,
314 not during normal usage.
315
316 void putlog (int logmode, char *channel, char *format, ... )
317 logs a comment, see src/eggdrop.h for logmodes, channel makes
318 a channel or "*" for all.
319
320 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
321 void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
322 the method of adding/remove bindings for tcl hash tables.
323 table is a hash table you find with find_hash_table,
324 cc format:
325 { char *command, char *flags, Function *function }
326 terminate with { 0, 0, 0, 0 }
327 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
328 the same function this does),
329 function is called with exactly the same args as a tcl binding is
330 (except for dcc which does include the handle in C) with type conversion
331 taken into account (e.g. idx's are ints)
332 return much the same as tcl bindings, use int 0/1 for those
333 which require 0/1 or char * for those which require a string (eg filt)
334 or nothing if no return is required.
335 return is also in src/tclhash.c
336
337
338 VI. WHAT TO DO WITH A MODULE?
339
340 If you have written a module and feel that you want to share
341 it with the rest of the eggdrop comunity, upload it to the incoming
342 directory on ftp.eggheads.org(/pub/eggdrop/incoming). Place a nice
343 descriptive text with it and makes it way to the modules directory.
344 Don't forgot to write for which eggdrop version this module is for...

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23