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 /* Declare the void's initially up here, as modules dont have an
  29  * include file, we will normally have client_p, source_p, parc
  30  * and parv[] where:
  31  *
  32  * client_p == client issuing command
  33  * source_p == where the command came from
  34  * parc     == the number of parameters
  35  * parv     == an array of the parameters
  36  */
  37
  38 static int munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
  39 static int mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
  40 static int mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
  41 static int mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
  42 static int moper_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
  43
  44 /* Show the commands this module can handle in a msgtab
  45  * and give the msgtab a name, here its test_msgtab
  46  */
  47
  48 struct Message test_msgtab = {
  49   "TEST",               /* the /COMMAND you want */
  50   0,                    /* SET TO ZERO -- number of times command used by clients */
  51   0,                    /* SET TO ZERO -- number of times command used by clients */
  52   0,                    /* SET TO ZERO -- number of times command used by clients */
  53   0,            /* ALWAYS SET TO 0 */
  54
  55   /* the functions to call for each handler.  If not using the generic
  56    * handlers, the first param is the function to call, the second is the
  57    * required number of parameters.  NOTE: If you specify a min para of 2,
  58    * then parv[1] must *also* be non-empty.
  59    */
  60   {
  61     {munreg_test, 0},   /* function call for unregistered clients, 0 parms required */
  62     {mclient_test, 0},  /* function call for local clients, 0 parms required */
  63     {mrclient_test, 0}, /* function call for remote clients, 0 parms required */
  64     {mserver_test, 0},  /* function call for servers, 0 parms required */
  65     mg_ignore,          /* function call for ENCAP, unused in this test */
  66     {moper_test, 0}     /* function call for operators, 0 parms required */
  67   }
  68 };
  69 /*
  70  * There are also some macros for the above function calls and parameter counts.
  71  * Here's a list:
  72  *
  73  * mg_ignore:       ignore the command when it comes from certain types
  74  * mg_not_oper:     tell the client it requires being an operator
  75  * mg_reg:          prevent the client using this if registered
  76  * mg_unreg:        prevent the client using this if unregistered
  77  *
  78  * These macros assume a parameter count of zero; you do not set it.
  79  * For further details, see include/msg.h
  80  */
  81
  82
  83 /* The mapi_clist_av1 indicates which commands (struct Message)
  84  * should be loaded from the module. The list should be terminated
  85  * by a NULL.
  86  */
  87 mapi_clist_av1 test_clist[] = { &test_msgtab, NULL };
  88
  89 /* The mapi_hlist_av1 indicates which hook functions we need to be able to
  90  * call.  We need to declare an integer, then add the name of the hook
  91  * function to call and a pointer to this integer.  The list should be
  92  * terminated with NULLs.
  93  */
  94 int doing_example_hook;
  95 mapi_hlist_av1 test_hlist[] = {
  96         { "doing_example_hook", &doing_example_hook, },
  97         { NULL, NULL }
  98 };
  99
 100 /* The mapi_hfn_list_av1 declares the hook functions which other modules can
 101  * call.  The first parameter is the name of the hook, the second is a void
 102  * returning function, with arbitrary parameters casted to (hookfn).  This
 103  * list must be terminated with NULLs.
 104  */
 105 static void show_example_hook(void *unused);
 106
 107 mapi_hfn_list_av1 test_hfnlist[] = {
 108         { "doing_example_hook", (hookfn) show_example_hook },
 109         { NULL, NULL }
 110 };
 111
 112 /* The mapi_cap_list_av2 declares the capabilities this module adds.  This is
 113  * for protocol usage. Here we declare both server and client capabilities.
 114  * The first parameter is the cap type (server or client). The second is the
 115  * name of the capability we wish to register. The third is the data attached
 116  * to the cap (typically NULL). The last parameter is a pointer to an integer
 117  * for the CAP index (recommended).
 118  */
 119 unsigned int CAP_TESTCAP_SERVER, CAP_TESTCAP_CLIENT;
 120 mapi_cap_list_av2 test_cap_list[] = {
 121         { MAPI_CAP_SERVER, "TESTCAP", NULL, &CAP_TESTCAP_SERVER },
 122         { MAPI_CAP_CLIENT, "testcap", NULL, &CAP_TESTCAP_CLIENT },
 123         { 0, NULL, NULL, NULL }
 124 };
 125
 126 /* Here we tell it what to do when the module is loaded */
 127 static int
 128 modinit(void)
 129 {
 130         /* Nothing to do for the example module. */
 131         /* The init function should return -1 on failure,
 132            which will cause the module to be unloaded,
 133            otherwise 0 to indicate success. */
 134         return 0;
 135 }
 136
 137 /* here we tell it what to do when the module is unloaded */
 138 static void
 139 moddeinit(void)
 140 {
 141         /* Again, nothing to do. */
 142 }
 143
 144 /* DECLARE_MODULE_AV2() actually declare the MAPI header. */
 145 DECLARE_MODULE_AV2(
 146                           /* The first argument is the name */
 147                           example,
 148                           /* The second argument is the function to call on load */
 149                           modinit,
 150                           /* And the function to call on unload */
 151                           moddeinit,
 152                           /* Then the MAPI command list */
 153                           test_clist,
 154                           /* Next the hook list, if we have one. */
 155                           test_hlist,
 156                           /* Then the hook function list, if we have one */
 157                           test_hfnlist,
 158                           /* Then the caps list, if we have one */
 159                           test_cap_list,
 160                           /* Then the version number of this module (NULL for bundled) */
 161                           NULL,
 162                           /* And finally, the description of this module */
 163                           "This is an example module");
 164
 165 /* Any of the above arguments can be NULL to indicate they aren't used. */
 166
 167
 168 /*
 169  * mr_test
 170  *      parv[1] = parameter
 171  */
 172
 173 /* Here we have the functions themselves that we declared above,
 174  * and the fairly normal C coding
 175  */
 176 static int
 177 munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 178 {
 179         if(parc < 2)
 180         {
 181                 sendto_one_notice(source_p, ":You are unregistered and sent no parameters");
 182         }
 183         else
 184         {
 185                 sendto_one_notice(source_p, ":You are unregistered and sent parameter: %s", parv[1]);
 186         }
 187
 188         /* illustration of how to call a hook function */
 189         call_hook(doing_example_hook, NULL);
 190
 191         return 0;
 192 }
 193
 194 /*
 195  * mclient_test
 196  *      parv[1] = parameter
 197  */
 198 static int
 199 mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 200 {
 201         if(parc < 2)
 202         {
 203                 sendto_one_notice(source_p, ":You are a normal user, and sent no parameters");
 204         }
 205         else
 206         {
 207                 sendto_one_notice(source_p, ":You are a normal user, and send parameters: %s", parv[1]);
 208         }
 209
 210         /* illustration of how to call a hook function */
 211         call_hook(doing_example_hook, NULL);
 212
 213         return 0;
 214 }
 215
 216 /*
 217  * mrclient_test
 218  *      parv[1] = parameter
 219  */
 220 static int
 221 mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 222 {
 223         if(parc < 2)
 224         {
 225                 sendto_one_notice(source_p, ":You are a remote client, and sent no parameters");
 226         }
 227         else
 228         {
 229                 sendto_one_notice(source_p, ":You are a remote client, and sent parameters: %s", parv[1]);
 230         }
 231         return 0;
 232 }
 233
 234 /*
 235  * mserver_test
 236  *      parv[1] = parameter
 237  */
 238 static int
 239 mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
 240 {
 241         if(parc < 2)
 242         {
 243                 sendto_one_notice(source_p, ":You are a server, and sent no parameters");
 244         }
 245         else
 246         {
 247                 sendto_one_notice(source_p, ":You are a server, and sent parameters: %s", parv[1]);
 248         }
 249         return 0;
 250 }
 251
 252 /*
 253  * moper_test
 254  *      parv[1] = parameter
 255  */
 256 static int
 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         return 0;
 268 }
 269
 270 static void
 271 show_example_hook(void *unused)
 272 {
 273         sendto_realops_snomask(SNO_GENERAL, L_ALL, "Called example hook!");
 274 }
 275
 276 /* END OF EXAMPLE MODULE */