.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "POE::Component::Jabber::Protocol 3pm"
.TH POE::Component::Jabber::Protocol 3pm "2023-08-26" "perl v5.36.0" "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"
POE::Component::Jabber::Protocol \- A base class for implementing protocol
differences
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Inherit from this base class when implementing specifc protocol extentions that
may exist when writing to support various other jabber server implementations.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
PCJ::Protocol is the base class used when differences between authentication
or other connection initialization methods require special processing.
.PP
A prime example is \s-1JABBER\s0(tm) vs. \s-1XMPP.\s0 The Jabber protocol uses a much
different method to authenticate (ie. using the iq:auth namespace) than \s-1XMPP\s0
which uses \s-1SASL.\s0 While the rest of the protocol is substantially unchanged, 
these differences mean they must be accounted. In the 1.x versions of \s-1PCJ,\s0
this was solved by having different duplicate classes in the same domain with
these differences manifest. It led to lots of headaches if there was a problem
because it then needed to be fixed in four places.
.PP
The solution is to keep the core aspect of \s-1PCJ\s0 immutable, while loading
separate individual Protocol classes that then implement the details for each
specific dialect.
.PP
As an end developer, if you wish to add support for another dialect (ie.
support another jabber server implementation that does service management
differently), subclass from this module and then add your entry into the 
ProtocolFactory.
.PP
Also be aware that \s-1PCJ\s0 uses object_states to construct its own session. 
Protocol subclassees are expected to fit smoothly into that. See the \s-1METHOD\s0
\&\fBget_states()\fR for more information.
.PP
And remember when you are finished handling the protocol specifics and the 
connection is finished, fire off the \s-1PCJ_INIT_FINISHED\s0 status, and call 
\&\fBrelinquish_states()\fR from the \f(CW$_\fR[\s-1HEAP\s0] object to return control back to the \s-1PCJ\s0
Core. (Yes, you read that correctly, \f(CW$_\fR[\s-1HEAP\s0] is actually the \s-1PCJ\s0 object).
.PP
If in doubt, please see the source code for the other Protocol subclasses (ie. 
\&\s-1XMPP\s0.pm, J14.pm, etc).
.SH "METHODS"
.IX Header "METHODS"
At a bare minimum, some methods must be implemented by the end developer. These
will be indicated with a \s-1MANDATORY\s0 flag.
.IP "\fBnew()\fR [\s-1OPTIONAL\s0]" 4
.IX Item "new() [OPTIONAL]"
\&\fBnew()\fR provides a default constructor. It returns a hash reference blessed into
the provided class
.IP "\fBget_version()\fR [\s-1MANDATORY\s0]" 4
.IX Item "get_version() [MANDATORY]"
\&\fBget_version()\fR is used by \s-1PCJ\s0 to populate the 'version' attribute in the opening
<stream:stream/>. For \s-1XMPP\s0 enabled clients, this must return '1.0'. For legacy
Jabber connections, it should return '0.9' but it isn't required. For all other
applications, see the appropriate \s-1RFC\s0 for details on what version it expects.
.IP "\fBget_xmlns()\fR [\s-1MANDATORY\s0]" 4
.IX Item "get_xmlns() [MANDATORY]"
\&\fBget_xmlns()\fR is used by \s-1PCJ\s0 to populate the default \s-1XML\s0 namespace attribute in 
the opening <stream:stream/>. Please feel free to use the constants in
POE::Filter::XML::NS to provide this.
.IP "\fBget_states()\fR [\s-1MANDATORY\s0]" 4
.IX Item "get_states() [MANDATORY]"
get_states is used by \s-1PCJ\s0 to fill its object_states with the Protocol states.
An array reference containing event names should be returned that corespond
one-to-one with the methods you implement in your subclass. Or if a mapping is
required, a hash reference should be returned that includes the mapping. See
POE::Session for more detail on object_states.
.IP "\fBget_input_event()\fR [\s-1MANDATORY\s0]" 4
.IX Item "get_input_event() [MANDATORY]"
\&\fBget_input_event()\fR returns the main entry point event into the Protocol 
subclass. This is then used by \s-1PCJ\s0 to assign the event to the Wheel, so that
the Protocol's events get fired from Wheel events.
.IP "\fBget_error_event()\fR [\s-1OPTIONAL\s0]" 4
.IX Item "get_error_event() [OPTIONAL]"
\&\fBget_error_event()\fR returns the event to be called when an error occurs in the 
Wheel. Typically, this isn't required for Protocol subclasses, but is available
if needed.
.IP "\fBget_flushed_event()\fR [\s-1OPTIONAL\s0]" 4
.IX Item "get_flushed_event() [OPTIONAL]"
\&\fBget_flushed_event()\fR returns the event to be called when the flushed event 
occurs in the Wheel. Typically, this isn't required for Protocol subclasses,
but is available if needed.
.SH "NOTES"
.IX Header "NOTES"
Here are some quick tips to keep in mind when subclassing:
.PP
Protocol subclassees execute within the same Session space as \s-1PCJ\s0
\&\f(CW$_\fR[\s-1HEAP\s0] contains the \s-1PCJ\s0 object.
If you need storage space, use \f(CW$_\fR[\s-1OBJECT\s0] (ie. yourself).
Send status events. See PCJ::Status
Don't forget to send \s-1PCJ_READY.\s0
And don't forget to call \f(CW$_\fR[\s-1HEAP\s0]\->\fBrelinquish_states()\fR when finished.
When in doubt, use the source!
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2007\-2009 Nicholas Perez. Distributed under the \s-1GPL.\s0