| AnyEvent::IRC::Client(3pm) | User Contributed Perl Documentation | AnyEvent::IRC::Client(3pm) |
AnyEvent::IRC::Client - A highlevel IRC connection
use AnyEvent;
use AnyEvent::IRC::Client;
my $c = AnyEvent->condvar;
my $timer;
my $con = new AnyEvent::IRC::Client;
$con->reg_cb (connect => sub {
my ($con, $err) = @_;
if (defined $err) {
warn "connect error: $err\n";
return;
}
});
$con->reg_cb (registered => sub { print "I'm in!\n"; });
$con->reg_cb (disconnect => sub { print "I'm out!\n"; $c->broadcast });
$con->reg_cb (
sent => sub {
my ($con) = @_;
if ($_[2] eq 'PRIVMSG') {
print "Sent message!\n";
$timer = AnyEvent->timer (
after => 1,
cb => sub {
undef $timer;
$con->disconnect ('done')
}
);
}
}
);
$con->send_srv (
PRIVMSG => 'elmex',
"Hello there I'm the cool AnyEvent::IRC test script!"
);
$con->connect ("localhost", 6667, { nick => 'testbot' });
$c->wait;
$con->disconnect;
AnyEvent::IRC::Client is a (nearly) highlevel client connection, that manages all the stuff that no one wants to implement again and again when handling with IRC. For example it PONGs the server or keeps track of the users on a channel.
This module also implements the ISUPPORT (command 005) extension of the IRC protocol (see http://www.irc.org/tech_docs/005.html) and will enable the NAMESX and UHNAMES extensions when supported by the server.
Also CTCP support is implemented, all CTCP messages will be decoded and events for them will be generated. You can configure auto-replies to certain CTCP commands with the "ctcp_auto_reply" method, or you can generate the replies yourself.
The case insensitivity of channel names and nicknames can lead to headaches when dealing with IRC in an automated client which tracks channels and nicknames.
I tried to preserve the case in all channel and nicknames AnyEvent::IRC::Client passes to his user. But in the internal structures I'm using lower case for the channel names.
The returned hash from "channel_list" for example has the lower case of the joined channels as keys.
But I tried to preserve the case in all events that are emitted. Please keep this in mind when handling the events.
For example a user might joins #TeSt and parts #test later.
The following events are emitted by AnyEvent::IRC::Client. Use "reg_cb" as described in Object::Event to register to such an event.
$msg is the IRC message hash that as returned by "parse_irc_msg".
$msg is the IRC message hash that as returned by "parse_irc_msg" or undef if the reason for the removal was a disconnect on our end.
You can change your away status by emitting the "AWAY" IRC command:
$cl->send_srv (AWAY => "I'm not here right now");
Or reset it:
$cl->send_srv ('AWAY');
$src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on.
$src is the source nick the message came from. $target is the target nickname (yours) or the channel the ctcp was sent on.
$id is the DCC connection ID.
$dest and $type are the destination and type of the DCC request.
$local_ip is the $local_ip argument passed to "start_dcc" or the IP the socket is bound to.
$local_port is the TCP port is the socket is listening on.
To answer to his request you can just call "dcc_accept" with the $id.
$id and $type are the DCC connection ID and type of the DCC request.
$hdl is a pre-configured AnyEvent::Handle object, which you only need to care about in case you want to implement your own DCC protocol. (This event has the on_error and on_eof events pre-configured to cleanup the data structures in this connection).
$id and $type are the DCC connection ID and type of the DCC request.
$reason is a human readable string indicating the reason for the end of the DCC request.
The last parameter of the $ircmsg will have all CTCP messages stripped off.
The last parameter of the $ircmsg will have all CTCP messages stripped off.
You may use AnyEvent::IRC::Util::rfc_code_to_name to convert $code to the error name from the RFC 2812. eg.:
rfc_code_to_name ('471') => 'ERR_CHANNELISFULL'
NOTE: This event is also emitted when a 'ERROR' message is received.
NOTE: You are free to use the hash member "heap" to store any associated data with this object. For example retry timers or anything else.
%args may contain these options:
$bool is "false" by default.
The keys of the hash reference you can pass in $info are:
nick - the nickname you want to register as
user - your username
real - your realname
password - the server password
timeout - the TCP connect timeout
All keys, except "nick" are optional.
NOTE: If you passed the nick, user, etc. already to the "connect" method you won't need to call this method, as AnyEvent::IRC::Client will do that for you.
If $callback is not defined the default nick change callback will be used again.
The default callback appends '_' to the end of the nickname supplied in the "register" routine.
If the callback returns the same nickname that was given it the connection will be terminated.
If the $channel parameter is given it returns the hash reference of the channel occupants or undef if the channel does not exist.
NOTE: If you stop the registered event (with "stop_event", see Object::Event) in a callback registered to the "before_registered" event, the "send_srv" queue will NOT be flushed and NOT sent to the server!
This allows you to simply write this:
my $cl = AnyEvent::IRC::Client->new;
$cl->connect ('irc.freenode.net', 6667, { nick => 'testbot' });
$cl->send_srv (PRIVMSG => 'elmex', 'Hi there!');
Instead of:
my $cl = AnyEvent::IRC::Client->new;
$cl->reg_cb (
registered => sub {
$cl->send_msg (PRIVMSG => 'elmex', 'Hi there!');
}
);
$cl->connect ('irc.freenode.net', 6667, { nick => 'testbot' });
$channel will be lowercased so that any case that comes from the server matches. (Yes, IRC handles upper and lower case as equal :-(
Be careful with this, there are chances you might not join the channel you wanted to join. You may wanted to join #bla and the server redirects that and sends you that you joined #blubb. You may use "clear_chan_queue" to remove the queue after some timeout after joining, so that you don't end up with a memory leak.
This method can be used to split up long messages into multiple commands.
$cmd and @params are the IRC command and it's first parameters, except the last one: the $msg. $msg can be a Unicode string, which will be encoded in $encoding before sending.
If you want to send a CTCP message you can encode it in the $cmd by appending the CTCP command with a "\001". For example if you want to send a CTCP ACTION you have to give this $cmd:
$cl->send_long_message (undef, 0, "PRIVMSG\001ACTION", "#test", "rofls");
$encoding can be undef if you don't need any recoding of $msg. But in case you want to send Unicode it is necessary to determine where to split a message exactly, to not break the encoding.
Please also note that the "nick_ident" for your own nick is necessary to compute this. To ensure best performance as possible use the "send_initial_whois" option if you want to use this method.
But note that this method might not work 100% correct and you might still get at least partially chopped off lines if you use "send_long_message" before the "WHOIS" reply to "send_initial_whois" arrived.
To be on the safest side you might want to wait until that initial "WHOIS" reply arrived.
The return value of this method is the list of the actually sent lines (but without encoding applied).
($cb will have the connection object as it's first argument.)
Make sure you call this method after the connection has been established. (eg. in the callback for the "registered" event).
This method returns 2 values: the mode map and the nickname.
The mode map is a hash reference with the keys being the modes the nick has set and the values being 1.
NOTE: If you feed in a prefixed ident ('@elmex!elmex@fofofof.de') you get 3 values out actually: the mode map, the nickname and the ident, otherwise the 3rd value is undef.
NOTE: If you want to rely on the "nick_ident" of your own nick you should make sure to enable the "send_initial_whois" option in the constructor.
If $coderef was given and is a code reference, it will called each time a $ctcp_command is received, this is useful for eg. CTCP PING reply generation. The arguments will be the same arguments that the "ctcp" event callbacks get. (See also "ctcp" event description above). The return value of the called subroutine should be a list of arguments for "encode_ctcp".
Currently you can only configure one auto-reply per $ctcp_command.
Example:
$cl->ctcp_auto_reply ('VERSION', ['VERSION', 'ScriptBla:0.1:Perl']);
$cl->ctcp_auto_reply ('PING', sub {
my ($cl, $src, $target, $tag, $msg, $type) = @_;
['PING', $msg]
});
$timeout is the time in seconds after which the listening socket will be closed if the receiver didn't connect yet. The default is 300 (5 minutes).
When the local listening socket has been setup the "dcc_ready" event is emitted. When the receiver connects to the socket the "dcc_accepted" event is emitted. And whenever a dcc connection is closed the "dcc_close" event is emitted.
For canceling the DCC offer or closing the connection see "dcc_disconnect" below.
The return value of this function will be the ID of the initiated DCC connection, which can be used for functions such as "dcc_disconnect", "send_dcc_chat" or "dcc_handle".
$id is the DCC connection ID. $reason should be a human readable reason why you ended the dcc offer, but it's only used for local logging purposes (see "dcc_close" event).
$timeout is the connection try timeout in seconds. The default is 300 (5 minutes).
See samples/anyeventirccl and other samples in samples/ for some examples on how to use AnyEvent::IRC::Client.
Robin Redeker, "<elmex@ta-sa.org>"
AnyEvent::IRC::Connection
RFC 1459 - Internet Relay Chat: Client Protocol
Copyright 2006-2009 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| 2022-06-06 | perl v5.34.0 |