[solanum.git] / extensions / example_module.c

/************************************************************************
 *   IRC - Internet Relay Chat, doc/example_module.c
 *   Copyright (C) 2001 Hybrid Development Team
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation; either version 1, or (at your option)
 *   any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

/* List of ircd includes from ../include/ */
#include "stdinc.h"
#include "modules.h"
#include "hook.h"
#include "client.h"
#include "ircd.h"
#include "send.h"

/* Declare the void's initially up here, as modules dont have an
 * include file, we will normally have client_p, source_p, parc
 * and parv[] where:
 *
 * client_p == client issuing command
 * source_p == where the command came from
 * parc     == the number of parameters
 * parv     == an array of the parameters
 */

static int munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static int mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static int mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static int mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static int moper_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);

/* Show the commands this module can handle in a msgtab
 * and give the msgtab a name, here its test_msgtab
 */

struct Message test_msgtab = {
  "TEST",               /* the /COMMAND you want */
  0,                    /* SET TO ZERO -- number of times command used by clients */
  0,                    /* SET TO ZERO -- number of times command used by clients */
  0,                    /* SET TO ZERO -- number of times command used by clients */
  0,            /* ALWAYS SET TO 0 */

  /* the functions to call for each handler.  If not using the generic
   * handlers, the first param is the function to call, the second is the
   * required number of parameters.  NOTE: If you specify a min para of 2,
   * then parv[1] must *also* be non-empty.
   */
  {
    {munreg_test, 0},   /* function call for unregistered clients, 0 parms required */
    {mclient_test, 0},  /* function call for local clients, 0 parms required */
    {mrclient_test, 0}, /* function call for remote clients, 0 parms required */
    {mserver_test, 0},  /* function call for servers, 0 parms required */
    mg_ignore,          /* function call for ENCAP, unused in this test */
    {moper_test, 0}     /* function call for operators, 0 parms required */
  }
};
/*
 * There are also some macros for the above function calls and parameter counts.
 * Here's a list:
 *
 * mg_ignore:       ignore the command when it comes from certain types
 * mg_not_oper:     tell the client it requires being an operator
 * mg_reg:          prevent the client using this if registered
 * mg_unreg:        prevent the client using this if unregistered
 *
 * These macros assume a parameter count of zero; you do not set it.
 * For further details, see include/msg.h
 */


/* The mapi_clist_av1 indicates which commands (struct Message)
 * should be loaded from the module. The list should be terminated
 * by a NULL.
 */
mapi_clist_av1 test_clist[] = { &test_msgtab, NULL };

/* The mapi_hlist_av1 indicates which hook functions we need to be able to
 * call.  We need to declare an integer, then add the name of the hook
 * function to call and a pointer to this integer.  The list should be
 * terminated with NULLs.
 */
int doing_example_hook;
mapi_hlist_av1 test_hlist[] = {
	{ "doing_example_hook", &doing_example_hook, },
	{ NULL, NULL }
};

/* The mapi_hfn_list_av1 declares the hook functions which other modules can
 * call.  The first parameter is the name of the hook, the second is a void
 * returning function, with arbitrary parameters casted to (hookfn).  This
 * list must be terminated with NULLs.
 */
static void show_example_hook(void *unused);

mapi_hfn_list_av1 test_hfnlist[] = {
	{ "doing_example_hook", (hookfn) show_example_hook },
	{ NULL, NULL }
};

/* The mapi_cap_list_av2 declares the capabilities this module adds.  This is
 * for protocol usage. Here we declare both server and client capabilities.
 * The first parameter is the cap type (server or client). The second is the
 * name of the capability we wish to register. The third is the data attached
 * to the cap (typically NULL). The last parameter is a pointer to an integer
 * for the CAP index (recommended).
 */
unsigned int CAP_TESTCAP_SERVER, CAP_TESTCAP_CLIENT;
mapi_cap_list_av2 test_cap_list[] = {
	{ MAPI_CAP_SERVER, "TESTCAP", NULL, &CAP_TESTCAP_SERVER },
	{ MAPI_CAP_CLIENT, "testcap", NULL, &CAP_TESTCAP_CLIENT },
	{ 0, NULL, NULL, NULL }
};

/* Here we tell it what to do when the module is loaded */
static int
modinit(void)
{
	/* Nothing to do for the example module. */
	/* The init function should return -1 on failure,
	   which will cause the module to be unloaded,
	   otherwise 0 to indicate success. */
	return 0;
}

/* here we tell it what to do when the module is unloaded */
static void
moddeinit(void)
{
	/* Again, nothing to do. */
}

/* DECLARE_MODULE_AV2() actually declare the MAPI header. */
DECLARE_MODULE_AV2(
			  /* The first argument is the name */
			  example,
			  /* The second argument is the function to call on load */
			  modinit,
			  /* And the function to call on unload */
			  moddeinit,
			  /* Then the MAPI command list */
			  test_clist,
			  /* Next the hook list, if we have one. */
			  test_hlist,
			  /* Then the hook function list, if we have one */
			  test_hfnlist,
			  /* Then the caps list, if we have one */
			  test_cap_list,
			  /* Then the version number of this module (NULL for bundled) */
			  NULL,
			  /* And finally, the description of this module */
			  "This is an example module");

/* Any of the above arguments can be NULL to indicate they aren't used. */


/*
 * mr_test
 *      parv[1] = parameter
 */

