NAME

Net::Async::IRC::Protocol - send and receive IRC messages

DESCRIPTION

This subclass of IO::Async::Protocol::LineStream implements an established IRC connection that has already completed its inital login sequence and is ready to send and receive IRC messages. It handles base message sending and receiving, and implements ping timers.

Objects of this type would not normally be constructed directly. For IRC clients, see Net::Async::IRC which is a subclass of it. All the events, parameters, and methods documented below are relevant there.

CONSTRUCTOR

$irc = Net::Async::IRC::Protocol->new( %args )

Returns a new instance of a Net::Async::IRC::Protocol object. This object represents a IRC connection to a peer. As it is a subclass of IO::Async::Protocol::LineStream its constructor takes any arguments for that class, in addition to the parameters named below.

PARAMETERS

The following named parameters may be passed to new or configure:

on_message => CODE

A CODE reference to the generic message handler; see MESSAGE HANDLING below.

on_message_* => CODE

Any parameter whose name starts with on_message_ can be installed as a handler for a specific message, in preference to the generic handler. See MESSAGE HANDLING.

pingtime => NUM

Amount of quiet time, in seconds, after a message is received from the peer, until a PING will be sent to check it is still alive.

pongtime => NUM

Timeout, in seconds, after sending a PING message, to wait for a PONG response.

on_ping_timeout => CODE

A CODE reference to invoke if the peer fails to respond to a PING message within the given timeout.

$on_ping_timeout->( $irc )

on_pong_reply => CODE

A CODE reference to invoke when the peer successfully sends a PONG in response of a PING message.

$on_pong_reply->( $irc, $lag )

Where $lag is the response time in (fractional) seconds.

encoding => STRING

If supplied, sets an encoding to use to encode outgoing messages and decode incoming messages.

METHODS

$connect = $irc->is_connected

Returns true if a connection to the peer is established. Note that even after a successful connection, the connection may not yet logged in to. See also the is_loggedin method.

$loggedin = $irc->is_loggedin

Returns true if the full login sequence has been performed on the connection and it is ready to use.

$nick = $irc->nick

Returns the current nick in use by the connection.

$nick_folded = $irc->nick_folded

Returns the current nick in use by the connection, folded by casefold_name for convenience.

MESSAGE HANDLING

A message with a command of COMMAND will try handlers in following places:

1. A CODE ref in a parameter called on_message_COMMAND

   $on_message_COMMAND->( $irc, $message, \%hints )

2. A method called on_message_COMMAND

   $irc->on_message_COMMAND( $message, \%hints )

3. A CODE ref in a parameter called on_message

   $on_message->( $irc, 'COMMAND', $message, \%hints )

4. A method called on_message

   $irc->on_message( 'COMMAND', $message, \%hints )

Certain commands are handled internally by methods on the base Net::Async::IRC::Protocol class itself. These may cause other hints hash keys to be created, or to invoke other handler methods. These are documented below.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>