Kデスクトップ環境

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