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

Contents of /eggdrop1.8/doc/MODULES

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


Revision 1.3 - (show annotations) (download)
Sun Oct 24 12:39:36 2010 UTC (8 years, 7 months ago) by pseudo
Branch: MAIN
CVS Tags: HEAD
Branch point for: gettext
Changes since 1.2: +1 -5 lines
Removed wire.mod and all references to it. Botnet and partyline encryption are now available using ssl.

1 $Id: MODULES,v 1.2 2010/07/27 21:49:41 pseudo Exp $
2
3 Eggdrop Module Information
4 Last revised: March 04, 2003
5 _____________________________________________________________________
6
7 Eggdrop Module Information
8
9
10 The purpose of this document is to show you how to download, install, create,
11 and submit modules.
12
13 Contents:
14 1. What are modules?
15 2. Why use modules?
16 3. How to install a module
17 4. Modules included with Eggdrop
18 5. Programming modules
19 6. What to do with a finished module
20
21
22 1. What are modules?
23
24 Modules are portions of code which are loaded separately to the bot itself
25 and provide extra services. For example, the filesys module provides the
26 entire file system.
27
28
29 2. Why use modules?
30
31 Modules allow C coders to add their own enhancements to the bot while
32 keeping them optional and without increasing the size of the Eggdrop core.
33
34
35 3. How to install a module
36
37 Please note that these are only basic instructions for compiling and
38 installing a module. Please read any and all directions included with
39 the module you wish to install.
40
41 1. Download and un-tar the Eggdrop source code.
42
43 2. Place the new module in its own directory (in the format of
44 (modulename).mod) in src/mod.
45
46 3. Run ./configure (from eggdrop1.8.x/).
47
48 4. Type 'make config' or 'make iconfig'.
49
50 5. Type 'make'.
51
52 6. Copy the compiled module file (modulename.so) into your bot's
53 modules folder.
54
55 7. Add 'loadmodule modulename' to your eggdrop.conf file (do not
56 add the .so suffix).
57
58 8. Rehash or restart your bot.
59
60 To view your currently loaded modules, type '.module'.
61
62
63 4. Modules included with Eggdrop
64
65 assoc This module provides assoc support, i.e. naming channels on the
66 botnet.
67
68 blowfish Eggdrop can encrypt your userfile, so users can have secure
69 passwords. Please note that when you change your encryption
70 method later (i.e. using other modules like a md5 module),
71 you can't use your current userfile anymore. Eggdrop will not
72 start without an encryption module.
73
74 channels This module provides channel related support for the bot.
75 Without it, you won't be able to make the bot join a channel
76 or save channel specific userfile information.
77
78 compress This module provides provides support for file compression. This
79 allows the bot to transfer compressed user files and, therefore,
80 save a significant amount of bandwidth.
81
82 console This module provides storage of console settings when you exit
83 the bot or type .store on the partyline.
84
85 ctcp This module provides the normal ctcp replies that you'd expect.
86 Without it loaded, CTCP CHAT will not work.
87
88 dns This module provides asynchronous dns support. This will avoid
89 long periods where the bot just hangs there, waiting for a
90 hostname to resolve, which will often let it timeout on all
91 other connections.
92
93 filesys This module provides an area within the bot where users can store
94 and manage files. With this module, the bot is usable as a file
95 server.
96
97 irc This module provides basic IRC support for your bot. You have to
98 load this if you want your bot to come on IRC.
99
100 notes This module provides support for storing of notes for users from
101 each other. Note sending between currently online users is
102 supported in the core, this is only for storing the notes for
103 later retrieval.
104
105 seen This module provides very basic seen commands via msg, on channel
106 or via dcc. This module works only for users in the bot's
107 userlist. If you are looking for a better and more advanced seen
108 module, try the gseen module by G'Quann. You can find it at
109 http://www.kreativrauschen.com/gseen.mod/.
110
111 server This module provides the core server support. You have to load
112 this if you want your bot to come on IRC. Not loading this is
113 equivalent to the old NO_IRC define.
114
115 share This module provides userfile sharing support between two
116 directly linked bots.
117
118 transfer The transfer module provides DCC SEND/GET support and userfile
119 transfer support for userfile sharing.
120
121 uptime This module reports uptime statistics to the uptime contest
122 web site at http://uptime.eggheads.org. Go look and see what
123 your uptime is! It takes about 9 hours to show up, so if your
124 bot isn't listed, try again later. See doc/settings/mod.uptime
125 for more information, including details on what information is
126 sent to the uptime server.
127
128 woobie This is for demonstrative purposes only. If you are looking for
129 starting point in writing modules, woobie is the right thing.
130
131
132 5. Programming modules
133
134 WARNING: This section is very likely to be out of date.
135
136 Note: This is for a simple module of 1 source file. If you're doing a
137 multiple source file module, you shouldn't need to read this anyway.
138
139 1. Create a src/mod/MODULE.mod directory in your Eggdrop directory (where
140 MODULE is the module name) and cd to it.
141
142 2. Copy the file `Makefile' from src/mod/woobie.mod and replace all
143 occurrences of `woobie' with your module name. This should ensure
144 that your module gets compiled.
145
146 3. Next, you want to create a file called MODULE.c (MODULE is the module
147 name again).
148
149 4. You MUST include the following in your source code:
150
151 a. #define MODULE_NAME "module-name"
152
153 This should be defined to the same name you will be using when you load
154 your module.
155
156 b. #define MAKING_MODULENAME
157
158 MODULENAME is the name of your module (MODULE_NAME), but in all caps.
159
160 c. #include "../module.h"
161
162 This provides access to Eggdrop's global function table. Examine
163 src/mod/module.h closely to find a list of functions available.
164
165 d. #include any other standard c header files you might need. Note that
166 stdio.h, string.h, stdlib.h, and sys/types.h are already included.
167
168 e. Function *global;
169
170 This variable provides access to all the Eggdrop functions; without it,
171 you can't call any Eggdrop functions (the module won't even load).
172
173 5. Every module must also have the following functions:
174
175 In most modules, all functions/variables (except global and MODULE_start)
176 should be static. This will drastically reduce the size of modules on
177 decent systems.
178
179 Throughout step 5, MODULE refers to the module name. Note that
180 "MODULE_NAME" should literally be "MODULE_NAME".
181
182 a. char *MODULE_start(Function *func_table)
183 This function is called when the module is first loaded. There are
184 several things that need to be done in this function:
185
186 global = func_table;
187
188 This allows you to make calls to the global function table.
189
190 module_register(MODULE_NAME, MODULE_table, MAJOR, MINOR);
191
192 This records details about the module for other modules and Eggdrop
193 itself to access. MAJOR and MINOR are ints, where MAJOR is the
194 module's major version number and MINOR is a minor version number.
195 MODULE_table is a function table (see below).
196
197 module_depend(MODULE_NAME, "another-module", MAJOR, MINOR);
198 This lets Eggdrop know that your module NEEDS "another-module" of
199 major version 'MAJOR' and at least minor version 'MINOR' to run,
200 and hence should try to load it if it's not already loaded. This
201 will return 1 on success, or 0 if it can't be done (at which stage
202 you should return an error).
203
204 Any other initialization stuff you desire should also be included in
205 this function. See below for various things you can do.
206
207 You also will need to return a value. Returning NULL implies the
208 module loaded successfully. Returning a non-NULL STRING is an error
209 message. The module (and any other dependant modules) will stop
210 loading and an error will be returned.
211
212 b. static Function *MODULE_table = {
213 MODULE_start,
214 MODULE_close,
215 MODULE_expmem,
216 MODULE_report,
217 any_other_functions,
218 you_want_to_export
219 };
220
221 This is a table of functions which any other module can access. The
222 first 4 functions are FIXED. You MUST have them; they provide important
223 module information.
224
225 c. static char *MODULE_close ()
226 This is called when the module is unloaded. Apart from tidying any
227 relevant data (I suggest you be thorough, we don't want any trailing
228 garbage from modules), you MUST do the following:
229
230 module_undepend(MODULE_NAME);
231 This lets Eggdrop know your module no longer depends on any other
232 modules.
233
234 Return a value. NULL implies success; any non-NULL STRING implies
235 that the module cannot be unloaded for some reason, and hence the
236 bot should not unload it (see the blowfish module for an example).
237
238 d. static int MODULE_expmem ()
239 This should tally all memory you allocate/deallocate within the module
240 (using nmalloc, nfree, etc) in bytes. It's used by memory debugging to
241 track memory faults, and it is used by .status to total up memory usage.
242
243 e. static void MODULE_report (int idx)
244 This should provide a relatively short report of the module's status
245 (for the module and status commands).
246
247 These functions are available to modules. MANY more available functions
248 can be found in src/mod/module.h.
249
250 void *nmalloc(int j);
251
252 This allocates j bytes of memory.
253
254 void nfree(void *a);
255
256 This frees an nmalloc'd block of memory.
257
258 Context;
259
260 Actually a macro -- records the current position in execution (for
261 debugging). Using Context is no longer recommended, because it uses
262 too many resources and a core file provides much more information.
263
264 void dprintf(int idx, char *format, ...)
265
266 This acts like a normal printf() function, but it outputs to
267 log/socket/idx.
268
269 idx is a normal dcc idx, or if < 0 is a sock number.
270
271 Other destinations:
272 DP_LOG - send to log file
273 DP_STDOUT - send to stdout
274 DP_MODE - send via mode queue to the server
275 DP_SERVER - send via normal queue to the server
276 DP_HELP - send via help queue to server
277
278 const module_entry *module_find(char *module_name, int major, int minor);
279
280 Searches for a loaded module (matching major, >= minor), and returns
281 info about it.
282
283 Members of module_entry:
284 char *name; - module name
285 int major; - real major version
286 int minor; - real minor version
287 Function *funcs; - function table (see above)
288
289 void module_rename(char *old_module_name, char *new_module_name)
290
291 This renames a module frim old_module_name to new_module_name.
292
293 void add_hook(int hook_num, Function *funcs)
294 void del_hook(int hook_num, Function *funcs)
295
296 These are used for adding or removing hooks to/from Eggdrop code that
297 are triggered on various events. Valid hooks are:
298 HOOK_SECONDLY - called every second
299 HOOK_MINUTELY - called every minute
300 HOOK_5MINUTELY - called every 5 minutes
301 HOOK_HOURLY - called every hour (hourly-updates minutes past)
302 HOOK_DAILY - called when the logfiles are switched
303
304 HOOK_READ_USERFILE - called when the userfile is read
305 HOOK_USERFILE - called when the userfile is written
306 HOOK_PRE_REHASH - called just before a rehash
307 HOOK_REHASH - called just after a rehash
308 HOOK_IDLE - called whenever the dcc connections have been
309 idle for a whole second
310 HOOK_BACKUP - called when a user/channel file backup is done
311 HOOK_LOADED - called when Eggdrop is first loaded
312 HOOK_DIE - called when Eggdrop is about to die
313
314 char *module_unload (char *module_name);
315 char *module_load (char *module_name);
316
317 Tries to load or unload the specified module; returns 0 on success, or
318 an error message.
319
320 void add_tcl_commands(tcl_cmds *tab);
321 void rem_tcl_commands(tcl_cmds *tab);
322
323 Provides a quick way to create and remove a table of Tcl commands. The
324 table is in the form of:
325
326 {char *func_name, Function *function_to_call}
327
328 Use { NULL, NULL } to indicate the end of the list.
329
330 void add_tcl_ints(tcl_ints *);
331 void rem_tcl_ints(tcl_ints *);
332
333 Provides a quick way to create and remove a table of links from C
334 int variables to Tcl variables (add_tcl_ints checks to see if the Tcl
335 variable exists and copies it over the C one). The format of table is:
336
337 {char *variable_name, int *variable, int readonly}
338
339 Use {NULL, NULL, 0} to indicate the end of the list.
340
341 void add_tcl_strings(tcl_strings *);
342 void rem_tcl_strings(tcl_strings *);
343
344 Provides a quick way to create and remove a table of links from C
345 string variables to Tcl variables (add_tcl_ints checks to see if the
346 Tcl variable exists and copies it over the C one). The format of table
347 is:
348
349 {char *variable_name, char *string, int length, int flags}
350
351 Use {NULL, NULL, 0, 0} to indicate the end of the list. Use 0 for
352 length if you want a const string. Use STR_DIR for flags if you want a
353 '/' constantly appended; use STR_PROTECT if you want the variable set
354 in the config file, but not during normal usage.
355
356 void add_builtins(p_tcl_hash_list table, cmd_t *cc);
357 void rem_builtins(p_tcl_hash_list table, cmd_t *cc);
358
359 This adds binds to one of Eggdrop's bind tables. The format of the
360 table is:
361
362 {char *command, char *flags, Function *function, char *displayname}
363
364 Use {NULL, NULL, NULL, NULL} to indicate the end of the list.
365
366 This works EXACTLY like the Tcl 'bind' command. displayname is what Tcl
367 sees this function's proc name as (in .binds all).
368
369 function is called with exactly the same args as a Tcl binding is with
370 type conversion taken into account (e.g. idx's are ints). Return values
371 are much the same as Tcl bindings. Use int 0/1 for those which require
372 0/1, or char * for those which require a string (auch as filt). Return
373 nothing if no return value is required.
374
375 void putlog (int logmode, char *channel, char *format, ...)
376
377 Adds text to a logfile (determined by logmode and channel). This text
378 will also output to any users' consoles if they have the specified
379 console mode enabled.
380
381
382 6. What to do with a module?
383
384 If you have written a module and feel that you wish to share it with the
385 rest of the Eggdrop community, upload it to the incoming directory on
386 incoming.eggheads.org (/incoming/modules/1.8). Place a nice descriptive
387 text (modulename.desc) with it, and it'll make its way to the modules
388 directory on ftp.eggheads.org. Don't forget to mention in your text file
389 which version Eggdrop the module is written for.
390 _____________________________________________________________________
391
392 Copyright (C) 1999 - 2010 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23