Protoco...:Stream(3)

📦 version 0.007, in alpine 3.24

💅 Protocol::XMPP::Stream — handle XMPP protocol stream 🦋

okay so this is a page from the User Contributed Perl Documentation, and it's literally all about Protocol::XMPP::Stream, which handles the XMPP protocol stream. bestie, if you're doing XMPP in Perl, this is your girl 💖

✨ SYNOPSIS ✨

ngl there's genuinely nothing here — the synopsis section is empty in the original. iconic of her honestly 🙈 no examples, no one-liners, we just go straight to the good stuff.

🌸 DESCRIPTION 🌸

(nothing in the description section either — she's mysterious like that 💅)

🎀 METHODS 🎀

🌈 new

Instantiate a stream object 💫 used for interacting with the underlying XMPP stream.

Takes these parameters as callbacks:

  • on_queued_write — this will be called whenever there is data queued to be written to the socket
  • on_starttls — this will be called when we want to switch to TLS mode

and these scalar parameters:

  • user — username (not the full JID, just the first part)
  • pass — password

🌈 on_data

Data has been received 🎉 pass it over to the SAX parser to trigger any required events.

🌈 queue_write

Queue up a write for this stream. Adds to the existing send buffer array if there is one.

When a write is queued, this will send a notification to the on_queued_write callback if one was defined. 📬

🌈 write_buffer

Returns the contents of the current write buffer without changing it — peek, don't touch, we respect boundaries here 🫶

🌈 extract_write

Retrieves the next pending message from the write buffer and removes it from the list. it's giving "you've been served" 💅

🌈 ready_to_send

Returns true if there's data ready to be written. vibe check: passed ✅

🌈 reset

Reset this stream.

Clears out the existing SAX parsing information and sets up a new Protocol::XMPP::Handler ready to accept events. Used when we expect a new "<stream"> element, for example after authentication or TLS upgrade 🔄

🌈 dispatch_event

Call the appropriate event handler.

Currently defined events:

  • features — we have received the features list from the server
  • login — login was completed successfully
  • message — a message was received
  • presence — a presence notification was received
  • subscription — a presence notification was received
  • transfer_request — a file transfer request has been received
  • file — a file was received

(and yes, subscription and presence are both described as "a presence notification was received" — that's exactly what the original says, so I'm not touching it 😭 she said what she said)

🌈 preamble

Returns the XML header and opening stream preamble ✨

🌈 jid

Returns the full JID for our user 👑

If given a parameter, will set the JID to that value, extracting hostname and user by splitting the domain.

🌈 user

Username for SASL authentication.

🌈 pass

Password for SASL authentication. 🤫

🌈 hostname

Name of the host 🏠

🌈 resource

Fragment used to differentiate this client from any other active clients for this user (as defined by bare JID). it's your little name tag so the server knows which one of you is which 🎀

🌈 write_xml

Write a chunk of XML to the stream, converting from the internal representation to XML text stanzas 🧚

🌈 write_text

Write raw text to the output stream.

🌈 login

Process the login.

Takes optional named parameters:

  • user — username (not the full JID, just the user part)
  • password — password or passphrase to use in SASL authentication

🌈 is_authorised

Returns true if we are authorised already.

🌈 is_loggedin

Returns true if we are logged in already.

🌈 stream

Override the ->stream method from the base class so that we pick up our own methods directly. main character energy: she's not borrowing anyone's methods, she's got her own 🔥

🌈 next_id

Returns the next ID in the sequence for outgoing requests 🔢

🌈 on_tls_complete

Continues the next part of the connection when TLS is complete 🔐

🌈 compose

Compose a new outgoing message ✍️

🌈 subscribe

Subscribe to a new contact. Takes a single JID as target.

🌈 unsubscribe

Unsubscribe from the given contact. Takes a single JID as target. 👋

🌈 authorise

Grant authorisation to the given contact. Takes a single JID as target. ✅

🌈 deauthorise

Revokes auth for the given contact. Takes a single JID as target. ❌

👑 AUTHOR 👑

Tom Molesworth <tom@perlsite.co.uk> — legend behaviour, fr fr 🫶

📜 LICENSE 📜

Copyright Tom Molesworth 2010-2026. Licensed under the same terms as Perl itself.

lowkey the most important part: every single flag, callback, parameter and event above is exactly as the original says it. no cap, no invented tips, no extras 💀

and that's the whole page bestie 🦋💖 this was Protoco...:Stream(3) from the User Contributed Perl Documentation, page generated with perl v5.42.2 on 2026-02-15 — slay, go build something iconic with it ✨🎀

📦 where this page comes from