ViewVC logotype

Contents of /eggdrop1.8/doc/MODULES

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

Revision 1.2 - (show annotations) (download)
Tue Jul 27 21:49:41 2010 UTC (9 years, 8 months ago) by pseudo
Branch: MAIN
Changes since 1.1: +3 -3 lines
Updated documentation to reference 1.8 instead of 1.6.
Changed module dependencies to 1.8.
Changed default handle length to 32.
Changed default make type to 'debug' as it should be in CVS builds.

1 $Id: MODULES,v 2010/07/26 21:11:06 simple Exp $
3 Eggdrop Module Information
4 Last revised: March 04, 2003
5 _____________________________________________________________________
7 Eggdrop Module Information
10 The purpose of this document is to show you how to download, install, create,
11 and submit modules.
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
22 1. What are modules?
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.
29 2. Why use modules?
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.
35 3. How to install a module
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.
41 1. Download and un-tar the Eggdrop source code.
43 2. Place the new module in its own directory (in the format of
44 (modulename).mod) in src/mod.
46 3. Run ./configure (from eggdrop1.8.x/).
48 4. Type 'make config' or 'make iconfig'.
50 5. Type 'make'.
52 6. Copy the compiled module file (modulename.so) into your bot's
53 modules folder.
55 7. Add 'loadmodule modulename' to your eggdrop.conf file (do not
56 add the .so suffix).
58 8. Rehash or restart your bot.
60 To view your currently loaded modules, type '.module'.
63 4. Modules included with Eggdrop
65 assoc This module provides assoc support, i.e. naming channels on the
66 botnet.
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.
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.
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.
82 console This module provides storage of console settings when you exit
83 the bot or type .store on the partyline.
85 ctcp This module provides the normal ctcp replies that you'd expect.
86 Without it loaded, CTCP CHAT will not work.
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.
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.
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.
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.
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/.
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.
115 share This module provides userfile sharing support between two
116 directly linked bots.
118 transfer The transfer module provides DCC SEND/GET support and userfile
119 transfer support for userfile sharing.
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.
128 wire This module provides all the standard .wire partyline commands.
129 It is an encrypted partyline communication tool, compatible with
130 wire.tcl.
132 woobie This is for demonstrative purposes only. If you are looking for
133 starting point in writing modules, woobie is the right thing.
136 5. Programming modules
138 WARNING: This section is very likely to be out of date.
140 Note: This is for a simple module of 1 source file. If you're doing a
141 multiple source file module, you shouldn't need to read this anyway.
143 1. Create a src/mod/MODULE.mod directory in your Eggdrop directory (where
144 MODULE is the module name) and cd to it.
146 2. Copy the file `Makefile' from src/mod/woobie.mod and replace all
147 occurrences of `woobie' with your module name. This should ensure
148 that your module gets compiled.
150 3. Next, you want to create a file called MODULE.c (MODULE is the module
151 name again).
153 4. You MUST include the following in your source code:
155 a. #define MODULE_NAME "module-name"
157 This should be defined to the same name you will be using when you load
158 your module.
160 b. #define MAKING_MODULENAME
162 MODULENAME is the name of your module (MODULE_NAME), but in all caps.
164 c. #include "../module.h"
166 This provides access to Eggdrop's global function table. Examine
167 src/mod/module.h closely to find a list of functions available.
169 d. #include any other standard c header files you might need. Note that
170 stdio.h, string.h, stdlib.h, and sys/types.h are already included.
172 e. Function *global;
174 This variable provides access to all the Eggdrop functions; without it,
175 you can't call any Eggdrop functions (the module won't even load).
177 5. Every module must also have the following functions:
179 In most modules, all functions/variables (except global and MODULE_start)
180 should be static. This will drastically reduce the size of modules on
181 decent systems.
183 Throughout step 5, MODULE refers to the module name. Note that
184 "MODULE_NAME" should literally be "MODULE_NAME".
186 a. char *MODULE_start(Function *func_table)
187 This function is called when the module is first loaded. There are
188 several things that need to be done in this function:
190 global = func_table;
192 This allows you to make calls to the global function table.
194 module_register(MODULE_NAME, MODULE_table, MAJOR, MINOR);
196 This records details about the module for other modules and Eggdrop
197 itself to access. MAJOR and MINOR are ints, where MAJOR is the
198 module's major version number and MINOR is a minor version number.
199 MODULE_table is a function table (see below).
201 module_depend(MODULE_NAME, "another-module", MAJOR, MINOR);
202 This lets Eggdrop know that your module NEEDS "another-module" of
203 major version 'MAJOR' and at least minor version 'MINOR' to run,
204 and hence should try to load it if it's not already loaded. This
205 will return 1 on success, or 0 if it can't be done (at which stage
206 you should return an error).
208 Any other initialization stuff you desire should also be included in
209 this function. See below for various things you can do.
211 You also will need to return a value. Returning NULL implies the
212 module loaded successfully. Returning a non-NULL STRING is an error
213 message. The module (and any other dependant modules) will stop
214 loading and an error will be returned.
216 b. static Function *MODULE_table = {
217 MODULE_start,
218 MODULE_close,
219 MODULE_expmem,
220 MODULE_report,
221 any_other_functions,
222 you_want_to_export
223 };
225 This is a table of functions which any other module can access. The
226 first 4 functions are FIXED. You MUST have them; they provide important
227 module information.
229 c. static char *MODULE_close ()
230 This is called when the module is unloaded. Apart from tidying any
231 relevant data (I suggest you be thorough, we don't want any trailing
232 garbage from modules), you MUST do the following:
234 module_undepend(MODULE_NAME);
235 This lets Eggdrop know your module no longer depends on any other
236 modules.
238 Return a value. NULL implies success; any non-NULL STRING implies
239 that the module cannot be unloaded for some reason, and hence the
240 bot should not unload it (see the blowfish module for an example).
242 d. static int MODULE_expmem ()
243 This should tally all memory you allocate/deallocate within the module
244 (using nmalloc, nfree, etc) in bytes. It's used by memory debugging to
245 track memory faults, and it is used by .status to total up memory usage.
247 e. static void MODULE_report (int idx)
248 This should provide a relatively short report of the module's status
249 (for the module and status commands).
251 These functions are available to modules. MANY more available functions
252 can be found in src/mod/module.h.
254 void *nmalloc(int j);
256 This allocates j bytes of memory.
258 void nfree(void *a);
260 This frees an nmalloc'd block of memory.
262 Context;
264 Actually a macro -- records the current position in execution (for
265 debugging). Using Context is no longer recommended, because it uses
266 too many resources and a core file provides much more information.
268 void dprintf(int idx, char *format, ...)
270 This acts like a normal printf() function, but it outputs to
271 log/socket/idx.
273 idx is a normal dcc idx, or if < 0 is a sock number.
275 Other destinations:
276 DP_LOG - send to log file
277 DP_STDOUT - send to stdout
278 DP_MODE - send via mode queue to the server
279 DP_SERVER - send via normal queue to the server
280 DP_HELP - send via help queue to server
282 const module_entry *module_find(char *module_name, int major, int minor);
284 Searches for a loaded module (matching major, >= minor), and returns
285 info about it.
287 Members of module_entry:
288 char *name; - module name
289 int major; - real major version
290 int minor; - real minor version
291 Function *funcs; - function table (see above)
293 void module_rename(char *old_module_name, char *new_module_name)
295 This renames a module frim old_module_name to new_module_name.
297 void add_hook(int hook_num, Function *funcs)
298 void del_hook(int hook_num, Function *funcs)
300 These are used for adding or removing hooks to/from Eggdrop code that
301 are triggered on various events. Valid hooks are:
302 HOOK_SECONDLY - called every second
303 HOOK_MINUTELY - called every minute
304 HOOK_5MINUTELY - called every 5 minutes
305 HOOK_HOURLY - called every hour (hourly-updates minutes past)
306 HOOK_DAILY - called when the logfiles are switched
308 HOOK_READ_USERFILE - called when the userfile is read
309 HOOK_USERFILE - called when the userfile is written
310 HOOK_PRE_REHASH - called just before a rehash
311 HOOK_REHASH - called just after a rehash
312 HOOK_IDLE - called whenever the dcc connections have been
313 idle for a whole second
314 HOOK_BACKUP - called when a user/channel file backup is done
315 HOOK_LOADED - called when Eggdrop is first loaded
316 HOOK_DIE - called when Eggdrop is about to die
318 char *module_unload (char *module_name);
319 char *module_load (char *module_name);
321 Tries to load or unload the specified module; returns 0 on success, or
322 an error message.
324 void add_tcl_commands(tcl_cmds *tab);
325 void rem_tcl_commands(tcl_cmds *tab);
327 Provides a quick way to create and remove a table of Tcl commands. The
328 table is in the form of:
330 {char *func_name, Function *function_to_call}
332 Use { NULL, NULL } to indicate the end of the list.
334 void add_tcl_ints(tcl_ints *);
335 void rem_tcl_ints(tcl_ints *);
337 Provides a quick way to create and remove a table of links from C
338 int variables to Tcl variables (add_tcl_ints checks to see if the Tcl
339 variable exists and copies it over the C one). The format of table is:
341 {char *variable_name, int *variable, int readonly}
343 Use {NULL, NULL, 0} to indicate the end of the list.
345 void add_tcl_strings(tcl_strings *);
346 void rem_tcl_strings(tcl_strings *);
348 Provides a quick way to create and remove a table of links from C
349 string variables to Tcl variables (add_tcl_ints checks to see if the
350 Tcl variable exists and copies it over the C one). The format of table
351 is:
353 {char *variable_name, char *string, int length, int flags}
355 Use {NULL, NULL, 0, 0} to indicate the end of the list. Use 0 for
356 length if you want a const string. Use STR_DIR for flags if you want a
357 '/' constantly appended; use STR_PROTECT if you want the variable set
358 in the config file, but not during normal usage.
360 void add_builtins(p_tcl_hash_list table, cmd_t *cc);
361 void rem_builtins(p_tcl_hash_list table, cmd_t *cc);
363 This adds binds to one of Eggdrop's bind tables. The format of the
364 table is:
366 {char *command, char *flags, Function *function, char *displayname}
368 Use {NULL, NULL, NULL, NULL} to indicate the end of the list.
370 This works EXACTLY like the Tcl 'bind' command. displayname is what Tcl
371 sees this function's proc name as (in .binds all).
373 function is called with exactly the same args as a Tcl binding is with
374 type conversion taken into account (e.g. idx's are ints). Return values
375 are much the same as Tcl bindings. Use int 0/1 for those which require
376 0/1, or char * for those which require a string (auch as filt). Return
377 nothing if no return value is required.
379 void putlog (int logmode, char *channel, char *format, ...)
381 Adds text to a logfile (determined by logmode and channel). This text
382 will also output to any users' consoles if they have the specified
383 console mode enabled.
386 6. What to do with a module?
388 If you have written a module and feel that you wish to share it with the
389 rest of the Eggdrop community, upload it to the incoming directory on
390 incoming.eggheads.org (/incoming/modules/1.8). Place a nice descriptive
391 text (modulename.desc) with it, and it'll make its way to the modules
392 directory on ftp.eggheads.org. Don't forget to mention in your text file
393 which version Eggdrop the module is written for.
394 _____________________________________________________________________
396 Copyright (C) 1999 - 2010 Eggheads Development Team

ViewVC Help
Powered by ViewVC 1.1.23