/[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.14 - (show annotations) (download)
Sun Feb 23 09:52:46 2003 UTC (16 years, 7 months ago) by wcc
Branch: MAIN
Changes since 1.13: +167 -282 lines
* More docs.

1 Eggdrop Module Information
2 Last revised: February 23, 2003
3 _________________________________________________________________
4
5 Eggdrop Module Information
6
7
8 INDEX
9
10 I. What are modules?
11 II. Why use modules?
12 III. How to install a module
13 IV. Modules included with Eggdrop
14 V. Programming modules
15 VI. What to do with a module?
16
17
18 I. What are modules?
19
20 Modules are portions of code which are loaded separately to the bot itself
21 and provide extra services. For example, the filesys module provides the
22 entire file system.
23
24
25 II. Why use modules?
26
27 Modules allow C coders to add their own enhancements to the bot without
28 recompiling the whole thing, and without increasing the size of the Eggdrop
29 core.
30
31
32 III. How to install a module
33
34 Please note that these are only basic instructions for compiling and
35 installing a module. Please read any and all directions included with
36 the module you wish to install.
37
38 1. Download and un-tar the Eggdrop source code.
39
40 2. Place the new module in its own directory (named 'modulename') in
41 modules/.
42
43 3. Run ./bootstrap (from eggdrop1.7.x/).
44
45 4. Run ./configure.
46
47 5. Type 'make'.
48
49 6. Copy the compiled module file (modulename.so) into your bot's modules
50 folder.
51
52 7. Add 'loadmodule modulename' to your eggdrop.conf file (do not
53 add the .so suffix).
54
55 8. Rehash or restart your bot.
56
57 To see your currently running modules type '.module'.
58
59
60 IV. Modules included with eggdrop
61
62 blowfish Eggdrop can encrypt your userfile, so users can have secure
63 passwords. Please note that when you change your encryption
64 method later (i.e. using other modules like a md5 module),
65 you can't use your current userfile anymore. Eggdrop will not
66 start without an encryption module.
67
68 channels This module provides channel related support for the bot.
69 Without it, you won't be able to make the bot join a channel
70 or save channel specific userfile information.
71
72 compress This module provides provides support for file compression.
73 This allows the bot to transfer compressed user files and,
74 therefore, save a significant amount of bandwidth.
75
76 console This module provides storage of console settings when you exit
77 the bot or type .store on the partyline.
78
79 filesys This module provides an area within the bot where users can
80 store files. With this module, the bot is usable as a file
81 server.
82
83 irc This module provides basic IRC support for your bot. You have
84 to load this if you want your bot to come on IRC.
85
86 notes This module provides support for storing of notes for users
87 from each other. Note sending between currently online users
88 is supported in the core, this is only for storing the notes
89 for later retrieval.
90
91 server This module provides the core server support. You have to load
92 this if you want your bot to come on IRC. Not loading this is
93 equivalent to the old NO_IRC define.
94
95 uptime This module reports uptime statistics to http://uptime.eggheads.org.
96 Go look and see what your uptime is! It takes about 9 hours to
97 show up, so if your bot isn't listed, try again later. See
98 doc/settings/mod.uptime for more information, including details
99 on what information is sent to the uptime server.
100
101
102 V. Programming modules
103
104 WARNING:
105 This section is very likely to be out of date. It was not updated for
106 quite some time. The most reliable way to learn about module
107 programming is to take a deep look at the other available modules.
108
109 Note: This is for a simple module of 1 source file. If you're doing a
110 multiple source file module, you shouldn't need to read this anyway. ;)
111
112 (a) Create a modules/<module> directory in your Eggdrop tree and cd to it.
113
114 (b) Create a `Makefile' for your module (see the example module distributed
115 with the bot). This should ensure that your module gets compiled.
116
117 (c) Next, you want to create a file called MODULE.c (MODULE is the module
118 name).
119
120 (1) Things you need to include in your source code:
121
122 (i) #define MODULE_NAME "module-name"
123
124 You MUST use this. It's required by several short cuts in the
125 code, and it's got to be the name you will be using in .loadmod
126
127 (ii) #define MAKING_MODULENAME
128 You MUST also include this, or else the module won't work.
129 MODULENAME is the name of your module (MODULE_NAME), but in caps.
130
131 (iii) #include "lib/eggdrop/module.h"
132
133 This provides all the accessible functions in Eggdrop. Examine
134 lib/eggdrop/module.h closely to find a list of functions available.
135
136 (iv) #include any other standard C header files you might need
137 (Note stdio.h, string.h, stdlib.h, and sys/types.h are already
138 included).
139
140 (v) eggdrop_t *egg = NULL;
141
142 This variable provides access to all the Eggdrop functions; without
143 it, you can't call any Eggdrop functions (heck, the module won't
144 even load).
145
146 (2) CORE functions every module needs.
147
148 *SIDENOTE* I suggest that in a single source file module, you define all
149 functions/variables (except global and module_start) as static. This will
150 drastically reduce the size of modules on decent systems.
151
152 In each of these cases, MODULE refers to the name of your module.
153
154 (i) char *MODULE_start(Function *func_table)
155 - This function is called when the module is first loaded.
156 You MUST do several things in this function:
157 (a) egg = func_table; (so you can make Eggdrop calls)
158
159 (b) module_register(MODULE_NAME, MODULE_table, major, minor);
160 This records details about the module for other modules and
161 Eggdrop itself to access. Major is a major version number,
162 minor is a minor version number, and MODULE_table is a
163 function table (see below).
164
165 (c) module_depend(MODULE_NAME, "another-module", major, minor);
166 This lets Eggdrop know that your module NEEDS "another-module"
167 of major version 'major' and at least minor version 'minor'
168 to run, and hence should try to load it if it's not already
169 here. This will return 1 on success, or 0 if it can't be done
170 (at which stage you should return an error).
171
172 (d) Any other initialization stuff you desire should be included
173 in this function. See below for various things you can do.
174
175 (e) a return value of some sort
176 Returning NULL implies the module loaded successfully,
177 therefor the bot can continue. Returning a non-NULL STRING
178 is an error message. The module (and any other dependant
179 modules) will stop loading and an error will be returned.
180
181 (ii) static Function *MODULE_table = {
182 MODULE_start,
183 MODULE_close,
184 MODULE_expmem,
185 MODULE_report,
186 any_other_functions,
187 you_want_to_export
188 };
189 Ok, it's not a function. It's a list of functions which any
190 other module can call up, so you can provide services for other
191 modules (e.g. transfer has raw_dcc_send in it's table to allow
192 the filesys to send files to others). The first 4 functions are
193 FIXED. You MUST have them; they provide important system info.
194
195 (iii) static char *MODULE_close ()
196 - This is called when the module is unloaded.
197 Apart from tidying any relevant data (I suggest you be thorough,
198 we don't want any trailing garbage from modules), you MUST do
199 the following:
200
201 (a) module_undepend(MODULE_NAME);
202 This lets Eggdrop know your module no longer depends on any
203 other modules.
204
205 (b) Return a value. NULL implies success; any non-NULL STRING
206 implies that the module cannot be unloaded for some reason,
207 and hence the bot should not unload it (see blowfish for
208 an example).
209
210 (iv) static void MODULE_report (int idx)
211 This should provide a relatively short report of the module's
212 status (for .module/.status).
213
214 (3) AVAILABLE FUNCTIONS
215
216 WRITE ME
217
218
219 VI. What to do with a module?
220
221 If you have written a module and feel that you wish to share it with the
222 rest of the Eggdrop community, upload it to the incoming directory on
223 incoming.eggheads.org (/incoming/modules/1.7). Place a nice descriptive
224 text (modulename.desc) with it, and it'll make its way to the modules
225 directory on ftp.eggheads.org. Don't forget to mention in your text file
226 which version Eggdrop the module is written for.
227 _________________________________________________________________
228
229 Copyright (C) 1999, 2000, 2001, 2002, 2003 Eggheads Development Team

webmaster@eggheads.org
ViewVC Help
Powered by ViewVC 1.1.23