/[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.3 - (hide annotations) (download)
Fri Feb 25 21:51:29 2000 UTC (19 years, 7 months ago) by fabian
Branch: MAIN
Changes since 1.2: +139 -97 lines
configure_module 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     VI
12    
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.3 console : This module provides storage of console settings when you exit
72 segfault 1.1 the bot (or .store).
73 fabian 1.3 ctcp : This provides the normal ctcp replies that you'd expect.
74     dns : This module provides asynchronous dns support which avoids
75     blocking on dns lookups. Especially useful for busy hub bots.
76     filesys : The file system. If you unload it all users currently using
77     the it will be disconnected from the bot.
78     irc : This module provides ALL NORMAL IRC INTERACTION, if you want
79 segfault 1.1 the normal join & maintain channels stuff, this is the module.
80 fabian 1.3 notes : This provides support for storing of notes for users from each
81     other. Notes between currently online users is supported in
82 segfault 1.1 the core, this is only for storing the notes for later
83     retrieval, direct user->user notes are built-in.
84 fabian 1.3 seen : This module provides seen commands via msg, on channel or via
85 segfault 1.1 dcc, similar to the various scripts.
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 wire : An encrypted partyline communication.
92     woobie : Just a fun, bizarre test module which serves as an example for
93     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 segfault 1.1
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     code, it's gotta be the name you will be using in .loadmodule
123 fabian 1.3
124     (ii) #include "../module.h"
125    
126     This provides all the accessible functions in eggdrop,
127 segfault 1.1 examine closely src/mod/module.h to find a list of functions
128 fabian 1.3 available.
129    
130     (iii) and other standard c include files you might need (Note
131     stdio.h string.h stdlib.h & sys/types.h are already included)
132    
133     (iv) Function *global;
134    
135 segfault 1.1 This variable provides access to all the eggdrop functions, without
136     it you can't call any eggdrop functions (heck, the module wont
137     even load)
138 fabian 1.3
139 segfault 1.1 (2) CORE functions every module needs.
140    
141     *SIDENOTE* I suggest in a single source file module you define all
142     functions/variables (except global & module_start) as static, this will
143     drastically reduce the size of modules on decent systems.
144    
145 fabian 1.3 In each of these cases MODULE = module name
146 segfault 1.1
147 fabian 1.3 (i) char *MODULE_start(Function *func_table)
148 segfault 1.1 - this module is called when the module is first loaded,
149     you MUST do serveral things in this function
150     (a) global = func_table; (so you can make eggdrop calls)
151 fabian 1.3 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
152 segfault 1.1 this records details about the module for other modules
153     & eggdrop itself to access, major is a major version number,
154     minor is a minor version number, MODULE_table is a function
155     table (see below)
156 fabian 1.3 (c) module_depend(MODULE_NAME, "another-module", major, minor);
157 segfault 1.1 this lets eggdrop know that your module NEEDS "another-module"
158     of major version 'major' and at least minor version 'minor'
159     to run and hence should try to load it if it's not already here
160     this will return 1 on success, or 0 if it cant be done
161     (at which stage you should return an error)
162     (d) any other initialization stuff you desire, see below for
163     various things you can do.
164     (e) a return value of some sort, returning NULL implies the module
165     loaded successfully, and so the bot can continue.
166     return a non-NULL STRING is an error message, the module
167     (and any other dependant modules) will stop loading
168     and an error will be returned.
169    
170 fabian 1.3 (ii) static Function *MODULE_table = {
171 segfault 1.1 MODULE_start,
172     MODULE_close,
173     MODULE_expmem,
174     MODULE_report,
175     any_other_functions,
176     you_want_to_export
177     };
178     ok, it's not a function, it's a list of functions, which any
179     other module can call up, so you can provide services for other
180     modules (eg transfer has raw_dcc_send in it's table to allow
181     the filesys to send files to others)
182     the first 4 functions are FIXED, you MUST have them, they
183     provide important system info.
184    
185 fabian 1.3 (iii) static char *MODULE_close ()
186 segfault 1.1 - this is called when the module is unloaded..
187     apart from tidying any relevant data (I suggest you be thorough,
188     we don't want any trailing garbage from modules) you MUST do the
189     following:
190     (a) module_undepend(MODULE_NAME);
191     this lets eggdrop know your module no longer depends on
192     any other modules.
193     (b) return a value, NULL implies success, non-NULL STRING implies
194     the module cannot be unloaded for some reason and hence
195     the bot should leave it in (see blowfish for an example)
196    
197     (iv) static int MODULE_expmem ()
198     this should tally all memory you allocate/deallocate within
199     the module (using modmalloc & modfree), it's used by memory
200     debugging to track memory faults, and by .status to total up
201     memory usage.
202    
203     (v) static void MODULE_report (int idx)
204     this should provide a relatively short report of module status
205     (for .modules/.status)
206    
207     (c) AVALIABLE FUNCTIONS - this is what ppl want no? :)
208     (i) reliable ones, you can RELY on these functions being available,
209     they may move in the tables for the moment (since it's a work
210     in progress) but they will be there...
211     This is just a short list of the ones you need to make
212     a mildly useful module, a goodly portion of the remaining
213     eggdrop functions are avaliable, check src/mod/module.h for
214     info.
215    
216 fabian 1.3 void *nmalloc (int a); - allocates a bytes
217     void nfree (void *a); - frees a modmalloc'd block
218 segfault 1.1 context; - actually a #define, records the current
219     - possition in execution, for debugging
220 fabian 1.3 void dprintf (int idx,char *format, ... ) - just like normal printf,
221 segfault 1.1 outputs to a dcc/socket/server,
222     idx is a normal dcc idx OR if < 0 is a sock #
223     OR one of: DP_LOG (send to log file)
224     DP_STDOUT (send to stdout)
225     DP_MODE (send via mode queue to sever) *fast*
226     DP_SERVER (send via normal queue to sever) *normal*
227     DP_HELP (send via help queue to sever) - use this
228     for mass outputs to users
229    
230 fabian 1.3 int module_register ( char *module_name,
231     Function *function_table,
232 segfault 1.1 int major, int minor )
233     - see above for what/who/why/etc
234 fabian 1.3 const module_entry *module_find ( char *module_name, int major, int minor);
235 segfault 1.1 - look for a module, (matching major, >= minor) and return
236     info about it....members of module_entry...
237 fabian 1.3 char *name; - module name (duh)
238 segfault 1.1 int major; - real major version
239     int minor; - real minor version
240 fabian 1.3 Function *funcs; - function table (see above)
241 segfault 1.1
242 fabian 1.3 int module_depend ( char *module_name, char *needed_module,
243 segfault 1.1 int major, int minor )
244     - marks your module (module_name) as needing needed_module
245     (matching major, >= minor) and tries to load said module
246     if it's not already loaded. returns 1 on success
247 fabian 1.3 int module_undpend ( char *module_name)
248 segfault 1.1 - marks your module as no longer needing any of it's
249     dependancies
250 fabian 1.3 void module_rename (char *old_module_name, char *new_module_name)
251 segfault 1.1 - renames a module, this works so that for exmaple, you
252     could have efnet.so, undernet.so, ircnet.so & dalnet.so
253     and they called all rename themselves as server.so which
254     is what you really want
255    
256 fabian 1.3 void add_hook (int hook_num, Function *funcs)
257     void del_hook (int hook_num, Function *funcs)
258 segfault 1.1
259     used for adding removing hooks into eggdrop code, on various events, these
260     functions are called, depending on the hook
261    
262     valid hooks:
263    
264     HOOK_SECONDLY - called every second
265     HOOK_MINUTELY - called every minute
266     HOOK_5MINUTELY - called every 5 minutes
267     HOOK_HOURLY - called every hour, (at hourly-updates minutes past)
268     HOOK_DAILY - called every day, when the logfiles are switched
269     HOOK_READ_USERFILE - called when the userfile is read
270     HOOK_USERFILE - called when the userfile is written
271     HOOK_PRE_REHASH - called just *before* rehash
272     HOOK_REHASH - called just after rehash
273     HOOK_IDLE - called whenever the dcc connections have been idle
274     for a whole second
275    
276 fabian 1.3 char *module_load ( char *module_name ); tries to load the given module,
277 segfault 1.1 returns 0 on success, or an error msg
278    
279 fabian 1.3 char *module_unload ( char *module_name ); tries to unload the given module,
280 segfault 1.1 returns as above.
281    
282 fabian 1.3 void add_tcl_commands(tcl_cmds *tab);
283     void rem_tcl_commands(tcl_cmds *tab);
284 segfault 1.1 provides a quick way to load & unload a list of tcl commands, the
285     table is in the form :
286 fabian 1.3 { char *func_name, Function *function_to_call }
287 segfault 1.1 these are normal tcl commands (as done in tcl*.c)
288     use { 0, 0 } to indicate the end of the list
289    
290     void add_tcl_ints(tcl_ints *);
291     void rem_tcl_ints(tcl_ints *);
292     provides a way to add/remove links from c variables to tcl variables
293     (add checks to see if the tcl already exists and copies it over the C one)
294     format of table is :
295 fabian 1.3 { char *variable_name, int *variable }
296 segfault 1.1 terminate with {0,0};
297    
298     void add_tcl_strings(tcl_strings *);
299     void rem_tcl_strings(tcl_strings *);
300     provides a way to add/remove links from c strings to tcl strings
301     (also copies exists tcl values)
302     format:
303 fabian 1.3 { char * variable_name, char *string, int length, int flags }
304 segfault 1.1 terminate with { 0, 0, 0, 0 }
305     length: set to 0 if you want a const string.
306     flags: use STR_DIR if you want a / constantly appended,
307     use STR_PROTECT if you want the variable on set in the configfile,
308     not during normal usage.
309    
310 fabian 1.3 void putlog (int logmode, char *channel, char *format, ... )
311 segfault 1.1 logs a comment, see src/eggdrop.h for logmodes, channel makes
312     a channel or "*" for all.
313    
314 fabian 1.3 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
315     void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
316 segfault 1.1 the method of adding/remove bindings for tcl hash tables.
317 fabian 1.2 table is a hash table you find with find_hash_table,
318     cc format:
319 fabian 1.3 { char *command, char *flags, Function *function }
320 fabian 1.2 terminate with { 0, 0, 0, 0 }
321 segfault 1.1 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
322     the same function this does),
323     function is called with exactly the same args as a tcl binding is
324     (except for dcc which does include the handle in C) with type conversion
325     taken into account (e.g. idx's are ints)
326     return much the same as tcl bindings, use int 0/1 for those
327     which require 0/1 or char * for those which require a string (eg filt)
328     or nothing if no return is required.
329     return is also in src/tclhash.c

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23