POE::C...otocol(3pm)

💖 NAME 💖

ok so this is POE::Component::Jabber::Protocol — it's literally the base class bestie, the blueprint you inherit from when you wanna implement protocol differences. that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

inherit from this base class when you're implementing specific protocol extensions that might exist when you're writing support for all the various other jabber server implementations. yes, "specifc" — we don't fix typos in this house, we preserve them. 💅

---

🌸 DESCRIPTION 🌸

PCJ::Protocol is the base class you reach for when the differences between authentication methods (or any other connection initialization stuff) need special processing. it's giving "template with opinions."

a prime example? 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. the rest of the protocol is substantially unchanged, but those differences still gotta be accounted for. in the 1.x versions of PCJ, this was solved by having different duplicate classes in the same domain with these differences manifest. and bestie, that led to lots of headaches — because if there was a problem, it then needed to be fixed in four places. not the move. 😭

the solution is to keep the core aspect of PCJ immutable, while loading separate individual Protocol classes that then implement the details for each specific dialect. slay. ✨

as an end developer, if you wanna 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. go off. 🎀

also be aware that PCJ uses object_states to construct its own session. Protocol subclasses are expected to fit smoothly into that. see the method get_states() for more info. 👑

and remember — when you're 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. not a typo, not a bit, it's real.) 🙈

if in doubt, please see the source code for the other Protocol subclasses (ie. XMPP.pm, J14.pm, etc).

---

💅 METHODS 💅

at a bare minimum, some methods must be implemented by the end developer. these will be indicated with a MANDATORY flag. no skipping, bestie.

🧚 new() [OPTIONAL]

new() provides a default constructor. it returns a hash reference blessed into the provided class. easy peasy. ⭐

🧚 get_version() [MANDATORY]

get_version() is used by PCJ to populate the 'version' attribute in the opening <stream:stream/>. for XMPP 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 RFC for details on what version it expects. iykyk. 📜

🧚 get_xmlns() [MANDATORY]

get_xmlns() is used by PCJ to populate the default XML namespace attribute in the opening <stream:stream/>. please feel free to use the constants in POE::Filter::XML::NS to provide this. free real estate. 🫶

🧚 get_states() [MANDATORY]

get_states is used by PCJ 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. (yes, "corespond" — preserving the sacred texts.) 🌈

🧚 get_input_event() [MANDATORY]

get_input_event() returns the main entry point event into the Protocol subclass. this is then used by PCJ to assign the event to the Wheel, so that the Protocol's events get fired from Wheel events. main character energy, honestly. 👑

🧚 get_error_event() [OPTIONAL]

get_error_event() 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. no pressure. 💀

🧚 get_flushed_event() [OPTIONAL]

get_flushed_event() 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. same energy as above. 😌

---

🌟 NOTES 🌟

here are some quick tips to keep in mind when subclassing:

• Protocol subclasses 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
• Don't forget to send PCJ_READY. 🚨
• And don't forget to call $_[HEAP]->relinquish_states() when finished.
• When in doubt, use the source! 🫡

fr fr, the source is the answer. every single time.

---

👑 AUTHOR 👑

Copyright (c) 2007-2009 Nicholas Perez. Distributed under the GPL. 💖

---

ok that's the whole page, bestie — and just so you know where this lil doc came from: it's from perl v5.36.0, dated 2023-08-26, filed under POE::C...otocol(3pm) in the User Contributed Perl Documentation. periodt. 💅✨🎀