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

✨ NAME ✨

POE::Component::Jabber — a POE Component for communicating over Jabber, bestie 💖

It's a Perl module, it lives in the User Contributed Perl Documentation manual section (3pm), and it is genuinely iconic.

---

🌸 VERSION 🌸

3.00 — that's the version, no cap ✨

---

🦋 DESCRIPTION 🦋

Okay so, PCJ (that's what we call POE::Component::Jabber when we're being cute, which is always 🎀) is a communications component that fits right inside the POE framework.

What does it actually do? It handles all the raw, low-level, unglamorous footwork for you:

• initiating a connection
• negotiating the various protocol layers
• doing the authentication

…so that you, the end developer, can focus on the business end of implementing a client or a service instead of crying about handshakes. It's giving personal assistant energy, honestly. 💅

---

👑 METHODS 👑

new()

Accepts a whole bunch of named, required arguments, all listed down below 👇. new() returns a reference to the freshly created PCJ object, and you should store it, bestie, don't just let it float away into the void 😭.

There are many useful methods you can call on that object to gather various bits of info — like your negotiated JID, which is lowkey the main character of the whole operation. ⭐

IP

The IP address in dotted quad, or the FQDN for the server. 🌐

PORT

The remote port of the server to connect to.

HOSTNAME

The hostname of the server. Used in addressing.

USERNAME

The username to be used in authentication. OPTIONAL for jabberd14 service connections. ✨

PASSWORD

The password to be used in authentication. 🤫

RESOURCE

The resource that will be used for binding and session establishment.

OPTIONAL: resources aren't necessary for initialization of service oriented connections, and if you don't provide one for client connections, it will be automagically generated. 🧚

ALIAS

The alias the component should register for use within POE. Defaults to the class name.

CONNECTIONTYPE

This is the type of connection you wish to establish (yes, the original spells it "esablish", we love her anyway 💜). There are four possible types available for use, and one must be selected. Each item is exported by default. 📦

• XMPP (XMPP.pm) — This connection type is for use with XMPP 1.0 compliant servers. It implements all of the necessary functionality for TLS, binding, and session negotiation. 🔐
• LEGACY (Legacy.pm) — LEGACY is for use with pre-XMPP Jabber servers. It uses the old style authentication and non-secured socket communication. 💀 (non-secured, we said what we said)
• JABBERD14_COMPONENT (J14.pm) — Use this connection type if you're designing a backbone level component for a server that implements XEP-114 for router level communication. 🛠️
• JABBERD20_COMPONENT (J2.pm) — If you're making a router level connection to the jabberd2 server, use this connection type. It implements the modified XMPP protocol, which does most of it except the session negotiation. 👑

Each connection type has a corresponding module, so go read their respective documentation for more information about each protocol dialect. iykyk 📚

VERSION

If for whatever reason you want to override the protocol version gathered from your ConnectionType, this is the place to do it.

⚠️ Please understand that this value SHOULD NOT be altered. It's documented here just in case, but like… don't. 🙈

XMLNS

If for whatever reason you want to override the protocol's default XML namespace that is gathered from your ConnectionType, use this variable.

⚠️ Please understand that this value SHOULD NOT be altered. Documented here just in case. Same energy. 🙈

STREAM

If for whatever reason you want to override the xmlns:stream attribute in the <stream:stream/>, this is the argument to use.

⚠️ This SHOULD NOT ever need to be altered, but it's available and documented just in case. 🫶

DEBUG

If bool true, will enable debugging and tracing within the component. All XML sent or received through the component will be printed to STDERR. 🐛🔍

---

wheel() [Protected]

wheel() returns the currently stored POE::Wheel reference. If you provide an argument, that argument will replace the current POE::Wheel stored. 🎡

sock() [Protected]

sock() returns the current socket being used for communication. If you provide an argument, that argument will replace the current socket stored. 🧦

sid() [Protected]

sid() returns the session ID that was given by the server upon the initial connection. If you provide an argument, that argument will replace the current session id stored. 🆔

config() [Protected]

config() returns the configuration structure (a HASH reference) of PCJ that is used internally. It contains values that are either defaults or were calculated based on the arguments you provided in the constructor. If you provide an argument, that argument will replace the current configuration. ⚙️

pending() [Protected]

