[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"

/* This string describes the module. Always declare it a static const char[].
 * It is preferred for stylistic reasons to put it first.
 *
 * Make it short, sweet, and to the point.
 */
static const char example_desc[] = "This is an example Solanum module.";

/* 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 void munreg_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static void mclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static void mserver_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static void mrclient_test(struct MsgBuf *msgbuf_p, struct Client *client_p, struct Client *source_p, int parc, const char *parv[]);
static void 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", 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 */
	example_desc);

/* 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 void
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);
}

/*
 * mclient_test
 *      parv[1] = parameter
 */
static void
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);
}

/*
 * mrclient_test
 *      parv[1] = parameter
 */
static void
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]);
	}
}

/*
 * mserver_test
 *      parv[1] = parameter
 */
static void
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]);
	}
}

/*
 * moper_test
 *      parv[1] = parameter
 */
static void
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]);
	}
}

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
eeabf33a EM	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	*/
a6f63a82	33	static const char example_desc[] = "This is an example Solanum module.";
eeabf33a	34
212380e3 AC	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
3c7d6fcc EM	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[]);
212380e3 AC	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 = {
eeabf33a EM	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	}
212380e3 AC	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;
55abcbb2	102	mapi_hlist_av1 test_hlist[] = {
212380e3 AC	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[] = {
82436efb	115	{ "doing_example_hook", show_example_hook },
212380e3 AC	116	{ NULL, NULL }
	117	};
	118
4d552723 EM	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 }
de2b673f	131	};
4d552723	132
212380e3 AC	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
4d552723 EM	151	/* DECLARE_MODULE_AV2() actually declare the MAPI header. */
4d552723 EM	152	DECLARE_MODULE_AV2(
eeabf33a EM	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);
212380e3 AC	171
	172	/* Any of the above arguments can be NULL to indicate they aren't used. */
	173
212380e3 AC	174	/*
212380e3 AC	175	* mr_test
212380e3 AC	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	*/
3c7d6fcc	182	static void
760bafda	183	munreg_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	184	{
	185	if(parc < 2)
	186	{
5366977b	187	sendto_one_notice(source_p, ":You are unregistered and sent no parameters");
212380e3 AC	188	}
	189	else
	190	{
5366977b	191	sendto_one_notice(source_p, ":You are unregistered and sent parameter: %s", parv[1]);
212380e3 AC	192	}
	193
	194	/* illustration of how to call a hook function */
	195	call_hook(doing_example_hook, NULL);
212380e3 AC	196	}
	197
	198	/*
	199	* mclient_test
212380e3 AC	200	* parv[1] = parameter
212380e3 AC	201	*/
3c7d6fcc	202	static void
760bafda	203	mclient_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	204	{
	205	if(parc < 2)
	206	{
5366977b	207	sendto_one_notice(source_p, ":You are a normal user, and sent no parameters");
212380e3 AC	208	}
	209	else
	210	{
5366977b	211	sendto_one_notice(source_p, ":You are a normal user, and send parameters: %s", parv[1]);
212380e3 AC	212	}
	213
	214	/* illustration of how to call a hook function */
	215	call_hook(doing_example_hook, NULL);
212380e3 AC	216	}
	217
	218	/*
	219	* mrclient_test
212380e3 AC	220	* parv[1] = parameter
212380e3 AC	221	*/
3c7d6fcc	222	static void
760bafda	223	mrclient_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	224	{
	225	if(parc < 2)
	226	{
5366977b	227	sendto_one_notice(source_p, ":You are a remote client, and sent no parameters");
212380e3 AC	228	}
	229	else
	230	{
5366977b	231	sendto_one_notice(source_p, ":You are a remote client, and sent parameters: %s", parv[1]);
212380e3	232	}
212380e3 AC	233	}
	234
	235	/*
	236	* mserver_test
212380e3 AC	237	* parv[1] = parameter
212380e3 AC	238	*/
3c7d6fcc	239	static void
760bafda	240	mserver_test(struct MsgBuf msgbuf_p, struct Client client_p, struct Client source_p, int parc, const char parv[])
212380e3 AC	241	{
	242	if(parc < 2)
	243	{
5366977b	244	sendto_one_notice(source_p, ":You are a server, and sent no parameters");
212380e3 AC	245	}
	246	else
	247	{
5366977b	248	sendto_one_notice(source_p, ":You are a server, and sent parameters: %s", parv[1]);
212380e3	249	}
212380e3 AC	250	}
	251
	252	/*
	253	* moper_test
212380e3 AC	254	* parv[1] = parameter
212380e3 AC	255	*/
3c7d6fcc	256	static void
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	266	}
212380e3 AC	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 */