/ 
Net-IRC3-0.5
River stage zero No dependents
/ Net::IRC3::Client::Connection

NAME

Net::IRC3::Client::Connection - A highlevel IRC connection

SYNOPSIS

use AnyEvent;
use Net::IRC3::Client::Connection;

my $c = AnyEvent->condvar;

my $timer;
my $con = new Net::IRC3::Client::Connection;

$con->reg_cb (registered => sub { print "I'm in!\n"; 0 });
$con->reg_cb (disconnect => sub { print "I'm out!\n"; 0 });
$con->reg_cb (
   sent => sub {
      if ($_[2] eq 'PRIVMSG') {
         print "Sent message!\n";
         $timer = AnyEvent->timer (after => 1, cb => sub { $c->broadcast });
      }
      1
   }
);

$con->send_srv (PRIVMSG => "Hello there i'm the cool Net::IRC3 test script!", 'elmex');

$con->connect ("localhost", 6667);
$con->register (qw/testbot testbot testbot/);

$c->wait;
undef $timer;

$con->disconnect;

DESCRIPTION

Net::IRC3::Client::Connection is a highlevel client connection, that manages all the stuff that noone 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.

A NOTE TO CASE MANAGEMENT

The case insensitivity of channelnames 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 Net::IRC3::Client::Connection 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.

EVENTS

The following events are emitted by Net::IRC3::Client::Connection. Use reg_cb as described in Net::IRC3::Connection to register to such an event.

registered

Emitted when the connection got successfully registered.

channel_add $channel @nicks

Emitted when @nicks are added to the channel $channel, this happens for example when someone JOINs a channel or when you get a RPL_NAMREPLY (see RFC2812).

channel_remove $channel @nicks

Emitted when @nicks are removed from the channel $channel, happens for example when they PART, QUIT or get KICKed.

channel_change $channel $old_nick $new_nick $is_myself

Emitted when a nickname on a channel changes. This is emitted when a NICK change occurs from $old_nick to $new_nick give the application a chance to quickly analyze what channels were affected. $is_myself is true when youself was the one who changed the nick.

channel_topic $channel $topic $who

This is emitted when the topic for a channel is discovered. $channel is the channel for which $topic is the current topic now. Which is set by $who. $who might be undefined when it's not known who set the channel topic.

join $nick $channel $is_myself

Emitted when $nick enters the channel $channel by JOINing. $is_myself is true if youself are the one who JOINs.

part $nick $channel $is_myself $msg

Emitted when $nick PARTs the channel $channel. $is_myself is true if youself are the one who PARTs. $msg is the PART message.

nick_change $old_nick $new_nick $is_myself

Emitted when $old_nick is renamed to $new_nick. $is_myself is true when youself was the one who changed the nick.

quit $nick $msg

Emitted when the nickname $nick QUITs with the message $msg.

publicmsg $channel $ircmsg

Emitted for NOTICE and PRIVMSG where the target $channel is a channel. $ircmsg is the original IRC message hash like it is returned by parse_irc_msg.

privatemsg $nick $ircmsg

Emitted for NOTICE and PRIVMSG where the target $nick (most of the time you) is a nick. $ircmsg is the original IRC message hash like it is returned by parse_irc_msg.

error $code $message $ircmsg

Emitted when any error occurs. $code is the 3 digit error id string from RFC 2812 and $message is a description of the error. $ircmsg is the complete error irc message.

You may use Net::IRC3::Util::rfc_code_to_name to convert $code to the error name from the RFC 2812. eg.:

rfc_code_to_name ('471') => 'ERR_CHANNELISFULL'

METHODS

new

This constructor takes no arguments.

register ($nick, $user, $real, $server_pass)

Sends the IRC registration commands NICK and USER. If $server_pass is passed also a PASS command is generated.

set_nick_change_cb $callback

This method lets you modify the nickname renaming mechanism when registering the connection. $callback is called with the current nickname as first argument when a ERR_NICKNAMEINUSE or ERR_UNAVAILRESOURCE error occurs on login. The returnvalue of $callback will then be used to change the nickname.

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.

nick ()

Returns the current nickname, under which this connection is registered at the IRC server. It might be different from the one that was passed to register as a nick-collision might happened on login.

registered ()

Returns a true value when the connection has been registered successfull and you can send commands.

channel_list ()

This returns a hash reference. The keys are the currently joined channels in lower case. The values are hash references which contain the joined nicks as key.

NOTE: Future versions might preserve the case from the JOIN command to the channels.

send_srv ($command, $trailing, @params)

This function sends an IRC message that is constructed by mk_msg (undef, $command, $trailing, @params) (see Net::IRC3::Util). If the connection isn't yet registered (for example if the connection is slow) and hasn't got a welcome (IRC command 001) from the server yet, the IRC message is queued until it gets a welcome.

clear_srv_queue

Clears the server send queue.

send_chan ($channel, $command, $trailing, @params))

This function sends a message (constructed by mk_msg (undef, $command, $trailing, @params) to the server, like send_srv only that it will queue the messages if it hasn't joined the channel $channel yet. The queued messages will be send once the connection successfully JOINed the $channel.

$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.

clear_chan_queue ($channel)

Clears the channel queue of the channel $channel.

EXAMPLES

See samples/netirc3cl and other samples in samples/ for some examples on how to use Net::IRC3::Client::Connection.

AUTHOR

Robin Redeker, <elmex@ta-sa.org>

SEE ALSO

Net::IRC3::Connection

RFC 2812 - Internet Relay Chat: Client Protocol

COPYRIGHT & LICENSE

Copyright 2006 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.