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

1 guppy 1.12 EGGDROP MODULE INFORMATION 13 Dec 2001
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 guppy 1.12 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 guppy 1.12 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 guppy 1.12 compress This module provides an zlib support for compress transfer of
71 fabian 1.7 files via the botnet. For Example, compressed userfile transfers
72     are possible now.
73 guppy 1.12 console This module provides storage of console settings when you exit
74 segfault 1.1 the bot (or .store).
75 guppy 1.12 ctcp This provides the normal ctcp replies that you'd expect.
76     dns This module provides asynchronous dns support which avoids
77 fabian 1.3 blocking on dns lookups. Especially useful for busy hub bots.
78 guppy 1.12 filesys The file system. If you unload it all users currently using
79 fabian 1.3 the it will be disconnected from the bot.
80 guppy 1.12 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 guppy 1.12 notes This provides support for storing of notes for users from each
83 fabian 1.3 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 guppy 1.12 server This provides the core server support (removing this is
87 segfault 1.1 equivalent to the old NO_IRC define).
88 guppy 1.12 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 guppy 1.12 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 fabian 1.3 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 segfault 1.1
103 fabian 1.3 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 tothwolf 1.8
110 fabian 1.3 (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 segfault 1.1
114 fabian 1.3 (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 segfault 1.1
117 fabian 1.3 (1) Things you need to include in your source code.
118 segfault 1.1
119 fabian 1.3 (i) #define MODULE_NAME "module-name"
120 segfault 1.1
121     You MUST use this, it's required by several short cuts in the
122 tothwolf 1.8 code, it's gotta be the name you will be using in .loadmod
123 fabian 1.3
124 johoho 1.5 (ii) #define MAKING_MODULENAME
125 tothwolf 1.8 You MUST also include this, or else the module won't work.
126 johoho 1.5 MODULENAME is the name of your module(MODULE_NAME), but in
127     caps
128    
129     (iii) #include "../module.h"
130 fabian 1.3
131     This provides all the accessible functions in eggdrop,
132 tothwolf 1.8 examine closely src/mod/module.h to find a list of functions
133     available.
134 fabian 1.3
135 johoho 1.5 (iv) and other standard c include files you might need (Note
136 fabian 1.3 stdio.h string.h stdlib.h & sys/types.h are already included)
137    
138 tothwolf 1.8 (v) Function *global;
139 fabian 1.3
140 segfault 1.1 This variable provides access to all the eggdrop functions, without
141 tothwolf 1.8 it you can't call any eggdrop functions (heck, the module wont
142     even load)
143 fabian 1.3
144 segfault 1.1 (2) CORE functions every module needs.
145 tothwolf 1.8
146 segfault 1.1 *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 tothwolf 1.8
150 fabian 1.3 In each of these cases MODULE = module name
151 tothwolf 1.8
152 fabian 1.3 (i) char *MODULE_start(Function *func_table)
153 segfault 1.1 - this module is called when the module is first loaded,
154 tothwolf 1.8 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 fabian 1.3 (ii) static Function *MODULE_table = {
176 segfault 1.1 MODULE_start,
177 tothwolf 1.8 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 fabian 1.3 (iii) static char *MODULE_close ()
191 segfault 1.1 - this is called when the module is unloaded..
192 tothwolf 1.8 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 segfault 1.1 following:
195 tothwolf 1.8 (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 segfault 1.1 this should tally all memory you allocate/deallocate within
204 tothwolf 1.8 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 segfault 1.1 this should provide a relatively short report of module status
210 tothwolf 1.8 (for .module/.status)
211    
212 johoho 1.6 (c) AVAILABLE FUNCTIONS - this is what ppl want no? :)
213 segfault 1.1 (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 tothwolf 1.8 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 fabian 1.3 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 tothwolf 1.8 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 segfault 1.1
233 tothwolf 1.8 int module_register ( char *module_name,
234 fabian 1.3 Function *function_table,
235 tothwolf 1.8 int major, int minor )
236     - see above for what/who/why/etc
237 fabian 1.3 const module_entry *module_find ( char *module_name, int major, int minor);
238 segfault 1.1 - look for a module, (matching major, >= minor) and return
239 tothwolf 1.8 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 segfault 1.1
245 fabian 1.3 int module_depend ( char *module_name, char *needed_module,
246 segfault 1.1 int major, int minor )
247 tothwolf 1.8 - 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 johoho 1.5 int module_undepend ( char *module_name)
251 segfault 1.1 - marks your module as no longer needing any of it's
252     dependancies
253 fabian 1.3 void module_rename (char *old_module_name, char *new_module_name)
254 segfault 1.1 - renames a module, this works so that for exmaple, you
255 tothwolf 1.8 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 fabian 1.3 void add_hook (int hook_num, Function *funcs)
260     void del_hook (int hook_num, Function *funcs)
261 segfault 1.1
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 guppy 1.10 HOOK_BACKUP - called when a user/channel file backup is done
279     HOOK_LOADED - called when eggdrop is first loaded
280 tothwolf 1.8
281 fabian 1.3 char *module_load ( char *module_name ); tries to load the given module,
282 segfault 1.1 returns 0 on success, or an error msg
283    
284 fabian 1.3 char *module_unload ( char *module_name ); tries to unload the given module,
285 segfault 1.1 returns as above.
286    
287 fabian 1.3 void add_tcl_commands(tcl_cmds *tab);
288     void rem_tcl_commands(tcl_cmds *tab);
289 segfault 1.1 provides a quick way to load & unload a list of tcl commands, the
290     table is in the form :
291 fabian 1.3 { char *func_name, Function *function_to_call }
292 segfault 1.1 these are normal tcl commands (as done in tcl*.c)
293     use { 0, 0 } to indicate the end of the list
294 tothwolf 1.8
295 segfault 1.1 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 johoho 1.5 { char *variable_name, int *variable, int readonly }
301     terminate with {0,0,0};
302 tothwolf 1.8
303 segfault 1.1 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 fabian 1.3 { char * variable_name, char *string, int length, int flags }
309 segfault 1.1 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 tothwolf 1.8 not during normal usage.
314 segfault 1.1
315 fabian 1.3 void putlog (int logmode, char *channel, char *format, ... )
316 segfault 1.1 logs a comment, see src/eggdrop.h for logmodes, channel makes
317     a channel or "*" for all.
318    
319 fabian 1.3 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
320     void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
321 segfault 1.1 the method of adding/remove bindings for tcl hash tables.
322 fabian 1.2 table is a hash table you find with find_hash_table,
323     cc format:
324 fabian 1.3 { char *command, char *flags, Function *function }
325 fabian 1.2 terminate with { 0, 0, 0, 0 }
326 segfault 1.1 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 fabian 1.4
336    
337     VI. WHAT TO DO WITH A MODULE?
338    
339 guppy 1.12 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