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

Annotation of /eggdrop1.8/doc/MODULES

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


Revision 1.3 - (hide 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 pseudo 1.3 $Id: MODULES,v 1.2 2010/07/27 21:49:41 pseudo Exp $
2 simple 1.1
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 pseudo 1.2 3. Run ./configure (from eggdrop1.8.x/).
47 simple 1.1
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 pseudo 1.2 incoming.eggheads.org (/incoming/modules/1.8). Place a nice descriptive
387 simple 1.1 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