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