NAME

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

DESCRIPTION

       This subclass of IO::Async::Stream 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. This class
       provides most of the functionality required for sending and receiving IRC commands and
       responses by mixing in from Protocol::IRC.

       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.

EVENTS

       The following events are invoked, either using subclass methods or "CODE" references in
       parameters:

   $handled = on_message
   $handled = on_message_MESSAGE
       Invoked on receipt of a valid IRC message. See "MESSAGE HANDLING" below.

   on_irc_error $err
       Invoked on receipt of an invalid IRC message if parsing fails. $err is the error message
       text. If left unhandled, any parse error will result in the connection being immediataely
       closed, followed by the exception being re-thrown.

   on_ping_timeout
       Invoked if the peer fails to respond to a "PING" message within the given timeout.

   on_pong_reply $lag
       Invoked when the peer successfully sends a "PONG" reply response to a "PING" message. $lag
       is the response time in (fractional) seconds.

PARAMETERS

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

       on_message => CODE
       on_message_MESSAGE => CODE
       on_irc_error => CODE
       on_ping_timeout => CODE
       on_pong_reply => CODE
               "CODE" references for event handlers.

       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.

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

CONSTRUCTOR

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

METHODS

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

   is_loggedin
          $loggedin = $irc->is_loggedin;

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

   nick
          $nick = $irc->nick;

       Returns the current nick in use by the connection.

   nick_folded
          $nick_folded = $irc->nick_folded;

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

MESSAGE HANDLING

       Every incoming message causes a sequence of message handling to occur. First, the message
       is parsed, and a hash of data about it is created; this is called the hints hash. The
       message and this hash are then passed down a sequence of potential handlers.

       Each handler indicates by return value, whether it considers the message to have been
       handled. Processing of the message is not interrupted the first time a handler declares to
       have handled a message. Instead, the hints hash is marked to say it has been handled.
       Later handlers can still inspect the message or its hints, using this information to
       decide if they wish to take further action.

       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 )

       As this message handling ability is provided by "Protocol::IRC", more details about how it
       works and how to use it can be found at "MESSAGE HANDLING" in Protocol::IRC.

       Additionally, some types of messages receive further processing by "Protocol::IRC" and in
       turn cause new types of events to be invoked. These are further documented by "INTERNAL
       MESSAGE HANDLING" in Protocol::IRC.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>