PCJ::Protocol is the base class used when differences between authentication
or other connection initialization methods require special processing.
A prime example is JABBER(tm) vs. XMPP. The Jabber protocol uses a much
different method to authenticate (ie. using the iq:auth namespace) than XMPP
which uses SASL. While the rest of the protocol is substantially unchanged,
these differences mean they must be accounted. In the 1.x versions of PCJ,
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.
The solution is to keep the core aspect of PCJ immutable, while loading
separate individual Protocol classes that then implement the details for each
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
Also be aware that PCJ uses object_states to construct its own session.
Protocol subclassees are expected to fit smoothly into that. See the METHOD
get_states() for more information.
And remember when you are finished handling the protocol specifics and the
connection is finished, fire off the PCJ_INIT_FINISHED status, and call
relinquish_states() from the $_[HEAP] object to return control back to the PCJ
Core. (Yes, you read that correctly, $_[HEAP] is actually the PCJ object).
If in doubt, please see the source code for the other Protocol subclasses (ie.
XMPP.pm, J14.pm, etc).
Here are some quick tips to keep in mind when subclassing:
Protocol subclassees execute within the same Session space as PCJ
$_[HEAP] contains the PCJ object.
If you need storage space, use $_[OBJECT] (ie. yourself).
Send status events. See PCJ::Status
Dont forget to send PCJ_READY.
And dont forget to call $_[HEAP]->relinquish_states() when finished.
When in doubt, use the source!