extensions/example_module.c

   1 /************************************************************************
   2  *   IRC - Internet Relay Chat, doc/example_module.c
   3  *   Copyright (C) 2001 Hybrid Development Team
   4  *
   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)
   8  *   any later version.
   9  *
  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.
  14  *
  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.
  18  */
  19
  20 /* List of ircd includes from ../include/ */
  21 #include "stdinc.h"
  22 #include "modules.h"
  23 #include "hook.h"
  24 #include "client.h"
  25 #include "ircd.h"
  26 #include "send.h"
  27
  28 /* This string describes the module. Always declare it a static const char[].
  29  * It is preferred for stylistic reasons to put it first.
  30  *
  31  * Make it short, sweet, and to the point.
  32  */
  33 static const char example_desc[] = "This is an example Solanum module.";
  34
  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
  37  * and parv[] where:
  38  *
  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
  43  */
  44
  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[]);
  50
  51 /* Show the commands this module can handle in a msgtab
  52  * and give the msgtab a name, here its test_msgtab
  53  */
  54
  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 */
  61
  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.
  66          */
  67         {
  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 */
  74         }
  75 };
  76 /*
  77  * There are also some macros for the above function calls and parameter counts.
  78  * Here's a list:
  79  *
  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
  84  *
  85  * These macros assume a parameter count of zero; you do not set it.
  86  * For further details, see include/msg.h
  87  */
  88
  89
  90 /* The mapi_clist_av1 indicates which commands (struct Message)
  91  * should be loaded from the module. The list should be terminated
  92  * by a NULL.
  93  */
  94 mapi_clist_av1 test_clist[] = { &test_msgtab, NULL };
  95
  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.
 100  */
 101 int doing_example_hook;
 102 mapi_hlist_av1 test_hlist[] = {
 103         { "doing_example_hook", &doing_example_hook, },
 104         { NULL, NULL }
 105 };
 106
 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.
 111  */
 112 static void show_example_hook(void *unused);
 113
 114 mapi_hfn_list_av1 test_hfnlist[] = {
 115         { "doing_example_hook", show_example_hook },
 116         { NULL, NULL }
 117 };
 118
 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).
 125  */
 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 }
 131 };
 132
 133 /* Here we tell it what to do when the module is loaded */
 134 static int
 135 modinit(void)
 136 {
 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. */
 141         return 0;
 142 }
 143
 144 /* here we tell it what to do when the module is unloaded */
 145 static void
 146 moddeinit(void)
 147 {
 148         /* Again, nothing to do. */
 149 }
 150
 151 /* DECLARE_MODULE_AV2() actually declare the MAPI header. */
 152 DECLARE_MODULE_AV2(
 153         /* The first argument is the name */
 154         example,
 155         /* The second argument is the function to call on load */
 156         modinit,
 157         /* And the function to call on unload */
 158         moddeinit,
 159         /* Then the MAPI command list */
 160         test_clist,
 161         /* Next the hook list, if we have one. */
 162         test_hlist,
 163         /* Then the hook function list, if we have one */
 164         test_hfnlist,
 165         /* Then the caps list, if we have one */
 166         test_cap_list,
 167         /* Then the version number of this module (NULL for bundled) */
 168         NULL,
 169         /* And finally, the description of this module */
 170         example_desc);
 171
 172 /* Any of the above arguments can be NULL to indicate they aren't used. */
 173
 174 /*
 175  * mr_test
 176  *      parv[1] = parameter
 177  */
 178
 179 /* Here we have the functions themselves that we declared above,
 180  * and the fairly normal C coding
 181  */
 182 static void
 183 munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 184 {
 185         if(parc < 2)
 186         {
 187                 sendto_one_notice(source_p, ":You are unregistered and sent no parameters");
 188         }
 189         else
 190         {
 191                 sendto_one_notice(source_p, ":You are unregistered and sent parameter: %s", parv[1]);
 192         }
 193
 194         /* illustration of how to call a hook function */
 195         call_hook(doing_example_hook, NULL);
 196 }
 197
 198 /*
 199  * mclient_test
 200  *      parv[1] = parameter
 201  */
 202 static void
 203 mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 204 {
 205         if(parc < 2)
 206         {
 207                 sendto_one_notice(source_p, ":You are a normal user, and sent no parameters");
 208         }
 209         else
 210         {
 211                 sendto_one_notice(source_p, ":You are a normal user, and send parameters: %s", parv[1]);
 212         }
 213
 214         /* illustration of how to call a hook function */
 215         call_hook(doing_example_hook, NULL);
 216 }
 217
 218 /*
 219  * mrclient_test
 220  *      parv[1] = parameter
 221  */
 222 static void
 223 mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 224 {
 225         if(parc < 2)
 226         {
 227                 sendto_one_notice(source_p, ":You are a remote client, and sent no parameters");
 228         }
 229         else
 230         {
 231                 sendto_one_notice(source_p, ":You are a remote client, and sent parameters: %s", parv[1]);
 232         }
 233 }
 234
 235 /*
 236  * mserver_test
 237  *      parv[1] = parameter
 238  */
 239 static void
 240 mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 241 {
 242         if(parc < 2)
 243         {
 244                 sendto_one_notice(source_p, ":You are a server, and sent no parameters");
 245         }
 246         else
 247         {
 248                 sendto_one_notice(source_p, ":You are a server, and sent parameters: %s", parv[1]);
 249         }
 250 }
 251
 252 /*
 253  * moper_test
 254  *      parv[1] = parameter
 255  */
 256 static void
 257 moper_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 258 {
 259         if(parc < 2)
 260         {
 261                 sendto_one_notice(source_p, ":You are an operator, and sent no parameters");
 262         }
 263         else
 264         {
 265                 sendto_one_notice(source_p, ":You are an operator, and sent parameters: %s", parv[1]);
 266         }
 267 }
 268
 269 static void
 270 show_example_hook(void *unused)
 271 {
 272         sendto_realops_snomask(SNO_GENERAL, L_ALL, "Called example hook!");
 273 }
 274
 275 /* END OF EXAMPLE MODULE */