
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 |