/[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.4 - (hide annotations) (download)
Fri Mar 31 22:50:27 2000 UTC (19 years, 2 months ago) by fabian
Branch: MAIN
CVS Tags: eggdrop10503, eggdrop10403
Changes since 1.3: +13 -1 lines
Wiktor's miscdoc patch

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 segfault 1.1
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 segfault 1.1 .loadmodule <module-name>
49 fabian 1.3 or in a tcl script:
50 segfault 1.1 loadmodule <module-name>
51    
52 fabian 1.3 module-name is the part BEFORE .so, eg filesys.so module
53     you type '.loadmodule filesys'.
54 segfault 1.1
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     To see your currently running modules type '.modules'.
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.4 compress : This module provides an zlib support for compress transfer of files
72     vi athe botnet. For Example, compressed userfile transfers are
73     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 segfault 1.1
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     code, it's gotta be the name you will be using in .loadmodule
126 fabian 1.3
127     (ii) #include "../module.h"
128    
129     This provides all the accessible functions in eggdrop,
130 segfault 1.1 examine closely src/mod/module.h to find a list of functions
131 fabian 1.3 available.
132    
133     (iii) and other standard c include files you might need (Note
134     stdio.h string.h stdlib.h & sys/types.h are already included)
135    
136     (iv) Function *global;
137    
138 segfault 1.1 This variable provides access to all the eggdrop functions, without
139     it you can't call any eggdrop functions (heck, the module wont
140     even load)
141 fabian 1.3
142 segfault 1.1 (2) CORE functions every module needs.
143    
144     *SIDENOTE* I suggest in a single source file module you define all
145     functions/variables (except global & module_start) as static, this will
146     drastically reduce the size of modules on decent systems.
147    
148 fabian 1.3 In each of these cases MODULE = module name
149 segfault 1.1
150 fabian 1.3 (i) char *MODULE_start(Function *func_table)
151 segfault 1.1 - this module is called when the module is first loaded,
152     you MUST do serveral things in this function
153     (a) global = func_table; (so you can make eggdrop calls)
154 fabian 1.3 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
155 segfault 1.1 this records details about the module for other modules
156     & eggdrop itself to access, major is a major version number,
157     minor is a minor version number, MODULE_table is a function
158     table (see below)
159 fabian 1.3 (c) module_depend(MODULE_NAME, "another-module", major, minor);
160 segfault 1.1 this lets eggdrop know that your module NEEDS "another-module"
161     of major version 'major' and at least minor version 'minor'
162     to run and hence should try to load it if it's not already here
163     this will return 1 on success, or 0 if it cant be done
164     (at which stage you should return an error)
165     (d) any other initialization stuff you desire, see below for
166     various things you can do.
167     (e) a return value of some sort, returning NULL implies the module
168     loaded successfully, and so the bot can continue.
169     return a non-NULL STRING is an error message, the module
170     (and any other dependant modules) will stop loading
171     and an error will be returned.
172    
173 fabian 1.3 (ii) static Function *MODULE_table = {
174 segfault 1.1 MODULE_start,
175     MODULE_close,
176     MODULE_expmem,
177     MODULE_report,
178     any_other_functions,
179     you_want_to_export
180     };
181     ok, it's not a function, it's a list of functions, which any
182     other module can call up, so you can provide services for other
183     modules (eg transfer has raw_dcc_send in it's table to allow
184     the filesys to send files to others)
185     the first 4 functions are FIXED, you MUST have them, they
186     provide important system info.
187    
188 fabian 1.3 (iii) static char *MODULE_close ()
189 segfault 1.1 - this is called when the module is unloaded..
190     apart from tidying any relevant data (I suggest you be thorough,
191     we don't want any trailing garbage from modules) you MUST do the
192     following:
193     (a) module_undepend(MODULE_NAME);
194     this lets eggdrop know your module no longer depends on
195     any other modules.
196     (b) return a value, NULL implies success, non-NULL STRING implies
197     the module cannot be unloaded for some reason and hence
198     the bot should leave it in (see blowfish for an example)
199    
200     (iv) static int MODULE_expmem ()
201     this should tally all memory you allocate/deallocate within
202     the module (using modmalloc & modfree), it's used by memory
203     debugging to track memory faults, and by .status to total up
204     memory usage.
205    
206     (v) static void MODULE_report (int idx)
207     this should provide a relatively short report of module status
208     (for .modules/.status)
209    
210     (c) AVALIABLE FUNCTIONS - this is what ppl want no? :)
211     (i) reliable ones, you can RELY on these functions being available,
212     they may move in the tables for the moment (since it's a work
213     in progress) but they will be there...
214     This is just a short list of the ones you need to make
215     a mildly useful module, a goodly portion of the remaining
216     eggdrop functions are avaliable, check src/mod/module.h for
217     info.
218    
219 fabian 1.3 void *nmalloc (int a); - allocates a bytes
220     void nfree (void *a); - frees a modmalloc'd block
221 segfault 1.1 context; - actually a #define, records the current
222     - possition in execution, for debugging
223 fabian 1.3 void dprintf (int idx,char *format, ... ) - just like normal printf,
224 segfault 1.1 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 fabian 1.3 int module_register ( char *module_name,
234     Function *function_table,
235 segfault 1.1 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     info about it....members of module_entry...
240 fabian 1.3 char *name; - module name (duh)
241 segfault 1.1 int major; - real major version
242     int minor; - real minor version
243 fabian 1.3 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     - 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 fabian 1.3 int module_undpend ( 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     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    
279 fabian 1.3 char *module_load ( char *module_name ); tries to load the given module,
280 segfault 1.1 returns 0 on success, or an error msg
281    
282 fabian 1.3 char *module_unload ( char *module_name ); tries to unload the given module,
283 segfault 1.1 returns as above.
284    
285 fabian 1.3 void add_tcl_commands(tcl_cmds *tab);
286     void rem_tcl_commands(tcl_cmds *tab);
287 segfault 1.1 provides a quick way to load & unload a list of tcl commands, the
288     table is in the form :
289 fabian 1.3 { char *func_name, Function *function_to_call }
290 segfault 1.1 these are normal tcl commands (as done in tcl*.c)
291     use { 0, 0 } to indicate the end of the list
292    
293     void add_tcl_ints(tcl_ints *);
294     void rem_tcl_ints(tcl_ints *);
295     provides a way to add/remove links from c variables to tcl variables
296     (add checks to see if the tcl already exists and copies it over the C one)
297     format of table is :
298 fabian 1.3 { char *variable_name, int *variable }
299 segfault 1.1 terminate with {0,0};
300    
301     void add_tcl_strings(tcl_strings *);
302     void rem_tcl_strings(tcl_strings *);
303     provides a way to add/remove links from c strings to tcl strings
304     (also copies exists tcl values)
305     format:
306 fabian 1.3 { char * variable_name, char *string, int length, int flags }
307 segfault 1.1 terminate with { 0, 0, 0, 0 }
308     length: set to 0 if you want a const string.
309     flags: use STR_DIR if you want a / constantly appended,
310     use STR_PROTECT if you want the variable on set in the configfile,
311     not during normal usage.
312    
313 fabian 1.3 void putlog (int logmode, char *channel, char *format, ... )
314 segfault 1.1 logs a comment, see src/eggdrop.h for logmodes, channel makes
315     a channel or "*" for all.
316    
317 fabian 1.3 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
318     void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
319 segfault 1.1 the method of adding/remove bindings for tcl hash tables.
320 fabian 1.2 table is a hash table you find with find_hash_table,
321     cc format:
322 fabian 1.3 { char *command, char *flags, Function *function }
323 fabian 1.2 terminate with { 0, 0, 0, 0 }
324 segfault 1.1 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
325     the same function this does),
326     function is called with exactly the same args as a tcl binding is
327     (except for dcc which does include the handle in C) with type conversion
328     taken into account (e.g. idx's are ints)
329     return much the same as tcl bindings, use int 0/1 for those
330     which require 0/1 or char * for those which require a string (eg filt)
331     or nothing if no return is required.
332     return is also in src/tclhash.c
333 fabian 1.4
334    
335     VI. WHAT TO DO WITH A MODULE?
336    
337     If you have written a module and feel that you want to share
338     it with the rest of the eggdrop comunity, upload it to the incoming
339     directory on ftp.eggheads.org(/pub/eggdrop/incoming). Place a nice
340     descriptive text with it and makes it way to the modules directory.
341     Don't forgot to write for which eggdrop version this module is for...

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23