/[cvs]/eggdrop1.9/doc/MODULES
ViewVC logotype

Contents of /eggdrop1.9/doc/MODULES

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.7 - (show annotations) (download)
Sun Oct 1 19:12:45 2000 UTC (18 years, 8 months ago) by fabian
Branch: MAIN
Changes since 1.6: +3 -3 lines
fabian: applied Eugene's testfix patch. Slightly edited.

1 EGGDROP MODULE INFORMATION 19 Feb 2000
2
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 WHAT TO DO WITH A MODULE?
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
27
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 .loadmod <module-name>
49 or in a tcl script:
50 loadmod <module-name>
51
52 module-name is the part BEFORE .so, eg filesys.so module
53 you type '.loadmodule filesys'.
54
55 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 '.module'.
60
61
62 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 will just sit on irc, it can respond to msg & ctcp commands,
70 but that's all.
71 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 console : This module provides storage of console settings when you exit
75 the bot (or .store).
76 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 the normal join & maintain channels stuff, this is the module.
83 notes : This provides support for storing of notes for users from each
84 other. Notes between currently online users is supported in
85 the core, this is only for storing the notes for later
86 retrieval, direct user->user notes are built-in.
87 seen : This module provides seen commands via msg, on channel or via
88 dcc, similar to the various scripts.
89 server : This provides the core server support (removing this is
90 equivalent to the old NO_IRC define).
91 share : Userfile sharing.
92 transfer : Handles the transfer of files via botnet or dcc, this is
93 REQUIRED for file sharing.
94 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
106 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
113 (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
117 (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
120 (1) Things you need to include in your source code.
121
122 (i) #define MODULE_NAME "module-name"
123
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 .loadmod
126
127 (ii) #define MAKING_MODULENAME
128 You MUST also include this, or else the module won't work.
129 MODULENAME is the name of your module(MODULE_NAME), but in
130 caps
131
132 (iii) #include "../module.h"
133
134 This provides all the accessible functions in eggdrop,
135 examine closely src/mod/module.h to find a list of functions
136 available.
137
138 (iv) and other standard c include files you might need (Note
139 stdio.h string.h stdlib.h & sys/types.h are already included)
140
141 (v) Function *global;
142
143 This variable provides access to all the eggdrop functions, without
144 it you can't call any eggdrop functions (heck, the module wont
145 even load)
146
147 (2) CORE functions every module needs.
148
149 *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
153 In each of these cases MODULE = module name
154
155 (i) char *MODULE_start(Function *func_table)
156 - this module is called when the module is first loaded,
157 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 (ii) static Function *MODULE_table = {
179 MODULE_start,
180 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 (iii) static char *MODULE_close ()
194 - this is called when the module is unloaded..
195 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 following:
198 (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 this should tally all memory you allocate/deallocate within
207 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 this should provide a relatively short report of module status
213 (for .module/.status)
214
215 (c) AVAILABLE FUNCTIONS - this is what ppl want no? :)
216 (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 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 void *nmalloc (int a); - allocates a bytes
225 void nfree (void *a); - frees a modmalloc'd block
226 context; - actually a #define, records the current
227 - possition in execution, for debugging
228 void dprintf (int idx,char *format, ... ) - just like normal printf,
229 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
238 int module_register ( char *module_name,
239 Function *function_table,
240 int major, int minor )
241 - see above for what/who/why/etc
242 const module_entry *module_find ( char *module_name, int major, int minor);
243 - look for a module, (matching major, >= minor) and return
244 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
250 int module_depend ( char *module_name, char *needed_module,
251 int major, int minor )
252 - 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 int module_undepend ( char *module_name)
256 - marks your module as no longer needing any of it's
257 dependancies
258 void module_rename (char *old_module_name, char *new_module_name)
259 - renames a module, this works so that for exmaple, you
260 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 void add_hook (int hook_num, Function *funcs)
265 void del_hook (int hook_num, Function *funcs)
266
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
284 char *module_load ( char *module_name ); tries to load the given module,
285 returns 0 on success, or an error msg
286
287 char *module_unload ( char *module_name ); tries to unload the given module,
288 returns as above.
289
290 void add_tcl_commands(tcl_cmds *tab);
291 void rem_tcl_commands(tcl_cmds *tab);
292 provides a quick way to load & unload a list of tcl commands, the
293 table is in the form :
294 { char *func_name, Function *function_to_call }
295 these are normal tcl commands (as done in tcl*.c)
296 use { 0, 0 } to indicate the end of the list
297
298 void add_tcl_ints(tcl_ints *);
299 void rem_tcl_ints(tcl_ints *);
300 provides a way to add/remove links from c variables to tcl variables
301 (add checks to see if the tcl already exists and copies it over the C one)
302 format of table is :
303 { char *variable_name, int *variable, int readonly }
304 terminate with {0,0,0};
305
306 void add_tcl_strings(tcl_strings *);
307 void rem_tcl_strings(tcl_strings *);
308 provides a way to add/remove links from c strings to tcl strings
309 (also copies exists tcl values)
310 format:
311 { char * variable_name, char *string, int length, int flags }
312 terminate with { 0, 0, 0, 0 }
313 length: set to 0 if you want a const string.
314 flags: use STR_DIR if you want a / constantly appended,
315 use STR_PROTECT if you want the variable on set in the configfile,
316 not during normal usage.
317
318 void putlog (int logmode, char *channel, char *format, ... )
319 logs a comment, see src/eggdrop.h for logmodes, channel makes
320 a channel or "*" for all.
321
322 void add_builtins (p_tcl_hash_list table, cmd_t *cc);
323 void rem_builtins (p_tcl_hash_list table, cmd_t *cc);
324 the method of adding/remove bindings for tcl hash tables.
325 table is a hash table you find with find_hash_table,
326 cc format:
327 { char *command, char *flags, Function *function }
328 terminate with { 0, 0, 0, 0 }
329 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
330 the same function this does),
331 function is called with exactly the same args as a tcl binding is
332 (except for dcc which does include the handle in C) with type conversion
333 taken into account (e.g. idx's are ints)
334 return much the same as tcl bindings, use int 0/1 for those
335 which require 0/1 or char * for those which require a string (eg filt)
336 or nothing if no return is required.
337 return is also in src/tclhash.c
338
339
340 VI. WHAT TO DO WITH A MODULE?
341
342 If you have written a module and feel that you want to share
343 it with the rest of the eggdrop comunity, upload it to the incoming
344 directory on ftp.eggheads.org(/pub/eggdrop/incoming). Place a nice
345 descriptive text with it and makes it way to the modules directory.
346 Don't forgot to write for which eggdrop version this module is for...

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23