[irc/rqf/shadowircd.git] / doc / hooks.txt

Hook documentation - <lee -at- leeh.co.uk>
------------------------------------------

Documentation on how to actually develop code to use hooks is contained in
contrib/example_module.c, this document simply describes which hooks are
available.

There are various hook structures available that may be passed to hooks:
hook_data		- struct Client *client; const void *arg1; 
			  const void *arg2;
hook_data_int		- struct Client *client; const void *arg1; int arg2;
hook_data_client	- struct Client *client; struct Client *target;
hook_data_channel	- struct Client *client; struct Channel *chptr;


Spy Hooks
---------
The following spy hooks are called only when the request is handled by the
local server.  They will not be called if the command is being sent remotely
for another server to handle:
"doing_admin"		- Passes hook_data:
			  hdata->client = client requesting ADMIN

"doing_info"		- Passes hook_data:
			  hdata->client = client requesting INFO

"doing_links"		- Passes hook_data:
			  hdata->client = client doing LINKS
			  (const char *) hdata->arg1 = optional mask

"doing_motd"		- Passes hook_data:
			  hdata->client = client doing MOTD

"doing_stats"		- Passes hook_data_int:
			  hdata->client = client doing STATS
			  (const char *) hdata->arg1 = optional stats l target
			  (char) hdata->arg2 = statchar being requested

"doing_stats_p"		- Passes hook_data:
			  hdata->client = client doing STATS p

"doing_trace"		- Passes hook_data_client:
			  hdata->client = client doing TRACE
			  hdata->target = optional target of TRACE

"doing_whois"		- Passes hook_data_client:
			  hdata->client = local client doing WHOIS
			  hdata->target = target of WHOIS

"doing_whois_global"	- Passes hook_data_client:
			  hdata->client = remote client doing WHOIS
			  hdata->target = target of WHOIS


Netburst Hooks
--------------
The following burst hooks are called when we are sending a netburst to a
server.

"burst_client"		- Sent after we have just burst a user.
			  Passes hook_data_client:
			  hdata->client = server we are bursting to
			  hdata->target = user we have just burst

"burst_channel"		- Sent after we have just burst a channel.
			  Passes hook_data_channel:
			  hdata->client = server we are bursting to
			  hdata->chptr = channel we have just burst

"burst_finished"	- Sent after we have just finished bursting users/chans
			  Passes hook_data_client:
			  hdata->client = server we are bursting to


Server Hooks
------------
The following hooks are called during server connects/exits.

"server_eob"		- Sent after a server finishes bursting to us.
			  Passes struct Client, the server that has
			  finished bursting.

"server_introduced"	- Sent after a server is introduced to the network,
			  local or remote.
			  Passes hook_data_client:
			  hdata->client = uplink server (&me if local)
			  hdata->target = server being introduced


Client Hooks
------------
The following hooks are called during various events related to clients.

"introduce_client"	- Sent after introducing a client to the (rest of the)
			  network.
			  Passes hook_data_client:
			  hdata->client = server that introduced this client
			  hdata->target = client being introduced

"new_local_user"	- Sent just before introducing a new local user
			  to the network.
			  Passes struct Client, the client being introduced.

"new_remote_user"	- Sent just before introducing a new remote user
			  to the rest of the network.
			  Passes struct Client, the client being introduced.

"umode_changed"		- Sent each time a user's mode or snomask changes.
			  Passes hook_data_umode_changed:
			  client = client whose modes are changing
			  oldumodes = new user mode field
			  oldsnomask = new snomask field


The following are for debugging and take struct hook_io_data for arguments. 
These can be used for a variety of purposes, but are aimed at the developer
community.
"iosend"
"iorecv"
"iorecvctrl"

