1 /************************************************************************
2 * IRC - Internet Relay Chat, doc/example_module.c
3 * Copyright (C) 2001 Hybrid Development Team
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 1, or (at your option)
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20 /* List of ircd includes from ../include/ */
28 /* This string describes the module. Always declare it a static const char[].
29 * It is preferred for stylistic reasons to put it first.
31 * Make it short, sweet, and to the point.
33 static const char example_desc
[] = "This is an example Charybdis module.";
35 /* Declare the void's initially up here, as modules dont have an
36 * include file, we will normally have client_p, source_p, parc
39 * client_p == client issuing command
40 * source_p == where the command came from
41 * parc == the number of parameters
42 * parv == an array of the parameters
45 static void munreg_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[]);
46 static void mclient_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[]);
47 static void mserver_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[]);
48 static void mrclient_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[]);
49 static void moper_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[]);
51 /* Show the commands this module can handle in a msgtab
52 * and give the msgtab a name, here its test_msgtab
55 struct Message test_msgtab
= {
56 "TEST", /* the /COMMAND you want */
57 0, /* SET TO ZERO -- number of times command used by clients */
58 0, /* SET TO ZERO -- number of times command used by clients */
59 0, /* SET TO ZERO -- number of times command used by clients */
60 0, /* ALWAYS SET TO 0 */
62 /* the functions to call for each handler. If not using the generic
63 * handlers, the first param is the function to call, the second is the
64 * required number of parameters. NOTE: If you specify a min para of 2,
65 * then parv[1] must *also* be non-empty.
68 {munreg_test
, 0}, /* function call for unregistered clients, 0 parms required */
69 {mclient_test
, 0}, /* function call for local clients, 0 parms required */
70 {mrclient_test
, 0}, /* function call for remote clients, 0 parms required */
71 {mserver_test
, 0}, /* function call for servers, 0 parms required */
72 mg_ignore
, /* function call for ENCAP, unused in this test */
73 {moper_test
, 0} /* function call for operators, 0 parms required */
77 * There are also some macros for the above function calls and parameter counts.
80 * mg_ignore: ignore the command when it comes from certain types
81 * mg_not_oper: tell the client it requires being an operator
82 * mg_reg: prevent the client using this if registered
83 * mg_unreg: prevent the client using this if unregistered
85 * These macros assume a parameter count of zero; you do not set it.
86 * For further details, see include/msg.h
90 /* The mapi_clist_av1 indicates which commands (struct Message)
91 * should be loaded from the module. The list should be terminated
94 mapi_clist_av1 test_clist
[] = { &test_msgtab
, NULL
};
96 /* The mapi_hlist_av1 indicates which hook functions we need to be able to
97 * call. We need to declare an integer, then add the name of the hook
98 * function to call and a pointer to this integer. The list should be
99 * terminated with NULLs.
101 int doing_example_hook
;
102 mapi_hlist_av1 test_hlist
[] = {
103 { "doing_example_hook", &doing_example_hook
, },
107 /* The mapi_hfn_list_av1 declares the hook functions which other modules can
108 * call. The first parameter is the name of the hook, the second is a void
109 * returning function, with arbitrary parameters casted to (hookfn). This
110 * list must be terminated with NULLs.
112 static void show_example_hook(void *unused
);
114 mapi_hfn_list_av1 test_hfnlist
[] = {
115 { "doing_example_hook", (hookfn
) show_example_hook
},
119 /* The mapi_cap_list_av2 declares the capabilities this module adds. This is
120 * for protocol usage. Here we declare both server and client capabilities.
121 * The first parameter is the cap type (server or client). The second is the
122 * name of the capability we wish to register. The third is the data attached
123 * to the cap (typically NULL). The last parameter is a pointer to an integer
124 * for the CAP index (recommended).
126 unsigned int CAP_TESTCAP_SERVER
, CAP_TESTCAP_CLIENT
;
127 mapi_cap_list_av2 test_cap_list
[] = {
128 { MAPI_CAP_SERVER
, "TESTCAP", NULL
, &CAP_TESTCAP_SERVER
},
129 { MAPI_CAP_CLIENT
, "testcap", NULL
, &CAP_TESTCAP_CLIENT
},
130 { 0, NULL
, NULL
, NULL
}
133 /* Here we tell it what to do when the module is loaded */
137 /* Nothing to do for the example module. */
138 /* The init function should return -1 on failure,
139 which will cause the module to be unloaded,
140 otherwise 0 to indicate success. */
144 /* here we tell it what to do when the module is unloaded */
148 /* Again, nothing to do. */
151 /* DECLARE_MODULE_AV2() actually declare the MAPI header. */
153 /* The first argument is the name */
155 /* The second argument is the function to call on load */
157 /* And the function to call on unload */
159 /* Then the MAPI command list */
161 /* Next the hook list, if we have one. */
163 /* Then the hook function list, if we have one */
165 /* Then the caps list, if we have one */
167 /* Then the version number of this module (NULL for bundled) */
169 /* And finally, the description of this module */
172 /* Any of the above arguments can be NULL to indicate they aren't used. */
176 * parv[1] = parameter
179 /* Here we have the functions themselves that we declared above,
180 * and the fairly normal C coding
183 munreg_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[])
187 sendto_one_notice(source_p
, ":You are unregistered and sent no parameters");
191 sendto_one_notice(source_p
, ":You are unregistered and sent parameter: %s", parv
[1]);
194 /* illustration of how to call a hook function */
195 call_hook(doing_example_hook
, NULL
);
200 * parv[1] = parameter
203 mclient_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[])
207 sendto_one_notice(source_p
, ":You are a normal user, and sent no parameters");
211 sendto_one_notice(source_p
, ":You are a normal user, and send parameters: %s", parv
[1]);
214 /* illustration of how to call a hook function */
215 call_hook(doing_example_hook
, NULL
);
220 * parv[1] = parameter
223 mrclient_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[])
227 sendto_one_notice(source_p
, ":You are a remote client, and sent no parameters");
231 sendto_one_notice(source_p
, ":You are a remote client, and sent parameters: %s", parv
[1]);
237 * parv[1] = parameter
240 mserver_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[])
244 sendto_one_notice(source_p
, ":You are a server, and sent no parameters");
248 sendto_one_notice(source_p
, ":You are a server, and sent parameters: %s", parv
[1]);
254 * parv[1] = parameter
257 moper_test(struct MsgBuf
*msgbuf_p
, struct Client
*client_p
, struct Client
*source_p
, int parc
, const char *parv
[])
261 sendto_one_notice(source_p
, ":You are an operator, and sent no parameters");
265 sendto_one_notice(source_p
, ":You are an operator, and sent parameters: %s", parv
[1]);
270 show_example_hook(void *unused
)
272 sendto_realops_snomask(SNO_GENERAL
, L_ALL
, "Called example hook!");
275 /* END OF EXAMPLE MODULE */