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

Annotation of /eggdrop1.9/doc/MODULES

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


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

1 fabian 1.3 EGGDROP MODULE INFORMATION 19 Feb 2000
2 segfault 1.1
3 fabian 1.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 fabian 1.4 VI WHAT TO DO WITH A MODULE?
12 fabian 1.3
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 tothwolf 1.8
27 fabian 1.3
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 johoho 1.6 .loadmod <module-name>
49 fabian 1.3 or in a tcl script:
50 guppy 1.9 loadmodule <module-name>
51 tothwolf 1.8
52 guppy 1.9 module-name is the part BEFORE .so, e.g filesys.so module
53     you type '.loadmod filesys'.
54 tothwolf 1.8
55 fabian 1.3 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 johoho 1.6 To see your currently running modules type '.module'.
60 segfault 1.1
61    
62 fabian 1.3 IV. CURRENT MODULES
63    
64     assoc : Assoc support.
65     blowfish : Encryption support needed for encrypting your users' passwords.
66 guppy 1.11 This module can't be unloaded once it's loaded.
67 fabian 1.3 channels : Provides channel related support for the bot, without it, it
68 segfault 1.1 will just sit on irc, it can respond to msg & ctcp commands,
69     but that's all.
70 fabian 1.7 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 fabian 1.3 console : This module provides storage of console settings when you exit
74 segfault 1.1 the bot (or .store).
75 fabian 1.3 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 segfault 1.1 the normal join & maintain channels stuff, this is the module.
82 fabian 1.3 notes : This provides support for storing of notes for users from each
83     other. Notes between currently online users is supported in
84 segfault 1.1 the core, this is only for storing the notes for later
85     retrieval, direct user->user notes are built-in.
86 fabian 1.3 server : This provides the core server support (removing this is
87 segfault 1.1 equivalent to the old NO_IRC define).
88 fabian 1.3 share : Userfile sharing.
89     transfer : Handles the transfer of files via botnet or dcc, this is
90 segfault 1.1 REQUIRED for file sharing.
91 fabian 1.3 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 segfault 1.1
102 fabian 1.3 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 tothwolf 1.8
109 fabian 1.3 (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 segfault 1.1
113 fabian 1.3 (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 segfault 1.1
116 fabian 1.3 (1) Things you need to include in your source code.
117 segfault 1.1
118 fabian 1.3 (i) #define MODULE_NAME "module-name"
119 segfault 1.1
120     You MUST use this, it's required by several short cuts in the
121 tothwolf 1.8 code, it's gotta be the name you will be using in .loadmod
122 fabian 1.3
123 johoho 1.5 (ii) #define MAKING_MODULENAME
124 tothwolf 1.8 You MUST also include this, or else the module won't work.
125 johoho 1.5 MODULENAME is the name of your module(MODULE_NAME), but in
126     caps
127    
128     (iii) #include "../module.h"
129 fabian 1.3
130     This provides all the accessible functions in eggdrop,
131 tothwolf 1.8 examine closely src/mod/module.h to find a list of functions
132     available.
133 fabian 1.3
134 johoho 1.5 (iv) and other standard c include files you might need (Note
135 fabian 1.3 stdio.h string.h stdlib.h & sys/types.h are already included)
136    
137 tothwolf 1.8 (v) Function *global;
138 fabian 1.3
139 segfault 1.1 This variable provides access to all the eggdrop functions, without
140 tothwolf 1.8 it you can't call any eggdrop functions (heck, the module wont
141     even load)
142 fabian 1.3
143 segfault 1.1 (2) CORE functions every module needs.
144 tothwolf 1.8
145 segfault 1.1 *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 tothwolf 1.8
149 fabian 1.3 In each of these cases MODULE = module name
150 tothwolf 1.8
151 fabian 1.3 (i) char *MODULE_start(Function *func_table)
152 segfault 1.1 - this module is called when the module is first loaded,
153 tothwolf 1.8 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 fabian 1.3 (ii) static Function *MODULE_table = {
175 segfault 1.1 MODULE_start,
176 tothwolf 1.8 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 fabian 1.3 (iii) static char *MODULE_close ()
190 segfault 1.1 - this is called when the module is unloaded..
191 tothwolf 1.8 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 segfault 1.1 following:
194 tothwolf 1.8 (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 segfault 1.1 this should tally all memory you allocate/deallocate within
203 tothwolf 1.8 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 segfault 1.1 this should provide a relatively short report of module status
209 tothwolf 1.8 (for .module/.status)
210    
211 johoho 1.6 (c) AVAILABLE FUNCTIONS - this is what ppl want no? :)
212 segfault 1.1 (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 tothwolf 1.8 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 fabian 1.3 void *nmalloc (int a); - allocates a bytes
221     void nfree (void *a); - frees a modmalloc'd block
222 segfault 1.1 context; - actually a #define, records the current
223     - possition in execution, for debugging
224 fabian 1.3 void dprintf (int idx,char *format, ... ) - just like normal printf,
225 tothwolf 1.8 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 segfault 1.1
234 tothwolf 1.8 int module_register ( char *module_name,
235 fabian 1.3 Function *function_table,
236 tothwolf 1.8 int major, int minor )
237     - see above for what/who/why/etc
238 fabian 1.3 const module_entry *module_find ( char *module_name, int major, int minor);
239 segfault 1.1 - look for a module, (matching major, >= minor) and return
240 tothwolf 1.8 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 segfault 1.1
246 fabian 1.3 int module_depend ( char *module_name, char *needed_module,
247 segfault 1.1 int major, int minor )
248 tothwolf 1.8 - 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 johoho 1.5 int module_undepend ( char *module_name)
252 segfault 1.1 - marks your module as no longer needing any of it's
253     dependancies
254 fabian 1.3 void module_rename (char *old_module_name, char *new_module_name)
255 segfault 1.1 - renames a module, this works so that for exmaple, you
256 tothwolf 1.8 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 fabian 1.3 void add_hook (int hook_num, Function *funcs)
261     void del_hook (int hook_num, Function *funcs)
262 segfault 1.1
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 guppy 1.10 HOOK_BACKUP - called when a user/channel file backup is done
280     HOOK_LOADED - called when eggdrop is first loaded
281 tothwolf 1.8
282 fabian 1.3 char *module_load ( char *module_name ); tries to load the given module,
283 segfault 1.1 returns 0 on success, or an error msg
284    
285 fabian 1.3 char *module_unload ( char *module_name ); tries to unload the given module,
286 segfault 1.1 returns as above.
287    
288 fabian 1.3 void add_tcl_commands(tcl_cmds *tab);
289     void rem_tcl_commands(tcl_cmds *tab);
290 segfault 1.1 provides a quick way to load & unload a list of tcl commands, the
291     table is in the form :
292 fabian 1.3 { char *func_name, Function *function_to_call }
293 segfault 1.1 these are normal tcl commands (as done in tcl*.c)
294     use { 0, 0 } to indicate the end of the list
295 tothwolf 1.8
296 segfault 1.1 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 johoho 1.5 { char *variable_name, int *variable, int readonly }
302     terminate with {0,0,0};
303 tothwolf 1.8
304 segfault 1.1 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 fabian 1.3 { char * variable_name, char *string, int length, int flags }
310 segfault 1.1 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 tothwolf 1.8 not during normal usage.
315 segfault 1.1
316 fabian 1.3 void putlog (int logmode, char *channel, char *format, ... )
317 segfault 1.1 logs a comment, see src/eggdrop.h for logmodes, channel makes
318     a channel or "*" for all.
319    
320 fabian 1.3 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
321     void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
322 segfault 1.1 the method of adding/remove bindings for tcl hash tables.
323 fabian 1.2 table is a hash table you find with find_hash_table,
324     cc format:
325 fabian 1.3 { char *command, char *flags, Function *function }
326 fabian 1.2 terminate with { 0, 0, 0, 0 }
327 segfault 1.1 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 fabian 1.4
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