$Id: hooks.txt 710 2006-02-06 03:10:01Z gxti $
Commit	Line	Data
212380e3	1	Hook documentation - <lee -at- leeh.co.uk>
	2	------------------------------------------
	3
	4	Documentation on how to actually develop code to use hooks is contained in
	5	contrib/example_module.c, this document simply describes which hooks are
	6	available.
	7
	8	There are various hook structures available that may be passed to hooks:
	9	hook_data - struct Client client; const void arg1;
	10	const void *arg2;
	11	hook_data_int - struct Client client; const void arg1; int arg2;
	12	hook_data_client - struct Client client; struct Client target;
	13	hook_data_channel - struct Client client; struct Channel chptr;
	14
	15
	16	Spy Hooks
	17	---------
	18	The following spy hooks are called only when the request is handled by the
	19	local server. They will not be called if the command is being sent remotely
	20	for another server to handle:
	21	"doing_admin" - Passes hook_data:
	22	hdata->client = client requesting ADMIN
	23
	24	"doing_info" - Passes hook_data:
	25	hdata->client = client requesting INFO
	26
	27	"doing_links" - Passes hook_data:
	28	hdata->client = client doing LINKS
	29	(const char *) hdata->arg1 = optional mask
	30
	31	"doing_motd" - Passes hook_data:
	32	hdata->client = client doing MOTD
	33
	34	"doing_stats" - Passes hook_data_int:
	35	hdata->client = client doing STATS
	36	(const char *) hdata->arg1 = optional stats l target
	37	(char) hdata->arg2 = statchar being requested
	38
	39	"doing_stats_p" - Passes hook_data:
	40	hdata->client = client doing STATS p
	41
	42	"doing_trace" - Passes hook_data_client:
	43	hdata->client = client doing TRACE
	44	hdata->target = optional target of TRACE
	45
	46	"doing_whois" - Passes hook_data_client:
	47	hdata->client = local client doing WHOIS
	48	hdata->target = target of WHOIS
	49
	50	"doing_whois_global" - Passes hook_data_client:
	51	hdata->client = remote client doing WHOIS
	52	hdata->target = target of WHOIS
	53
	54
	55	Netburst Hooks
	56	--------------
	57	The following burst hooks are called when we are sending a netburst to a
	58	server.
	59
	60	"burst_client" - Sent after we have just burst a user.
	61	Passes hook_data_client:
	62	hdata->client = server we are bursting to
	63	hdata->target = user we have just burst
	64
65	"burst_channel" - Sent after we have just burst a channel.
66	Passes hook_data_channel:
67	hdata->client = server we are bursting to
68	hdata->chptr = channel we have just burst
69
70	"burst_finished" - Sent after we have just finished bursting users/chans
71	Passes hook_data_client:
72	hdata->client = server we are bursting to
73
74
75	Server Hooks
76	------------
77	The following hooks are called during server connects/exits.
78
79	"server_eob" - Sent after a server finishes bursting to us.
80	Passes struct Client, the server that has
81	finished bursting.
82
83	"server_introduced" - Sent after a server is introduced to the network,
84	local or remote.
85	Passes hook_data_client:
86	hdata->client = uplink server (&me if local)
87	hdata->target = server being introduced
88
89
90	Client Hooks
91	------------
92	The following hooks are called during various events related to clients.
93
94	"introduce_client" - Sent after introducing a client to the (rest of the)
95	network.
96	Passes hook_data_client:
97	hdata->client = server that introduced this client
98	hdata->target = client being introduced
99
100	"new_local_user" - Sent just before introducing a new local user
101	to the network.
102	Passes struct Client, the client being introduced.
103
104	"new_remote_user" - Sent just before introducing a new remote user
105	to the rest of the network.
106	Passes struct Client, the client being introduced.
107
108	"umode_changed" - Sent each time a user's mode or snomask changes.
109	Passes hook_data_umode_changed:
110	client = client whose modes are changing
111	oldumodes = new user mode field
112	oldsnomask = new snomask field
113
114
115	The following are for debugging and take struct hook_io_data for arguments.
116	These can be used for a variety of purposes, but are aimed at the developer
117	community.
118	"iosend"
119	"iorecv"
120	"iorecvctrl"
121
122	$Id: hooks.txt 710 2006-02-06 03:10:01Z gxti $