/[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.13 - (show annotations) (download)
Tue Dec 18 07:04:21 2001 UTC (17 years, 6 months ago) by guppy
Branch: MAIN
Changes since 1.12: +0 -2 lines
removed Context and ContextNote

1 EGGDROP MODULE INFORMATION 13 Dec 2001
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 uptime Compete with other bots to see who has the highest uptime.
92 woobie Just a fun, bizarre test module which serves as an example for
93 module programming.
94
95
96 V. PROGRAMMING MODULES
97
98 WARNING:
99 This section is very likely to be out of date. It was not updated
100 for quite some time. The most reliable way to learn about module
101 programming is to take a deep look at the other available modules.
102
103 Note: This is for a simple module of 1 source file, if you're doing a
104 multiple source file module, you shouldn't need to read this
105 anyway ;)
106
107 (a) Create a src/mod/MODULE.mod directory in your eggdrop distro
108 (where MODULE is the module name) and cd to it.
109
110 (b) Copy the file `Makefile' from src/mod/woobie.mod and replace all
111 occurences of `woobie' with your module name. This should ensure
112 that your module gets compiled.
113
114 (c) Next you want to create a file called MODULE.c (again MODULE is the
115 module name), and here's where the work starts :)
116
117 (1) Things you need to include in your source code.
118
119 (i) #define MODULE_NAME "module-name"
120
121 You MUST use this, it's required by several short cuts in the
122 code, it's gotta be the name you will be using in .loadmod
123
124 (ii) #define MAKING_MODULENAME
125 You MUST also include this, or else the module won't work.
126 MODULENAME is the name of your module(MODULE_NAME), but in
127 caps
128
129 (iii) #include "../module.h"
130
131 This provides all the accessible functions in eggdrop,
132 examine closely src/mod/module.h to find a list of functions
133 available.
134
135 (iv) and other standard c include files you might need (Note
136 stdio.h string.h stdlib.h & sys/types.h are already included)
137
138 (v) Function *global;
139
140 This variable provides access to all the eggdrop functions, without
141 it you can't call any eggdrop functions (heck, the module wont
142 even load)
143
144 (2) CORE functions every module needs.
145
146 *SIDENOTE* I suggest in a single source file module you define all
147 functions/variables (except global & module_start) as static, this will
148 drastically reduce the size of modules on decent systems.
149
150 In each of these cases MODULE = module name
151
152 (i) char *MODULE_start(Function *func_table)
153 - this module is called when the module is first loaded,
154 you MUST do serveral things in this function
155 (a) global = func_table; (so you can make eggdrop calls)
156 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
157 this records details about the module for other modules
158 & eggdrop itself to access, major is a major version number,
159 minor is a minor version number, MODULE_table is a function
160 table (see below)
161 (c) module_depend(MODULE_NAME, "another-module", major, minor);
162 this lets eggdrop know that your module NEEDS "another-module"
163 of major version 'major' and at least minor version 'minor'
164 to run and hence should try to load it if it's not already here
165 this will return 1 on success, or 0 if it cant be done
166 (at which stage you should return an error)
167 (d) any other initialization stuff you desire, see below for
168 various things you can do.
169 (e) a return value of some sort, returning NULL implies the module
170 loaded successfully, and so the bot can continue.
171 return a non-NULL STRING is an error message, the module
172 (and any other dependant modules) will stop loading
173 and an error will be returned.
174
175 (ii) static Function *MODULE_table = {
176 MODULE_start,
177 MODULE_close,
178 MODULE_expmem,
179 MODULE_report,
180 any_other_functions,
181 you_want_to_export
182 };
183 ok, it's not a function, it's a list of functions, which any
184 other module can call up, so you can provide services for other
185 modules (eg transfer has raw_dcc_send in it's table to allow
186 the filesys to send files to others)
187 the first 4 functions are FIXED, you MUST have them, they
188 provide important system info.
189
190 (iii) static char *MODULE_close ()
191 - this is called when the module is unloaded..
192 apart from tidying any relevant data (I suggest you be thorough,
193 we don't want any trailing garbage from modules) you MUST do the
194 following:
195 (a) module_undepend(MODULE_NAME);
196 this lets eggdrop know your module no longer depends on
197 any other modules.
198 (b) return a value, NULL implies success, non-NULL STRING implies
199 the module cannot be unloaded for some reason and hence
200 the bot should leave it in (see blowfish for an example)
201
202 (iv) static int MODULE_expmem ()
203 this should tally all memory you allocate/deallocate within
204 the module (using modmalloc & modfree), it's used by memory
205 debugging to track memory faults, and by .status to total up
206 memory usage.
207
208 (v) static void MODULE_report (int idx)
209 this should provide a relatively short report of module status
210 (for .module/.status)
211
212 (c) AVAILABLE FUNCTIONS - this is what ppl want no? :)
213 (i) reliable ones, you can RELY on these functions being available,
214 they may move in the tables for the moment (since it's a work
215 in progress) but they will be there...
216 This is just a short list of the ones you need to make
217 a mildly useful module, a goodly portion of the remaining
218 eggdrop functions are avaliable, check src/mod/module.h for
219 info.
220
221 void *nmalloc (int a); - allocates a bytes
222 void nfree (void *a); - frees a modmalloc'd block
223 void dprintf (int idx,char *format, ... ) - just like normal printf,
224 outputs to a dcc/socket/server,
225 idx is a normal dcc idx OR if < 0 is a sock #
226 OR one of: DP_LOG (send to log file)
227 DP_STDOUT (send to stdout)
228 DP_MODE (send via mode queue to sever) *fast*
229 DP_SERVER (send via normal queue to sever) *normal*
230 DP_HELP (send via help queue to sever) - use this
231 for mass outputs to users
232
233 int module_register ( char *module_name,
234 Function *function_table,
235 int major, int minor )
236 - see above for what/who/why/etc
237 const module_entry *module_find ( char *module_name, int major, int minor);
238 - look for a module, (matching major, >= minor) and return
239 info about it....members of module_entry...
240 char *name; - module name (duh)
241 int major; - real major version
242 int minor; - real minor version
243 Function *funcs; - function table (see above)
244
245 int module_depend ( char *module_name, char *needed_module,
246 int major, int minor )
247 - marks your module (module_name) as needing needed_module
248 (matching major, >= minor) and tries to load said module
249 if it's not already loaded. returns 1 on success
250 int module_undepend ( char *module_name)
251 - marks your module as no longer needing any of it's
252 dependancies
253 void module_rename (char *old_module_name, char *new_module_name)
254 - renames a module, this works so that for exmaple, you
255 could have efnet.so, undernet.so, ircnet.so & dalnet.so
256 and they called all rename themselves as server.so which
257 is what you really want
258
259 void add_hook (int hook_num, Function *funcs)
260 void del_hook (int hook_num, Function *funcs)
261
262 used for adding removing hooks into eggdrop code, on various events, these
263 functions are called, depending on the hook
264
265 valid hooks:
266
267 HOOK_SECONDLY - called every second
268 HOOK_MINUTELY - called every minute
269 HOOK_5MINUTELY - called every 5 minutes
270 HOOK_HOURLY - called every hour, (at hourly-updates minutes past)
271 HOOK_DAILY - called every day, when the logfiles are switched
272 HOOK_READ_USERFILE - called when the userfile is read
273 HOOK_USERFILE - called when the userfile is written
274 HOOK_PRE_REHASH - called just *before* rehash
275 HOOK_REHASH - called just after rehash
276 HOOK_IDLE - called whenever the dcc connections have been idle
277 for a whole second
278 HOOK_BACKUP - called when a user/channel file backup is done
279 HOOK_LOADED - called when eggdrop is first loaded
280
281 char *module_load ( char *module_name ); tries to load the given module,
282 returns 0 on success, or an error msg
283
284 char *module_unload ( char *module_name ); tries to unload the given module,
285 returns as above.
286
287 void add_tcl_commands(tcl_cmds *tab);
288 void rem_tcl_commands(tcl_cmds *tab);
289 provides a quick way to load & unload a list of tcl commands, the
290 table is in the form :
291 { char *func_name, Function *function_to_call }
292 these are normal tcl commands (as done in tcl*.c)
293 use { 0, 0 } to indicate the end of the list
294
295 void add_tcl_ints(tcl_ints *);
296 void rem_tcl_ints(tcl_ints *);
297 provides a way to add/remove links from c variables to tcl variables
298 (add checks to see if the tcl already exists and copies it over the C one)
299 format of table is :
300 { char *variable_name, int *variable, int readonly }
301 terminate with {0,0,0};
302
303 void add_tcl_strings(tcl_strings *);
304 void rem_tcl_strings(tcl_strings *);
305 provides a way to add/remove links from c strings to tcl strings
306 (also copies exists tcl values)
307 format:
308 { char * variable_name, char *string, int length, int flags }
309 terminate with { 0, 0, 0, 0 }
310 length: set to 0 if you want a const string.
311 flags: use STR_DIR if you want a / constantly appended,
312 use STR_PROTECT if you want the variable on set in the configfile,
313 not during normal usage.
314
315 void putlog (int logmode, char *channel, char *format, ... )
316 logs a comment, see src/eggdrop.h for logmodes, channel makes
317 a channel or "*" for all.
318
319 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
320 void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
321 the method of adding/remove bindings for tcl hash tables.
322 table is a hash table you find with find_hash_table,
323 cc format:
324 { char *command, char *flags, Function *function }
325 terminate with { 0, 0, 0, 0 }
326 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
327 the same function this does),
328 function is called with exactly the same args as a tcl binding is
329 (except for dcc which does include the handle in C) with type conversion
330 taken into account (e.g. idx's are ints)
331 return much the same as tcl bindings, use int 0/1 for those
332 which require 0/1 or char * for those which require a string (eg filt)
333 or nothing if no return is required.
334 return is also in src/tclhash.c
335
336
337 VI. WHAT TO DO WITH A MODULE?
338
339 If you have written a module and feel that you wish to share it with the
340 rest of the eggdrop community, upload it to the incoming directory on
341 incoming.eggheads.org(/incoming/modules). Place a nice descriptive
342 text with it and it'll make its way to the modules directory on
343 ftp.eggheads.org. Don't forget to mention in your text file which
344 version eggdrop the module is writen for.

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23