/[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.10 - (hide annotations) (download)
Tue Jul 24 14:19:18 2001 UTC (17 years, 11 months ago) by guppy
Branch: MAIN
Changes since 1.9: +2 -0 lines
I thought about doing this years ago .. glad someone did it :P~

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

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23