/* Here we have the functions themselves that we declared above,
 * and the fairly normal C coding
 */
static int
munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
{
	if(parc < 2)
	{
		sendto_one_notice(source_p, ":You are unregistered and sent no parameters");
	}
	else
	{
		sendto_one_notice(source_p, ":You are unregistered and sent parameter: %s", parv[1]);
	}

	/* illustration of how to call a hook function */
	call_hook(doing_example_hook, NULL);

	return 0;
}

/*
 * mclient_test
 *      parv[1] = parameter
 */
static int
mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
{
	if(parc < 2)
	{
		sendto_one_notice(source_p, ":You are a normal user, and sent no parameters");
	}
	else
	{
		sendto_one_notice(source_p, ":You are a normal user, and send parameters: %s", parv[1]);
	}

	/* illustration of how to call a hook function */
	call_hook(doing_example_hook, NULL);

	return 0;
}

/*
 * mrclient_test
 *      parv[1] = parameter
 */
static int
mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
{
	if(parc < 2)
	{
		sendto_one_notice(source_p, ":You are a remote client, and sent no parameters");
	}
	else
	{
		sendto_one_notice(source_p, ":You are a remote client, and sent parameters: %s", parv[1]);
	}
	return 0;
}

/*
 * mserver_test
 *      parv[1] = parameter
 */
static int
mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
{
	if(parc < 2)
	{
		sendto_one_notice(source_p, ":You are a server, and sent no parameters");
	}
	else
	{
		sendto_one_notice(source_p, ":You are a server, and sent parameters: %s", parv[1]);
	}
	return 0;
}

/*
 * moper_test
 *      parv[1] = parameter
 */
static int
moper_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[])
{
	if(parc < 2)
	{
		sendto_one_notice(source_p, ":You are an operator, and sent no parameters");
	}
	else
	{
		sendto_one_notice(source_p, ":You are an operator, and sent parameters: %s", parv[1]);
	}
	return 0;
}

static void
show_example_hook(void *unused)
{
	sendto_realops_snomask(SNO_GENERAL, L_ALL, "Called example hook!");
}

/* END OF EXAMPLE MODULE */
Commit	Line	Data
212380e3 AC	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.
212380e3 AC	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
760bafda AC	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[]);
212380e3 AC	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 */
7baa37a9	53	0, /* ALWAYS SET TO 0 */
212380e3 AC	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;
55abcbb2	95	mapi_hlist_av1 test_hlist[] = {
212380e3 AC	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
4d552723 EM	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 }
de2b673f	124	};
4d552723	125
212380e3 AC	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
4d552723 EM	144	/* DECLARE_MODULE_AV2() actually declare the MAPI header. */
4d552723 EM	145	DECLARE_MODULE_AV2(
212380e3 AC	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,
4d552723 EM	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");
212380e3 AC	164
	165	/* Any of the above arguments can be NULL to indicate they aren't used. */
	166
	167
	168	/*
	169	* mr_test
212380e3 AC	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
760bafda	177	munreg_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	178	{
	179	if(parc < 2)
	180	{
5366977b	181	sendto_one_notice(source_p, ":You are unregistered and sent no parameters");
212380e3 AC	182	}
	183	else
	184	{
5366977b	185	sendto_one_notice(source_p, ":You are unregistered and sent parameter: %s", parv[1]);
212380e3 AC	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
212380e3 AC	196	* parv[1] = parameter
	197	*/
	198	static int
760bafda	199	mclient_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	200	{
	201	if(parc < 2)
	202	{
5366977b	203	sendto_one_notice(source_p, ":You are a normal user, and sent no parameters");
212380e3 AC	204	}
	205	else
	206	{
5366977b	207	sendto_one_notice(source_p, ":You are a normal user, and send parameters: %s", parv[1]);
212380e3 AC	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
212380e3 AC	218	* parv[1] = parameter
	219	*/
	220	static int
760bafda	221	mrclient_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	222	{
	223	if(parc < 2)
	224	{
5366977b	225	sendto_one_notice(source_p, ":You are a remote client, and sent no parameters");
212380e3 AC	226	}
	227	else
	228	{
5366977b	229	sendto_one_notice(source_p, ":You are a remote client, and sent parameters: %s", parv[1]);
212380e3 AC	230	}
	231	return 0;
	232	}
	233
	234	/*
	235	* mserver_test
212380e3 AC	236	* parv[1] = parameter
	237	*/
	238	static int
760bafda	239	mserver_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	240	{
	241	if(parc < 2)
	242	{
5366977b	243	sendto_one_notice(source_p, ":You are a server, and sent no parameters");
212380e3 AC	244	}
	245	else
	246	{
5366977b	247	sendto_one_notice(source_p, ":You are a server, and sent parameters: %s", parv[1]);
212380e3 AC	248	}
	249	return 0;
	250	}
	251
	252	/*
	253	* moper_test
212380e3 AC	254	* parv[1] = parameter
	255	*/
	256	static int
760bafda	257	moper_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	258	{
	259	if(parc < 2)
	260	{
5366977b	261	sendto_one_notice(source_p, ":You are an operator, and sent no parameters");
212380e3 AC	262	}
	263	else
	264	{
5366977b	265	sendto_one_notice(source_p, ":You are an operator, and sent parameters: %s", parv[1]);
212380e3 AC	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 */