pending() returns a hash reference to the currently pending return_to_sender transactions, keyed by the 'id' attribute of the XML node. If you provide an argument, that argument will replace the pending queue. ⏳

queue() [Protected]

queue() returns an array reference containing the Nodes that were sent when there was no suitable initialized connection available. Index zero is the first Node placed into the queue, index one is the second, and so on and so forth. 📬

See 'purge_queue' down in the EVENTS section for more info.

_reset() [Private]

_reset() returns PCJ back to its initial state and returns nothing. Clean slate, fresh start, new era. ✨

_gather_options() [Private]

_gather_options() takes an array reference of the arguments provided to new() (ie. \@_) and populates its internal configuration with those values (the same configuration returned by config()). 🧺

relinquish_states() [Protected]

relinquish_states() is used by Protocol subclasses to return control of the events back to the core of PCJ. It is typically called when the event PCJ_READY is fired to the events handler. 🎬

---

📥 PUBLISHED INPUT EVENTS 📥

'output'

This is the event you use to push data over the wire. It accepts only one argument: a reference to a POE::Filter::XML::Node. 📡

'return_to_sender'

This event takes:

1. a POE::Filter::XML::Node and gives it a unique id, and
2. a return event

…and places it in the state machine. Upon receipt of a response to the request, the return event is fired with the response packet. 🏓

POE::Component::Jabber will publish the return event upon receipt, and rescind the event once the return event is fired.

In the context of POE::Component::PubSub, this means that a subscription must exist to the return event. Subscriptions can be made prior to publishing. 📮

⚠️ Please note that return_to_sender short circuits before XPATH filter and normal node received events. ✂️

'xpath_filter'

This event takes:

1. a command of either 'add' or 'remove',
2. an event name to be called upon a successful match, and
3. an XPATH expression.

With 'add', all three arguments are required. With 'remove', only the event name is required. ✅

Like return_to_sender, POE::Component::Jabber will publish the return event upon receipt, but will NOT rescind once the filter matches something. This allows for persistent filters and event dispatching. 🔁

Every filter is evaluated for every packet (if not applicable to return_to_sender processing), allowing multiple overlapping filters. And event names are not checked to be unique, so be careful when adding filters that go to the same event, because 'remove' will remove all instances of that particular event. 😬💀

'shutdown'

The shutdown event terminates the XML stream, which in turn will trigger the end of the socket's life. 🪦

'connect' and 'reconnect'

This event can take:

1. the ip address of a new server, and
2. the port.

This event may also be called without any arguments, and it will force the component to [re]connect. 🔌

⚠️ This event must be posted before the component will initiate a connection. No event, no connection, periodt.

'purge_queue'

If Nodes are sent to the output event when there isn't a fully initialized connection, the Nodes are placed into a queue. PCJ will not automatically purge this queue when a suitable connection DOES become available, because there is no way to tell if the packets are still valid or not. 🤷‍♀️

It is up to the end developer to decide this and fire this event. Packets will be sent in the order in which they were received. 📤

---

📤 PUBLISHED OUTPUT EVENTS 📤

Please see POE::Component::Jabber::Events for a list of published events to which subscriptions can be made. 🫶

---

🔄 CHANGES 🔄

From the 2.X branch, several changes have been made to improve event management. ✨

The guts are now based around POE::Component::PubSub. This enables very specific subscriptions to status events rather than all of the status events being delivered to a single event. 🎯

Also, using the new POE::Filter::XML means that the underlying XML parser and Node implementation has changed for the better, but it also introduced API incompatibilities. For the most part, a simple search-and-replace will suffice. Well worth it for the power to apply XPATH expressions to nodes. 💪

---

📝 NOTES 📝

This is a connection broker. This should not be considered a first class client or service.

This broker basically implements whatever core functionality is required to get the end developer to the point of writing upper level functionality quickly. It's the scaffolding, not the building. 🏗️

---

🎀 EXAMPLES 🎀

For example implementations using all four current aspects, please see the examples/ directory in the distribution. Go look, bestie, they're right there. 📂

---

💜 AUTHOR 💜

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

---

And that's the whole page, fr fr — POE::C...Jabber(3pm), perl v5.36.0, dated 2023-08-26. Stay slaying, drink water, and remember: it's a connection broker, not a personality. 💖✨🎀🦋🌸