NAME

Net::IRC3::Connection - An IRC connection abstraction

SYNOPSIS

   #...
   $con->send_msg (undef, "PRIVMSG", "Hello there!", "yournick");
   #...

DESCRIPTION

NOTE: This module is DEPRECATED, please use AnyEvent::IRC for new programs, and possibly port existing Net::IRC3 applications to AnyEvent::IRC. Though the API of AnyEvent::IRC has incompatible changes, it's still fairly similar.

The connection class. Here the actual interesting stuff can be done, such as sending and receiving IRC messages.

Please note that CTCP support is available through the functions encode_ctcp and decode_ctcp provided by Net::IRC3::Util.

METHODS

new

This constructor does take no arguments.

connect ($host, $port)

Tries to open a socket to the host $host and the port $port. If an error occured it will die (use eval to catch the exception).

use_socket ($host, $port, $socket)

This method can be used instead of connect to handle IRC messages that are received and sent over the $socket.

In this case $host and $port are just documentation for the error messages.

disconnect ($reason)

Unregisters the connection in the main Net::IRC3 object, closes the sockets and send a 'disconnect' event with $reason as argument.

is_connected

Returns true when this connection is connected. Otherwise false.

heap ()

Returns a hash reference that is local to this connection object that lets you store any information you want.

send_raw ($ircline)

This method sends $ircline straight to the server without any further processing done.

send_msg (@ircmsg)

This function sends a message to the server. @ircmsg is the argumentlist for Net::IRC3::Util::mk_msg.

reg_cb ($cmd, $cb) or reg_cb ($cmd1, $cb1, $cmd2, $cb2, ..., $cmdN, $cbN)

This registers a callback in the connection class. These callbacks will be called by internal events and by IRC protocol commands. You can also specify multiple callback registrations.

The first argument to the callbacks is always the connection object itself.

If a callback returns a false value, it will be unregistered.

NOTE: A callback has to return true to stay alive

If $cmd starts with 'irc_' the callback $cb will be registered for a IRC protocol command. The command is the suffix of $cmd then. The second argument to the callback is the message hash reference that has the layout that is returned by Net::IRC3::Util::parse_irc_msg.

With the special $cmd 'irc_*' the callback will be called on any IRC command that is received.

EXAMPLE:

   $con->reg_cb (irc_privmsg => \&privmsg_handler);
   # privmsg_handler will be called if an IRC message
   # with the command 'PRIVMSG' arrives.

If $cmd is not prefixed with a 'irc_' it will be called when an event with the name $cmd is emitted. The arguments to the callback depend on the event that is emitted (but remember: the first argument will always be the connection object)

Following events are emitted by this module and shouldn't be emitted from a module user call to event.

connect

This event is generated when the socket was successfully connected.

connect_error $error

This event is generated when the socket couldn't be connected successfully.

disconnect $reason

This event will be generated if the connection is somehow terminated. It will also be emitted when disconnect is called. The second argument to the callback is $reason, a string that contains a clue about why the connection terminated.

If you want to reestablish a connection, call connect again.

sent @ircmsg

Emitted when a message (@ircmsg) was sent to the server. @ircmsg are the arguments to Net::IRC3::Util::mk_msg.

'*' $msg

read $msg

Emitted when a message ($msg) was read from the server. $msg is the hash reference returned by Net::IRC3::Util::parse_irc_msg;

event ($event, @args)

This function emits an event with the name $event and the arguments @args. The registerd callback that has been registered with reg_cb will be called with the first argument being the connection object and the rest of the arguments being @args.

EXAMPLE

   $con->reg_cb (test_event => sub { print "Yay, i love $_[1]!!\n");
   $con->event (test_event => "IRC");

   # will print "Yay, i love IRC!!\n"

AUTHOR

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

SEE ALSO

Net::IRC3

Net::IRC3::Client::Connection

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.