/[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.12 - (hide annotations) (download)
Fri Dec 14 05:48:37 2001 UTC (17 years, 10 months ago) by guppy
Branch: MAIN
Changes since 1.11: +22 -20 lines
applied BarkerJr's patch to update doc/MODULES from 1.6

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 segfault 1.1 context; - actually a #define, records the current
224     - possition in execution, for debugging
225 fabian 1.3 void dprintf (int idx,char *format, ... ) - just like normal printf,
226 tothwolf 1.8 outputs to a dcc/socket/server,
227     idx is a normal dcc idx OR if < 0 is a sock #
228     OR one of: DP_LOG (send to log file)
229     DP_STDOUT (send to stdout)
230     DP_MODE (send via mode queue to sever) *fast*
231     DP_SERVER (send via normal queue to sever) *normal*
232     DP_HELP (send via help queue to sever) - use this
233     for mass outputs to users
234 segfault 1.1
235 tothwolf 1.8 int module_register ( char *module_name,
236 fabian 1.3 Function *function_table,
237 tothwolf 1.8 int major, int minor )
238     - see above for what/who/why/etc
239 fabian 1.3 const module_entry *module_find ( char *module_name, int major, int minor);
240 segfault 1.1 - look for a module, (matching major, >= minor) and return
241 tothwolf 1.8 info about it....members of module_entry...
242     char *name; - module name (duh)
243     int major; - real major version
244     int minor; - real minor version
245     Function *funcs; - function table (see above)
246 segfault 1.1
247 fabian 1.3 int module_depend ( char *module_name, char *needed_module,
248 segfault 1.1 int major, int minor )
249 tothwolf 1.8 - marks your module (module_name) as needing needed_module
250     (matching major, >= minor) and tries to load said module
251     if it's not already loaded. returns 1 on success
252 johoho 1.5 int module_undepend ( char *module_name)
253 segfault 1.1 - marks your module as no longer needing any of it's
254     dependancies
255 fabian 1.3 void module_rename (char *old_module_name, char *new_module_name)
256 segfault 1.1 - renames a module, this works so that for exmaple, you
257 tothwolf 1.8 could have efnet.so, undernet.so, ircnet.so & dalnet.so
258     and they called all rename themselves as server.so which
259     is what you really want
260    
261 fabian 1.3 void add_hook (int hook_num, Function *funcs)
262     void del_hook (int hook_num, Function *funcs)
263 segfault 1.1
264     used for adding removing hooks into eggdrop code, on various events, these
265     functions are called, depending on the hook
266    
267     valid hooks:
268    
269     HOOK_SECONDLY - called every second
270     HOOK_MINUTELY - called every minute
271     HOOK_5MINUTELY - called every 5 minutes
272     HOOK_HOURLY - called every hour, (at hourly-updates minutes past)
273     HOOK_DAILY - called every day, when the logfiles are switched
274     HOOK_READ_USERFILE - called when the userfile is read
275     HOOK_USERFILE - called when the userfile is written
276     HOOK_PRE_REHASH - called just *before* rehash
277     HOOK_REHASH - called just after rehash
278     HOOK_IDLE - called whenever the dcc connections have been idle
279     for a whole second
280 guppy 1.10 HOOK_BACKUP - called when a user/channel file backup is done
281     HOOK_LOADED - called when eggdrop is first loaded
282 tothwolf 1.8
283 fabian 1.3 char *module_load ( char *module_name ); tries to load the given module,
284 segfault 1.1 returns 0 on success, or an error msg
285    
286 fabian 1.3 char *module_unload ( char *module_name ); tries to unload the given module,
287 segfault 1.1 returns as above.
288    
289 fabian 1.3 void add_tcl_commands(tcl_cmds *tab);
290     void rem_tcl_commands(tcl_cmds *tab);
291 segfault 1.1 provides a quick way to load & unload a list of tcl commands, the
292     table is in the form :
293 fabian 1.3 { char *func_name, Function *function_to_call }
294 segfault 1.1 these are normal tcl commands (as done in tcl*.c)
295     use { 0, 0 } to indicate the end of the list
296 tothwolf 1.8
297 segfault 1.1 void add_tcl_ints(tcl_ints *);
298     void rem_tcl_ints(tcl_ints *);
299     provides a way to add/remove links from c variables to tcl variables
300     (add checks to see if the tcl already exists and copies it over the C one)
301     format of table is :
302 johoho 1.5 { char *variable_name, int *variable, int readonly }
303     terminate with {0,0,0};
304 tothwolf 1.8
305 segfault 1.1 void add_tcl_strings(tcl_strings *);
306     void rem_tcl_strings(tcl_strings *);
307     provides a way to add/remove links from c strings to tcl strings
308     (also copies exists tcl values)
309     format:
310 fabian 1.3 { char * variable_name, char *string, int length, int flags }
311 segfault 1.1 terminate with { 0, 0, 0, 0 }
312     length: set to 0 if you want a const string.
313     flags: use STR_DIR if you want a / constantly appended,
314     use STR_PROTECT if you want the variable on set in the configfile,
315 tothwolf 1.8 not during normal usage.
316 segfault 1.1
317 fabian 1.3 void putlog (int logmode, char *channel, char *format, ... )
318 segfault 1.1 logs a comment, see src/eggdrop.h for logmodes, channel makes
319     a channel or "*" for all.
320    
321 fabian 1.3 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
322     void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
323 segfault 1.1 the method of adding/remove bindings for tcl hash tables.
324 fabian 1.2 table is a hash table you find with find_hash_table,
325     cc format:
326 fabian 1.3 { char *command, char *flags, Function *function }
327 fabian 1.2 terminate with { 0, 0, 0, 0 }
328 segfault 1.1 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
329     the same function this does),
330     function is called with exactly the same args as a tcl binding is
331     (except for dcc which does include the handle in C) with type conversion
332     taken into account (e.g. idx's are ints)
333     return much the same as tcl bindings, use int 0/1 for those
334     which require 0/1 or char * for those which require a string (eg filt)
335     or nothing if no return is required.
336     return is also in src/tclhash.c
337 fabian 1.4
338    
339     VI. WHAT TO DO WITH A MODULE?
340    
341 guppy 1.12 If you have written a module and feel that you wish to share it with the
342     rest of the eggdrop community, upload it to the incoming directory on
343     incoming.eggheads.org(/incoming/modules). Place a nice descriptive
344     text with it and it'll make its way to the modules directory on
345     ftp.eggheads.org. Don't forget to mention in your text file which
346     version eggdrop the module is writen for.

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23