.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Async::IRC::Protocol 3pm" .TH Net::Async::IRC::Protocol 3pm "2018-07-02" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Net::Async::IRC::Protocol" \- send and receive IRC messages .SH "DESCRIPTION" .IX Header "DESCRIPTION" This subclass of IO::Async::Stream implements an established \s-1IRC\s0 connection that has already completed its inital login sequence and is ready to send and receive \s-1IRC\s0 messages. It handles base message sending and receiving, and implements ping timers. This class provides most of the functionality required for sending and receiving \s-1IRC\s0 commands and responses by mixing in from Protocol::IRC. .PP Objects of this type would not normally be constructed directly. For \s-1IRC\s0 clients, see Net::Async::IRC which is a subclass of it. All the events, parameters, and methods documented below are relevant there. .SH "EVENTS" .IX Header "EVENTS" The following events are invoked, either using subclass methods or \f(CW\*(C`CODE\*(C'\fR references in parameters: .ie n .SS "$handled = on_message" .el .SS "\f(CW$handled\fP = on_message" .IX Subsection "$handled = on_message" .ie n .SS "$handled = on_message_MESSAGE" .el .SS "\f(CW$handled\fP = on_message_MESSAGE" .IX Subsection "$handled = on_message_MESSAGE" Invoked on receipt of a valid \s-1IRC\s0 message. See \f(CW\*(C`MESSAGE HANDLING\*(C'\fR below. .ie n .SS "on_irc_error $err" .el .SS "on_irc_error \f(CW$err\fP" .IX Subsection "on_irc_error $err" Invoked on receipt of an invalid \s-1IRC\s0 message if parsing fails. \f(CW$err\fR 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. .SS "on_ping_timeout" .IX Subsection "on_ping_timeout" Invoked if the peer fails to respond to a \f(CW\*(C`PING\*(C'\fR message within the given timeout. .ie n .SS "on_pong_reply $lag" .el .SS "on_pong_reply \f(CW$lag\fP" .IX Subsection "on_pong_reply $lag" Invoked when the peer successfully sends a \f(CW\*(C`PONG\*(C'\fR reply response to a \f(CW\*(C`PING\*(C'\fR message. \f(CW$lag\fR is the response time in (fractional) seconds. .SH "PARAMETERS" .IX Header "PARAMETERS" The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR: .IP "on_message => \s-1CODE\s0" 8 .IX Item "on_message => CODE" .PD 0 .IP "on_message_MESSAGE => \s-1CODE\s0" 8 .IX Item "on_message_MESSAGE => CODE" .IP "on_irc_error => \s-1CODE\s0" 8 .IX Item "on_irc_error => CODE" .IP "on_ping_timeout => \s-1CODE\s0" 8 .IX Item "on_ping_timeout => CODE" .IP "on_pong_reply => \s-1CODE\s0" 8 .IX Item "on_pong_reply => CODE" .PD \&\f(CW\*(C`CODE\*(C'\fR references for event handlers. .IP "pingtime => \s-1NUM\s0" 8 .IX Item "pingtime => NUM" Amount of quiet time, in seconds, after a message is received from the peer, until a \f(CW\*(C`PING\*(C'\fR will be sent to check it is still alive. .IP "pongtime => \s-1NUM\s0" 8 .IX Item "pongtime => NUM" Timeout, in seconds, after sending a \f(CW\*(C`PING\*(C'\fR message, to wait for a \f(CW\*(C`PONG\*(C'\fR response. .IP "encoding => \s-1STRING\s0" 8 .IX Item "encoding => STRING" If supplied, sets an encoding to use to encode outgoing messages and decode incoming messages. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 1 \& $irc = Net::Async::IRC::Protocol\->new( %args ) .Ve .PP Returns a new instance of a \f(CW\*(C`Net::Async::IRC::Protocol\*(C'\fR object. This object represents a \s-1IRC\s0 connection to a peer. .SH "METHODS" .IX Header "METHODS" .SS "is_connected" .IX Subsection "is_connected" .Vb 1 \& $connect = $irc\->is_connected .Ve .PP 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 \f(CW\*(C`is_loggedin\*(C'\fR method. .SS "is_loggedin" .IX Subsection "is_loggedin" .Vb 1 \& $loggedin = $irc\->is_loggedin .Ve .PP Returns true if the full login sequence has been performed on the connection and it is ready to use. .SS "nick" .IX Subsection "nick" .Vb 1 \& $nick = $irc\->nick .Ve .PP Returns the current nick in use by the connection. .SS "nick_folded" .IX Subsection "nick_folded" .Vb 1 \& $nick_folded = $irc\->nick_folded .Ve .PP Returns the current nick in use by the connection, folded by \f(CW\*(C`casefold_name\*(C'\fR for convenience. .SH "MESSAGE HANDLING" .IX Header "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. .PP 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. .PP A message with a command of \f(CW\*(C`COMMAND\*(C'\fR will try handlers in following places: .IP "1." 4 A \s-1CODE\s0 ref in a parameter called \f(CW\*(C`on_message_COMMAND\*(C'\fR .Sp .Vb 1 \& $on_message_COMMAND\->( $irc, $message, \e%hints ) .Ve .IP "2." 4 A method called \f(CW\*(C`on_message_COMMAND\*(C'\fR .Sp .Vb 1 \& $irc\->on_message_COMMAND( $message, \e%hints ) .Ve .IP "3." 4 A \s-1CODE\s0 ref in a parameter called \f(CW\*(C`on_message\*(C'\fR .Sp .Vb 1 \& $on_message\->( $irc, \*(AqCOMMAND\*(Aq, $message, \e%hints ) .Ve .IP "4." 4 A method called \f(CW\*(C`on_message\*(C'\fR .Sp .Vb 1 \& $irc\->on_message( \*(AqCOMMAND\*(Aq, $message, \e%hints ) .Ve .PP As this message handling ability is provided by \f(CW\*(C`Protocol::IRC\*(C'\fR, more details about how it works and how to use it can be found at \&\*(L"\s-1MESSAGE HANDLING\*(R"\s0 in Protocol::IRC. .PP Additionally, some types of messages receive further processing by \&\f(CW\*(C`Protocol::IRC\*(C'\fR and in turn cause new types of events to be invoked. These are further documented by \*(L"\s-1INTERNAL MESSAGE HANDLING\*(R"\s0 in Protocol::IRC. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans