/[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.1.1.1 - (show annotations) (download) (vendor branch)
Mon Jul 26 21:11:06 2010 UTC (9 years, 8 months ago) by simple
Branch: eggheads
CVS Tags: v1
Changes since 1.1: +0 -0 lines
Imported Eggdrop 1.6.20

1 $Id: MODULES,v 1.36 2010/07/05 12:07:05 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.6.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 wire This module provides all the standard .wire partyline commands.
129 It is an encrypted partyline communication tool, compatible with
130 wire.tcl.
131
132 woobie This is for demonstrative purposes only. If you are looking for
133 starting point in writing modules, woobie is the right thing.
134
135
136 5. Programming modules
137
138 WARNING: This section is very likely to be out of date.
139
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.
142
143 1. Create a src/mod/MODULE.mod directory in your Eggdrop directory (where
144 MODULE is the module name) and cd to it.
145
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.
149
150 3. Next, you want to create a file called MODULE.c (MODULE is the module
151 name again).
152
153 4. You MUST include the following in your source code:
154
155 a. #define MODULE_NAME "module-name"
156
157 This should be defined to the same name you will be using when you load
158 your module.
159
160 b. #define MAKING_MODULENAME
161
162 MODULENAME is the name of your module (MODULE_NAME), but in all caps.
163
164 c. #include "../module.h"
165
166 This provides access to Eggdrop's global function table. Examine
167 src/mod/module.h closely to find a list of functions available.
168
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.
171
172 e. Function *global;
173
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).
176
177 5. Every module must also have the following functions:
178
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.
182
183 Throughout step 5, MODULE refers to the module name. Note that
184 "MODULE_NAME" should literally be "MODULE_NAME".
185
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:
189
190 global = func_table;
191
192 This allows you to make calls to the global function table.
193
194 module_register(MODULE_NAME, MODULE_table, MAJOR, MINOR);
195
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).
200
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).
207
208 Any other initialization stuff you desire should also be included in
209 this function. See below for various things you can do.
210
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.
215
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 };
224
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.
228
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:
233
234 module_undepend(MODULE_NAME);
235 This lets Eggdrop know your module no longer depends on any other
236 modules.
237
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).
241
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.
246
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).
250
251 These functions are available to modules. MANY more available functions
252 can be found in src/mod/module.h.
253
254 void *nmalloc(int j);
255
256 This allocates j bytes of memory.
257
258 void nfree(void *a);
259
260 This frees an nmalloc'd block of memory.
261
262 Context;
263
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.
267
268 void dprintf(int idx, char *format, ...)
269
270 This acts like a normal printf() function, but it outputs to
271 log/socket/idx.
272
273 idx is a normal dcc idx, or if < 0 is a sock number.
274
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
281
282 const module_entry *module_find(char *module_name, int major, int minor);
283
284 Searches for a loaded module (matching major, >= minor), and returns
285 info about it.
286
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)
292
293 void module_rename(char *old_module_name, char *new_module_name)
294
295 This renames a module frim old_module_name to new_module_name.
296
297 void add_hook(int hook_num, Function *funcs)
298 void del_hook(int hook_num, Function *funcs)
299
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
307
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
317
318 char *module_unload (char *module_name);
319 char *module_load (char *module_name);
320
321 Tries to load or unload the specified module; returns 0 on success, or
322 an error message.
323
324 void add_tcl_commands(tcl_cmds *tab);
325 void rem_tcl_commands(tcl_cmds *tab);
326
327 Provides a quick way to create and remove a table of Tcl commands. The
328 table is in the form of:
329
330 {char *func_name, Function *function_to_call}
331
332 Use { NULL, NULL } to indicate the end of the list.
333
334 void add_tcl_ints(tcl_ints *);
335 void rem_tcl_ints(tcl_ints *);
336
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:
340
341 {char *variable_name, int *variable, int readonly}
342
343 Use {NULL, NULL, 0} to indicate the end of the list.
344
345 void add_tcl_strings(tcl_strings *);
346 void rem_tcl_strings(tcl_strings *);
347
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:
352
353 {char *variable_name, char *string, int length, int flags}
354
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.
359
360 void add_builtins(p_tcl_hash_list table, cmd_t *cc);
361 void rem_builtins(p_tcl_hash_list table, cmd_t *cc);
362
363 This adds binds to one of Eggdrop's bind tables. The format of the
364 table is:
365
366 {char *command, char *flags, Function *function, char *displayname}
367
368 Use {NULL, NULL, NULL, NULL} to indicate the end of the list.
369
370 This works EXACTLY like the Tcl 'bind' command. displayname is what Tcl
371 sees this function's proc name as (in .binds all).
372
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.
378
379 void putlog (int logmode, char *channel, char *format, ...)
380
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.
384
385
386 6. What to do with a module?
387
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.6). 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 _____________________________________________________________________
395
396 Copyright (C) 1999 - 2010 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23