/[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.1 - (show annotations) (download)
Mon Sep 13 14:36:18 1999 UTC (20 years, 1 month ago) by segfault
Branch: MAIN
Initial commit based off of .29 cvs

1 ### Module information (not finished yet, but getting there)
2
3 What: modules are portions of code which are loaded seperately to the
4 bot itself, which provided extra services. eg. filesys module
5 provides the entire file system.
6
7 Why: it allows the core eggdrop, that which is minimally required to be
8 reduced, and allows C coders to add their own ehancements to the
9 bot without recompiling the whole thing.
10
11 How: run ./configure as normal, then 'make' to make the eggdrop
12 with module support, this will also compile the modules.
13
14 next do one of two things to load the module:
15 from the partyline (as an owner) type:
16 .loadmodule <module-name>
17 or in a tcl script:
18 loadmodule <module-name>
19
20 module name is the part BEFORE .so, eg filesys.so module
21 you type '.loadmodule filesys'
22
23 to see your currently running modules type '.modules'
24
25 CURRENT MODULES:
26
27 assoc : assoc support happily load & unload at will.
28 blowfish : use it (or some other encryption module someone might
29 write) FROM THE VERY BEGINNING, the first password you make
30 will be invalid if load this later
31 use 'loadmodule blowfish' in your config file,
32 it's relatively safe to load&unload once your running, but
33 remember, whilst it's unloaded, no-one can login.
34 channels : provides channel related support for the bot, without it, it
35 will just sit on irc, it can respond to msg & ctcp commands,
36 but that's all.
37 console : this module provides storage of console settings when you exit
38 the bot (or .store).
39 ctcp : this provides the normal ctcp replies that you'd expect.
40 filesys : the file system, this is relatively stable and you should be
41 able to load & unload at will, with the following restriction.
42 and users in the file area will currently just hang when you
43 unload the module and resume when it's reloaded, if they EOF
44 before then, and unexplained eof will occur and the bot will
45 clean it up.
46 irc : this module provides ALL NORMAL IRC INTERACTION, if you want
47 the normal join & maintain channels stuff, this is the module.
48 notes : this provides support for storing of notes for users from each
49 other. notes between currently online users is supported in
50 the core, this is only for storing the notes for later
51 retrieval, direct user->user notes are built-in.
52 seen : this module provides seen commands via msg, on channel or via
53 dcc, similar to the various scripts.
54 server : this provides the core server support (removing this is
55 equivalent to the old NO_IRC define).
56 share : userfile sharing.
57 transfer : handles the transfer of files via botnet or dcc, this is
58 REQUIRED for file sharing.
59 wire : an encrypted partyline communication.
60 woobie : just a fun, bizarre test module.
61
62 This is VERY experimental at this stage, so be wary :)
63
64 PROGRAMMING THE SUCKERS: (The step by step guide)
65 note: this is for a simple module of 1 source file, if you're doing a multiple
66 source file module, you shouldn't need to read this anyway ;)
67
68 (a) create a src/mod/module.mod directory in your eggdrop distro
69 (where module is the module name) and cd to it.
70
71 (b) create a small file called Makefile with the following contents:
72
73 FILENAME=module
74 include ../Makefile.generic
75
76 (again with module as the module name), this ensures a make will
77 compile it.
78
79 (c) next you want to create a file called module.c (again module is the
80 module name), and here's where the work starts :)
81
82 (1) things you need to include in your source code.
83 (i) #define MODULE_NAME "module-name"
84 You MUST use this, it's required by several short cuts in the
85 code, it's gotta be the name you will be using in .loadmodule
86 (ii) #include "../module.h"
87 this provides all the accessible functions in eggdrop,
88 examine closely src/mod/module.h to find a list of functions
89 available (not, this is still in flux, and you will need to
90 recompile a module when a new version comes out)
91 (iii) and other standard c include files you might need
92 (note stdio.h string.h stdlib.h & sys/types.h are already included)
93 (iv) Function * global;
94 This variable provides access to all the eggdrop functions, without
95 it you can't call any eggdrop functions (heck, the module wont
96 even load)
97 (2) CORE functions every module needs.
98
99 *SIDENOTE* I suggest in a single source file module you define all
100 functions/variables (except global & module_start) as static, this will
101 drastically reduce the size of modules on decent systems.
102
103 in each of these cases MODULE = module name
104
105 (i) char * MODULE_start(Function * func_table)
106 - this module is called when the module is first loaded,
107 you MUST do serveral things in this function
108 (a) global = func_table; (so you can make eggdrop calls)
109 (b) module_register(MODULE_NAME,MODULE_table,major,minor);
110 this records details about the module for other modules
111 & eggdrop itself to access, major is a major version number,
112 minor is a minor version number, MODULE_table is a function
113 table (see below)
114 (c) module_depend(MODULE_NAME,"another-module",major,minor);
115 this lets eggdrop know that your module NEEDS "another-module"
116 of major version 'major' and at least minor version 'minor'
117 to run and hence should try to load it if it's not already here
118 this will return 1 on success, or 0 if it cant be done
119 (at which stage you should return an error)
120 (d) any other initialization stuff you desire, see below for
121 various things you can do.
122 (e) a return value of some sort, returning NULL implies the module
123 loaded successfully, and so the bot can continue.
124 return a non-NULL STRING is an error message, the module
125 (and any other dependant modules) will stop loading
126 and an error will be returned.
127
128 (ii) static Function * MODULE_table = {
129 MODULE_start,
130 MODULE_close,
131 MODULE_expmem,
132 MODULE_report,
133 any_other_functions,
134 you_want_to_export
135 };
136 ok, it's not a function, it's a list of functions, which any
137 other module can call up, so you can provide services for other
138 modules (eg transfer has raw_dcc_send in it's table to allow
139 the filesys to send files to others)
140 the first 4 functions are FIXED, you MUST have them, they
141 provide important system info.
142
143 (iii) static char * MODULE_close ()
144 - this is called when the module is unloaded..
145 apart from tidying any relevant data (I suggest you be thorough,
146 we don't want any trailing garbage from modules) you MUST do the
147 following:
148 (a) module_undepend(MODULE_NAME);
149 this lets eggdrop know your module no longer depends on
150 any other modules.
151 (b) return a value, NULL implies success, non-NULL STRING implies
152 the module cannot be unloaded for some reason and hence
153 the bot should leave it in (see blowfish for an example)
154
155 (iv) static int MODULE_expmem ()
156 this should tally all memory you allocate/deallocate within
157 the module (using modmalloc & modfree), it's used by memory
158 debugging to track memory faults, and by .status to total up
159 memory usage.
160
161 (v) static void MODULE_report (int idx)
162 this should provide a relatively short report of module status
163 (for .modules/.status)
164
165 (c) AVALIABLE FUNCTIONS - this is what ppl want no? :)
166 (i) reliable ones, you can RELY on these functions being available,
167 they may move in the tables for the moment (since it's a work
168 in progress) but they will be there...
169 This is just a short list of the ones you need to make
170 a mildly useful module, a goodly portion of the remaining
171 eggdrop functions are avaliable, check src/mod/module.h for
172 info.
173
174 void * nmalloc (int a); - allocates a bytes
175 void nfree (void * a); - frees a modmalloc'd block
176 context; - actually a #define, records the current
177 - possition in execution, for debugging
178 void dprintf (int idx,char * format, ... ) - just like normal printf,
179 outputs to a dcc/socket/server,
180 idx is a normal dcc idx OR if < 0 is a sock #
181 OR one of: DP_LOG (send to log file)
182 DP_STDOUT (send to stdout)
183 DP_MODE (send via mode queue to sever) *fast*
184 DP_SERVER (send via normal queue to sever) *normal*
185 DP_HELP (send via help queue to sever) - use this
186 for mass outputs to users
187
188 int module_register ( char * module_name,
189 Function * function_table,
190 int major, int minor )
191 - see above for what/who/why/etc
192 const module_entry * module_find ( char * module_name, int major, int minor);
193 - look for a module, (matching major, >= minor) and return
194 info about it....members of module_entry...
195 char * name; - module name (duh)
196 int major; - real major version
197 int minor; - real minor version
198 Function * funcs; - function table (see above)
199
200 int module_depend ( char * module_name, char * needed_module,
201 int major, int minor )
202 - marks your module (module_name) as needing needed_module
203 (matching major, >= minor) and tries to load said module
204 if it's not already loaded. returns 1 on success
205 int module_undpend ( char * module_name)
206 - marks your module as no longer needing any of it's
207 dependancies
208 void module_rename (char * old_module_name, char * new_module_name)
209 - renames a module, this works so that for exmaple, you
210 could have efnet.so, undernet.so, ircnet.so & dalnet.so
211 and they called all rename themselves as server.so which
212 is what you really want
213
214 void add_hook (int hook_num, Function * funcs)
215 void del_hook (int hook_num, Function * funcs)
216
217 used for adding removing hooks into eggdrop code, on various events, these
218 functions are called, depending on the hook
219
220 valid hooks:
221
222 HOOK_SECONDLY - called every second
223 HOOK_MINUTELY - called every minute
224 HOOK_5MINUTELY - called every 5 minutes
225 HOOK_HOURLY - called every hour, (at hourly-updates minutes past)
226 HOOK_DAILY - called every day, when the logfiles are switched
227 HOOK_READ_USERFILE - called when the userfile is read
228 HOOK_USERFILE - called when the userfile is written
229 HOOK_PRE_REHASH - called just *before* rehash
230 HOOK_REHASH - called just after rehash
231 HOOK_IDLE - called whenever the dcc connections have been idle
232 for a whole second
233
234 char * module_load ( char * module_name ); tries to load the given module,
235 returns 0 on success, or an error msg
236
237 char * module_unload ( char * module_name ); tries to unload the given module,
238 returns as above.
239
240 void add_tcl_commands(tcl_cmds * tab);
241 void rem_tcl_commands(tcl_cmds * tab);
242 provides a quick way to load & unload a list of tcl commands, the
243 table is in the form :
244 { char * func_name, Function * function_to_call }
245 these are normal tcl commands (as done in tcl*.c)
246 use { 0, 0 } to indicate the end of the list
247
248 void add_tcl_ints(tcl_ints *);
249 void rem_tcl_ints(tcl_ints *);
250 provides a way to add/remove links from c variables to tcl variables
251 (add checks to see if the tcl already exists and copies it over the C one)
252 format of table is :
253 { char * variable_name, int * variable }
254 terminate with {0,0};
255
256 void add_tcl_strings(tcl_strings *);
257 void rem_tcl_strings(tcl_strings *);
258 provides a way to add/remove links from c strings to tcl strings
259 (also copies exists tcl values)
260 format:
261 { char * variable_name, char * string, int length, int flags }
262 terminate with { 0, 0, 0, 0 }
263 length: set to 0 if you want a const string.
264 flags: use STR_DIR if you want a / constantly appended,
265 use STR_PROTECT if you want the variable on set in the configfile,
266 not during normal usage.
267
268 void putlog (int logmode, char * channel, char * format, ... )
269 logs a comment, see src/eggdrop.h for logmodes, channel makes
270 a channel or "*" for all.
271
272 void add_builtins (p_tcl_hash_list table, cmd_t * cc);
273 void rem_builtins (p_tcl_hash_list table, cmd_t * cc);
274 the method of adding/remove bindings for tcl hash tables.
275 table is a hash table you find with find_hash_table, cc format:
276 { char * command, char * flags, Function * function }
277 this is EXACTLY like a bind command in tcl, (heck, tcl_bind calls
278 the same function this does),
279 function is called with exactly the same args as a tcl binding is
280 (except for dcc which does include the handle in C) with type conversion
281 taken into account (e.g. idx's are ints)
282 return much the same as tcl bindings, use int 0/1 for those
283 which require 0/1 or char * for those which require a string (eg filt)
284 or nothing if no return is required.
285 return is also in src/tclhash.c

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23