# 5.2. Hooks

From `/load'ed` scripts, as well as from `.sircrc.pl`, you have the possibility to define subs to be called when specified events occur. This is the equivalent of ircII's `/on's`.

To declare a hook, you must define a subroutine called `"hook_somename"` which does whatever you want done when a hook of type `"hook_type"` is triggered, and then call `&addhook("hook_type", "somename");`

To remove a hook, you call `&remhook("hook_type", "somename");`

Numeric hooks are also available, for every 3-digit number; to declare one of those, define a soubroutine called `"hook_somename"` which does what you want, and call `&addhook("xxx", "somename")`, where xxx is the number of the numeric reply. To remove one of these, you call `&remhook("xxx", "somename");`

Subs called from hooks have access to the same functions and variables listed above for functions, plus a few specific ones (wherever applicable):

     $who		is the nick that triggered the hook
     $user           is the corresponding username
     $host		is the corresponding hostname

Hooks can also set the variable `$silent` if they want to provide the display for the event (via `&print`) and inhibit the default. This is the direct equivalent of the `"ˆ"` switch on ircII `/on's`, except for `"raw_irc"`.

Hooks marked with a `*` can also set the special variable `$skip` and cause the line to be ignored by the client. This is in general a bad idea, use `$silent` whenever possible. Only the hooks where this provides some actual additional functionality have this possibility. For `"raw_irc"` this is the equivalent of the `"ˆ"` switch on ircII's `/on raw_irc`.

The following hooks are available, and get called with the following arguments:

     action		activated by a ctcp action;
     		1st arg is the nick or channel it was sent to
     		2nd arg is the message

     command      *	activated by the user typing a command (regardless of
     		whether it is a /command or just a line of text)
     		1st arg is the user's line
     		this hook is special in that (like "print" and
     		"status"), it is explicitly allowed to modify its
     		argument ($_[0]) to change what command should be
     		interpreted.
     		setting $skip=1 in the hook will make sirc ignore the
     		command

     chat_disconnect activated when a dcc chat is lost (but not when the
     		user closes one with DCC CLOSE CHAT)
     		1st arg is the nick associated with the chat

     ctcp	     *	activated by any ctcp, BEFORE the client parses
     		and eventually answers the ctcp.
     		1st arg is the nick or channel it was sent to
     		2nd arg is the ctcp command
     		3rd arg are the arguments

     ctcp_reply	activated by ctcp replies;
     		1st arg is the nick or channel it was sent to
     		2nd arg is the ctcp command
     		3rd arg are the arguments

     dcc_chat	activated by received text over a dcc chat
     		1st arg is the nick
     		2nd arg is the text

     dcc_disconnect  activated when a dcc get or send is finished or closed
     		(even when the user closes one with DCC CLOSE GET/SEND)
     		1st arg is the nick associated with the chat
     		2nd arg is the filename
     		3rd arg is the number of bytes transferred
     		4th arg is the number of seconds the transfer took

     dcc_request	activated by a received dcc chat or send request, and
     		after the client has processed the request.  this is
     		the hook to use if you want to implement any kind of
     		auto-dcc.
     		1st arg is the type ("CHAT" or "SEND")
     		2nd arg is the machine address (a 32-bit integer)
     		3rd arg is the port
     		for a DCC SEND offer:
     		  4th arg is the file name
     		  5th arg is the file lenght

     disconnect	activated by losing the connection to the server, or
     		breaking it with /disconnect (but not with /server).
     		no arguments are passed

     input	     *	activated whenever the client wants to ask the user
     		for a line through &getuserline (i.e. when you got
     		disconnected, or need a new nick, or some script called
     		&getuserline).
     		1st arg is the "long" prompt
     		2nd arg is the "short" one
     		if the hook sets $skip, then &getuserline won't ask
     		the user for anything, and the contents of $_ will
     		be returned

     invite		activated by invites;
     		1st arg is the channel you're invited to

     join		activated by joins;
     		1st arg is the channel that $who is joining

     kick		activated by kicks;
     		1st arg is the nick of the person who got kicked
     		2nd arg is the channel that they got kicked from
     		3rd arg is the reason

     leave		activated by parts;
     		1st arg is the channel that $who is leaving

     mode		activated by mode changes;
     		1st arg is the channel or user the change applies to
     		2nd arg is the mode change itself

     msg		activated by msgs;
     		1st arg is the message

     nick		activated by nick changes
     		1st arg is $who's new nick

     notice		activated by notices
     		1st arg is the nick or channel it was sent to
     		2nd arg is the message

     server_notice	activated by notices from servers
     		1st arg is the nick or channel it was sent to
     		2nd arg is the message

     notify_signon	activated by a notify signon
     		1st arg is the nick
     		$user and $host are *not* set to anything meaningful

     notify_signoff	activated by a notify signoff
     		1st arg is the nick
     		$user and $host are *not* set to anything meaningful

     print	     *	activated by the printing of any line to the screen
     		1st arg is the line to print
     		this hook is special in that (like "status" and
     		"command") it is explicitly allowed to modify its
     		argument ($_[0]) to change what line should be
     		printed.
     		setting $skip=1 in the hook will prevent the line from
     		being actually printed

     public		activated by non-ctcp messages to a channel;
     		1st arg is the channel
     		2nd arg is the message

     raw_irc	     *	activated by any server line
     		$who    is the originator (user or server)
     		$user   is his username ('' if it comes from a server)
     		$host   is his hostname (same comment)
     		1st arg is the command
     		2nd arg are the arguments

     send_action	activated when we send a /me or a /de
     		($who, $user and $host do not apply here)
     		1st arg is the nick/channel
     		2nd arg	is the action

     send_ctcp	activated when we send a ctcp
     		1st arg is the nick or channel the ctcp is being sent to
     		2nd arg is the complete ctcp text (type and arguments)

     send_dcc_chat	activated when we send text over a dcc chat
     		($who, $user and $host do not apply here)
     		1st arg is the nick we're sending to
     		2nd arg is the text

     send_text	activated when we send a /msg or speak on a channel
     		($who, $user and $host do not apply here)
     		1st arg is the nick/channel
     		2nd arg is the msg

     send_notice	activated when we send a notice
     		($who, $user and $host do not apply here)
     		1st arg is the nick/channel
     		2nd arg is the notice

     signoff		activated when someone signs off
     		1st arg	is the quitting comment

     status		activated when sirc redraws the status line (as a
     		result of &dostatus being called, either internally
     		or by a script).
     		1st arg is the proposed status line
     		this hook is special in that (like "print" and
     		"command") it is explicitly allowed to modify its
     		argument ($_[0]) to change what should go to the status
     		line

     topic		activated when someone changes the topic
     		1st arg is the channel
     		2nd arg is the new topic

     <3-digit nb>  * activated by that particular server numeric reply
     		1st arg is whatever the server sent after the number,
     	 	unparsed (which means there's still a : in front of the
     	 	last argument)

Example, which could be put into a file and /load'ed directly, of a hook that will rejoin a channel whenever you are kicked:

     # auto-rejoin hook

     sub hook_kicked {
       local($kicked, $where_from, $reason)=@_;
       					# local vars with the args
       if (&eq($kicked, $nick)) {		# if *we* got kicked
         &sl("JOIN $where_from");		# send a JOIN to the server
       }
     }
     &addhook("kick", "kicked");	  	# activate the hook

Another example, to display the username and hostname with each message (which is better done with /set printuh anyway):

     # userhost-on message hook

     sub hook_uhmsg {
       &tell("[\cb${who}!${user}\@${host}\cb] $_[0]");  # print everything
       $silent=1;			# disable the default display
     }
     &addhook("msg", "uhmsg");	  	# activate the hook