Net::Ja...Protocol(3)

📦
version 2.0 · 6 versions
, in alpine 3.24

🌸 Net::Jabber::Protocol 🌸

okay bestie, so this is Net::Jabber::Protocol(3) — straight out of the User Contributed Perl Documentation corner of the universe 💜. Yes, the title is abbreviated in the header (Net::Ja...Protocol(3)) but the real name is the full thing, and we're about to get into it.

✨ NAME ✨

Net::Jabber::Protocol — the Jabber Protocol Library 🦋 (yes, that Jabber, the instant-messaging one, and this module is the whole vibe)

🎀 SYNOPSIS 🎀

Net::Jabber::Protocol is a module that gives a developer easy access to the Jabber Instant Messaging protocol 💅. It hands high level functions to the Net::Jabber Client, Component, and Server objects. And the way these functions show up in those modules? Automatically, through AUTOLOAD and delegates ✨. You don't have to do anything, they're just there, like a good bestie.

💖 DESCRIPTION 💖

Protocol.pm is out here trying to give you enough high level APIs and automation of the low level APIs that writing a Jabber Client/Transport in Perl is trivial 😭 — like, actually trivial. And for the people who love to dig around down low? You can absolutely do that too, no gatekeeping. Those functions are covered in the documentation for each module, so go read those if that's your vibe 🫶.

Net::Jabber::Protocol provides functions to:

  • login
  • send and receive messages
  • set personal information
  • create a new user account
  • manage the roster
  • disconnect

And here's the gorgeous part: you can use all or none of the functions. There is no requirement. Pick and choose, build your own little stack, it's giving main character energy 👑.

For more information on how the details for how Net::Jabber is written, please see the help for Net::Jabber itself.

For more information on writing a Client, see Net::Jabber::Client.

For more information on writing a Transport, see Net::Jabber::Transport.

🦋 Modes 🦋

Several of the functions take a mode argument that lets you specify how the function should behave. This is the vibe check of the whole module, so pay attention 👀:

  • block — send the packet with an ID, and then block until an answer comes back. You can optionally specify a timeout so that you do not block forever. (please use the timeout, bestie, don't just sit there 😭)
  • nonblock — send the packet with an ID, but then return that ID and control to the master program. Net::Jabber is still tracking this packet, so you must use the CheckID function to tell when it comes in. (and yeah, the docs are literally like "this might not be very useful..." 💀 so take that as you will)
  • passthru — send the packet with an ID, but do NOT register it with Net::Jabber, then return the ID. This is useful when combined with the XPath function because you can register a one shot function tied to the ID you get back. chef's kiss combo, fr fr 🤌

🔥 Basic Functions 🔥

okay so first you gotta get your connection going. here's how, from Net::Jabber::Client:

use Net::Jabber qw( Client );
$Con = new Net::Jabber::Client();                # From
$status = $Con->Connect(hostname=>"jabber.org"); # Net::Jabber::Client

or, if Component is more your thing:

use Net::Jabber qw( Component );
$Con = new Net::Jabber::Component();             #
$status = $Con->Connect(hostname=>"jabber.org",  # From
                        secret=>"bob");          # Net::Jabber::Component

and for callback setup, go peek at Net::XMPP::Protocol:

#
# For callback setup, see Net::XMPP::Protocol
#

then you can flex your info like this:

$Con->Info(name=>"Jarl",
           version=>"v0.6000");

(that's you, saying hi, telling everyone who you are and what version you're on — iconic behavior honestly 🎀)

🧚 ID Functions 🧚

these are your send-with-an-ID girlies. every one of these hands you back an ID you can hang onto:

$id         = $Con->SendWithID($sendObj);
$id         = $Con->SendWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID($sendObj);
$receiveObj = $Con->SendAndReceiveWithID($sendObj,
                                         10);
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
$receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
                                         5);
$yesno      = $Con->ReceivedID($id);
$receiveObj = $Con->GetID($id);
$receiveObj = $Con->WaitForID($id);
$receiveObj = $Con->WaitForID($id,
                              20);

see how the numbers just show up there? those are timeouts, and SendAndReceiveWithID / WaitForID both take them optionally. ReceivedID gives you a yes/no. GetID and WaitForID give you the actual object back. slay 💅

⭐ IQ Functions ⭐

this is the big umbrella heading, and everything below lives under it. IQ functions, but make it a whole aesthetic 💖.

🍓 Agents Functions 🍓

%agents = $Con->AgentsGet();
%agents = $Con->AgentsGet(to=>"transport.jabber.org");

that's it, that's the whole thing — ask with no args for everything, or point it at a specific to 🌸

🌈 Browse Functions 🌈

%hash = $Con->BrowseRequest(jid=>"jabber.org");
%hash = $Con->BrowseRequest(jid=>"jabber.org",
                            timeout=>10);

$id = $Con->BrowseRequest(jid=>"jabber.org",
                          mode=>"nonblock");

$id = $Con->BrowseRequest(jid=>"jabber.org",
                          mode=>"passthru");

default vibe gives you back a %hash. add a timeout if you don't want to wait forever. or go mode=>"nonblock" / mode=>"passthru" and take the $id instead ✨

🦋 Browse DB Functions 🦋

$Con->BrowseDBDelete("jabber.org");
$Con->BrowseDBDelete(Net::Jabber::JID);

$presence  = $Con->BrowseDBQuery(jid=>"bob\@jabber.org");
$presence  = $Con->BrowseDBQuery(jid=>Net::Jabber::JID);
$presence  = $Con->BrowseDBQuery(jid=>"users.jabber.org",
                                 timeout=>10);
$presence  = $Con->BrowseDBQuery(jid=>"conference.jabber.org",
                                 refresh=>1);

BrowseDBDelete takes either a plain string or a Net::Jabber::JID. BrowseDBQuery hands you back a $presence, and it takes jid, an optional timeout, and a refresh flag 🫶 — note the \@ in there, escape it, don't get caught out 😭

💜 Bystreams Functions 💜

(yes, that's the heading name, we're keeping it exactly as it is, no notes 👑

%hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server");
%hash = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                      timeout=>10);

$id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                    mode=>"nonblock");

$id = $Con->ByteStreamsProxyRequest(jid=>"proxy.server",
                                    mode=>"passthru");

%hash = $Con->ByteStreamsProxyParse($query);

$status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                         jid=>"proxy.server");
$status = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                         jid=>"proxy.server",
                                        timeout=>10);

$id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                     jid=>"proxy.server",
                                    mode=>"nonblock");

$id = $Con->ByteStreamsProxyActivate(sid=>"stream_id",
                                     jid=>"proxy.server",
                                    mode=>"passthru");

$jid = $Con->ByteStreamsOffer(sid=>"stream_id",
                              streamhosts=>[{jid=>"jid",
                                             host=>"host",
                                             port=>"port",
                                             zeroconf=>"zero",
                                            },
                                            ...
                                           ],
                              jid=>"bob\@jabber.org");
$jid = $Con->ByteStreamsOffer(sid=>"stream_id",
                              streamhosts=>[{},{},...],
                              jid=>"bob\@jabber.org",
                              timeout=>10);

$id = $Con->ByteStreamsOffer(sid=>"stream_id",
                             streamhosts=>[{},{},...],
                             jid=>"bob\@jabber.org",
                             mode=>"nonblock");

$id = $Con->ByteStreamsOffer(sid=>"stream_id",
                             streamhosts=>[{},{},...],
                             jid=>"bob\@jabber.org",
                             mode=>"passthru");

okay so ByteStreamsProxyRequest = give me a %hash (or an $id with a mode, plus optional timeout). ByteStreamsProxyParse takes a $query and hands back a %hash. ByteStreamsProxyActivate takes sid + jid and gives you a $status, or an $id in nonblock/passthru, and yes it takes timeout too. ByteStreamsOffer takes sid, streamhosts (an arrayref of hashrefs with jid, host, port, zeroconf keys — ... means more of them, keep adding bestie), and jid, and gives you a $jid back — or an $id with a mode, and timeout is available there as well 💅✨

heads up: the alignment in those examples is straight from the original docs, quirks and all — copy the commands, not the spacing 💀

🧚 Disco Functions 🧚

%hash = $Con->DiscoInfoRequest(jid=>"jabber.org");
%hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
                               node=>"node...");
%hash = $Con->DiscoInfoRequest(jid=>"jabber.org",
                               node=>"node...",
                               timeout=>10);

$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                             mode=>"nonblock");
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                             node=>"node...",
                             mode=>"nonblock");

$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                             mode=>"passthru");
$id = $Con->DiscoInfoRequest(jid=>"jabber.org",
                             node=>"node...",
                             mode=>"passthru");

%hash = $Con->DiscoInfoParse($query);

%hash = $Con->DiscoItemsRequest(jid=>"jabber.org");
%hash = $Con->DiscoItemsRequest(jid=>"jabber.org",
                                timeout=>10);

$id = $Con->DiscoItemsRequest(jid=>"jabber.org",
                              mode=>"nonblock");

$id = $Con->DiscoItemsRequest(jid=>"jabber.org",
                              mode=>"passthru");

%hash = $Con->DiscoItemsParse($query);

DiscoInfoRequest takes jid, an optional node, an optional timeout, and the usual mode options. DiscoInfoParse turns a $query into a %hash. DiscoItemsRequest takes jid + optional timeout (or a mode), and DiscoItemsParse turns a $query into a %hash too 🌈✨

🌸 Feature Negotiation Functions 🌸

%hash = $Con->FeatureNegRequest(jid=>"jabber.org",
                                features=>{ feat1=>["opt1","opt2",...],
                                            feat2=>["optA","optB",...]
                                          }
                               );
%hash = $Con->FeatureNegRequest(jid=>"jabber.org",
                                features=>{ ... },
                                timeout=>10);

$id = $Con->FeatureNegRequest(jid=>"jabber.org",
                              features=>{ ... },
                              mode=>"nonblock");

$id = $Con->FeatureNegRequest(jid=>"jabber.org",
                              features=>{ ... },
                              mode=>"passthru");

my $query = $self->FeatureNegQuery(\{ ... });
$iq->AddQuery($query);

%hash = $Con->FeatureNegParse($query);

so FeatureNegRequest wants a jid and a features hashref where each feature key maps to an arrayref of its options — feat1 gets "opt1", "opt2", ..., feat2 gets "optA", "optB", ... — and yes, timeout and mode are available like everywhere else. then there's FeatureNegQuery(\{ ... }) which gives you a $query you can $iq->AddQuery($query), and FeatureNegParse($query) to get your %hash back 💖

🎀 File Transfer Functions 🎀

$method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                  sid=>"stream_id",
                                  filename=>"/path/to/file",
                                  methods=>["http://jabber.org/protocol/si/profile/bytestreams",
                                            "jabber:iq:oob",
                                            ...
                                           ]
                                 );
$method = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                                  sid=>"stream_id",
                                  filename=>"/path/to/file",
                                  methods=>\@methods,
                                  timeout=>"10");

$id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                              sid=>"stream_id",
                              filename=>"/path/to/file",
                              methods=>\@methods,
                              mode=>"nonblock");

$id = $Con->FileTransferOffer(jid=>"bob\@jabber.org",
                              sid=>"stream_id",
                              filename=>"/path/to/file",
                              methods=>\@methods,
                              mode=>"passthru");

FileTransferOffer takes jid, sid, filename, and methods. methods can be an inline arrayref with things like "http://jabber.org/protocol/si/profile/bytestreams", "jabber:iq:oob", ... — or you can pass \@methods. it hands you a $method back, or an $id if you go nonblock/passthru, and timeout is right there too (as "10", a string, in the example — copy it exactly, bestie 🫶) 🔥

⭐ Last Functions ⭐

$Con->LastQuery();
$Con->LastQuery(to=>"bob@jabber.org");

%result = $Con->LastQuery(mode=>"block");
%result = $Con->LastQuery(to=>"bob@jabber.org",
                          mode=>"block");

LastQuery can be called bare, or with a to, or with mode=>"block" — and %result comes back in the block examples. note there's no backslash on that bob@jabber.org here, that's exactly how it's written, don't @ me 👑💅

More LastQuery flex — same to=>"bob@jabber.org", same mode=>"block", same timeout=>10:

%result = $Con->LastQuery(to=>"bob@jabber.org",
                          mode=>"block",
                          timeout=>10);
%result = $Con->LastQuery(mode=>"block",
                          timeout=>10);

$Con->LastSend(to=>"bob@jabber.org");

$seconds = $Con->LastActivity();

💬 Multi-User Chat Functions

Joining a room is literally the easiest slay. Basic join first, then the password-protected version:

$Con->MUCJoin(room=>"jabber",
              server=>"conference.jabber.org",
              nick=>"nick");

$Con->MUCJoin(room=>"jabber",
              server=>"conference.jabber.org",
              nick=>"nick",
              password=>"secret");

🪪 Register Functions

Registering a user? RegisterSendData takes the target host and a little bundle of identity fields. No cap:

@result = $Con->RegisterSendData("users.jabber.org",
                                 first=>"Bob",
                                 last=>"Smith",
                                 nick=>"bob",
                                 email=>"foo@bar.net");

📞 RPC Functions

RPC time 🫶 — encode, parse, call, respond, and set callbacks. All the shapes are below, exactly as they appear:

$query = $Con->RPCEncode(type=>"methodCall",
                         methodName=>"methodName",
                         params=>[param,param,...]);
$query = $Con->RPCEncode(type=>"methodResponse",
                         params=>[param,param,...]);
$query = $Con->RPCEncode(type=>"methodResponse",
                         faultCode=>4,
                         faultString=>"Too many params");

@response = $Con->RPCParse($iq);

@response = $Con->RPCCall(to=>"dataHouse.jabber.org",
                          methodname=>"numUsers",
                          params=>[ param,param,... ]
                         );

$Con->RPCResponse(to=>"you\@jabber.org",
                  params=>[ param,param,... ]);

$Con->RPCResponse(to=>"you\@jabber.org",
                  faultCode=>"4",
                  faultString=>"Too many parameters"
                 );

$Con->RPCSetCallBacks(myMethodA=>\&methoda,
                      myMethodB=>\&do_somthing,
                      etc...
                     );

🔎 Search Functions

Search is giving directory energy: request fields, send a search, or send data straight to a service:

%fields = $Con->SearchRequest();
%fields = $Con->SearchRequest(to=>"users.jabber.org");
%fields = $Con->SearchRequest(to=>"users.jabber.org",
                              timeout=>10);

$Con->SearchSend(to=>"somewhere",
                 name=>"",
                 first=>"Bob",
                 last=>"",
                 nick=>"bob",
                 email=>"",
                 key=>"some key");

$Con->SearchSendData("users.jabber.org",
                     first=>"Bob",
                     last=>"",
                     nick=>"bob",
                     email=>"");

⏰ Time Functions

Time queries: fire one off, or ask for a blocking %result:

$Con->TimeQuery();
$Con->TimeQuery(to=>"bob@jabber.org");

%result = $Con->TimeQuery(mode=>"block");
%result = $Con->TimeQuery(to=>"bob@jabber.org",
                          mode=>"block");

$Con->TimeSend(to=>"bob@jabber.org");

🏷️ Version Functions

Version queries: same deal — fire-and-forget or blocking %result. And yes, VersionSend carries name, ver, and os:

$Con->VersionQuery();
$Con->VersionQuery(to=>"bob@jabber.org");

%result = $Con->VersionQuery(mode=>"block");
%result = $Con->VersionQuery(to=>"bob@jabber.org",
                             mode=>"block");

$Con->VersionSend(to=>"bob@jabber.org",
                  name=>"Net::Jabber",
                  ver=>"1.0a",
                  os=>"Perl");

🔧 METHODS 🔧

🧸 Basic Functions

Stash your identity so Net::Jabber can auto-reply to some packets for you and save you some work:

Info(name=>string,
     version=>string)
⚠️ NOTE: this requires that you use the SetIQCallBacks methodology and not the SetCallBacks for <iq/> packets. That distinction is lowkey important, bestie.

📡 IQ Functions

🕵️ Agents Functions

⚠️ Deprecated in favor of Disco — this section is legacy, so don’t build new stuff on it. The details stay because we don’t erase lore. 💅

AgentsGet

AgentsGet(to=>string,
AgentsGet()

This takes all of the information and builds a Net::Jabber::IQ::Agents packet. It then sends that packet either to the server, or to the specified transport, with an ID, and waits for that ID to return. Then it looks in the resulting packet and builds a hash that contains the values of the agent list. The hash is laid out like this — and yes, the jid is the key that distinguishes the various agents:

$hash{<JID>}->{order} = 4
            ->{name} = "ICQ Transport"
            ->{transport} = "ICQ #"
            ->{description} = "ICQ..blah.."
            ->{service} = "icq"
            ->{register} = 1
            ->{search} = 1
          etc...

The order field determines the order that it came from the server in… in case you care. For more info on the valid fields, see the Net::Jabber::Query jabber:iq:agent namespace.

🧭 Browse Functions

⚠️ Deprecated in favor of Disco — iconic relic behavior, but still deprecated. Don’t act brand new about it.

BrowseRequest

BrowseRequest(jid=>string,
              mode=>string,
              timeout=>int)

This sends a jabber:iq:browse request to the jid passed as an argument. It returns a hash with the resulting tree if mode is set to "block":

$browse{'category'} = "conference"
$browse{'children'}->[0]
$browse{'children'}->[1]
$browse{'children'}->[11]
$browse{'jid'} = "conference.jabber.org"
$browse{'name'} = "Jabber.org Conferencing Center"
$browse{'ns'}->[0]
$browse{'ns'}->[1]
$browse{'type'} = "public"

The ns array is an array of the namespaces that this jid supports. The children array points to hashes of this form, and represent the fact that they can be browsed to.

See MODES above for using the mode and timeout.

🗄️ Browse DB Functions

BrowseDBDelete

BrowseDBDelete(string|Net::Jabber::JID)

Deletes this JID’s browse data from the DB.

BrowseDBQuery

BrowseDBQuery(jid=>string | NJ::JID,
              timeout=>integer,
              refresh=>0|1)

Returns the browse data for the requested JID. If the DB does not contain the data for the JID, then it attempts to fetch the data via BrowseRequest(). The timeout is passed to the BrowseRequest() call, and refresh tells the DB to request the data, even if it already has some.

🌊 Bytestreams Functions

ByteStreamsProxyRequest

ByteStreamsProxyRequest(jid=>string,
                        mode=>string,
                        timeout=>int)

Sends a bytestreams request to the jid passed as an argument. It returns an array ref with the resulting tree if mode is set to "block".

See ByteStreamsProxyParse for the format of the resulting tree.

See MODES above for using the mode and timeout.

ByteStreamsProxyParse

ByteStreamsProxyParse(Net::Jabber::Query)

Parses the query and returns an array ref to the resulting tree:

$host[0]->{jid} = "bytestreams1.proxy.server";
$host[0]->{host} = "proxy1.server";
$host[0]->{port} = "5006";
$host[1]->{jid} = "bytestreams2.proxy.server";
$host[1]->{host} = "proxy2.server";
$host[1]->{port} = "5007";
...

ByteStreamsProxyActivate

ByteStreamsProxyActivate(jid=>string,
                         sid=>string,
                         mode=>string,
                         timeout=>int)

Sends a bytestreams activate to the jid passed as an argument. If mode is set to "block", it returns 1 if the proxy activated, and undef if it did not.

sid is the stream id that is being used to talk about this stream.

See MODES above for using the mode and timeout.

ByteStreamsOffer

ByteStreamsOffer(jid=>string,
                 sid=>string,
                 streamhosts=>arrayref,
                 mode=>string,
                 timeout=>int)

Sends a bytestreams offer to the jid passed as an argument. If mode is set to "block", it returns the jid of the streamhost that the user selected.

streamhosts is the same format as the array ref returned from ByteStreamsProxyParse.

See MODES above for using the mode and timeout.

✨ Disco Functions ✨

  • DiscoInfoRequest(jid=>string, node=>string, mode=>string, timeout=>int) — sends a disco#info request to the jid you pass in, and to the node too if you specified one. If mode is set to "block" you get a hash back with the resulting tree, bestie. 💅

Wanna know what that tree looks like? Peek at DiscoInfoParse, it's literally right there.

And for the whole mode + timeout situation, scroll up to MODES above, iykyk.

  • DiscoInfoParse(Net::Jabber::Query) — parses the query and hands you back a hash ref to the resulting tree, like this:
$info{identity}->[0]->{category} = "groupchat";
$info{identity}->[0]->{name} = "Public Chatrooms";
$info{identity}->[0]->{type} = "public";

$info{identity}->[1]->{category} = "groupchat";
$info{identity}->[1]->{name} = "Private Chatrooms";
$info{identity}->[1]->{type} = "private";

$info{feature}->{http://jabber.org/protocol/disco#info} = 1;
$info{feature}->{http://jabber.org/protocol/muc#admin} = 1;
  • DiscoItemsRequest(jid=>string, mode=>string, timeout=>int) — fires off a disco#items request to the jid you passed in. If mode is "block", congrats, you get a hash with the resulting tree. 🎀

The format of that tree? That's DiscoItemsParse's whole thing.

Mode + timeout deets live up in MODES above. Go look, fr fr.

  • DiscoItemsParse(Net::Jabber::Query) — parses the query and returns a hash ref to the resulting tree, which looks like:
$items{jid}->{node} = name;

$items{"proxy.server"}->{""} = "Bytestream Proxy Server";
$items{"conf.server"}->{"public"} = "Public Chatrooms";
$items{"conf.server"}->{"private"} = "Private Chatrooms";

🌸 Feature Negotiation Functions 🌸

  • FeatureNegRequest(jid=>string, features=>hash ref, mode=>string, timeout=>int) — sends a feature negotiation to the jid you passed in, using the features you specified. If mode is "block" you get a hash with the resulting tree back. Obsessed. 💖

Curious about the format of that features hash ref? Run, don't walk, to DiscoInfoQuery.

For the resulting tree's format, check DiscoInfoParse.

And mode + timeout? MODES above, babe. Always MODES.

  • FeatureNegParse(Net::Jabber::Query) — parses the query and returns a hash ref to the resulting tree:
$features->{feat1} = ["opt1","opt2",...];
$features->{feat2} = ["optA","optB",...];
....

But if this is a result, it's giving something different:

$features->{feat1} = "opt2";
$features->{feat2} = "optA";
....
  • FeatureNeqQuery(hash ref) — takes a hash ref and turns it into a feature negotiation query that you can AddQuery into your packet. The hash ref format goes like this:
$features->{feat1} = ["opt1","opt2",...];
$features->{feat2} = ["optA","optB",...];
....

🦋 File Transfer Functions 🦋

  • FileTransferOffer(jid=>string, sid=>string, filename=>string, mode=>string, timeout=>int) — sends a file transfer stream initiation to the jid you passed in. Returns the method if the user accepts, undef if the user declines — but only when mode is set to "block", okay? 😭

Mode and timeout usage? Say it with me: MODES above. 👑

⭐ Last Functions ⭐

  • LastQuery(to=>string, mode=>string, timeout=>int) / LastQuery() — asks the jid you specified for its last activity. If to is blank, then it queries the server instead. If mode is "block" you get a hash back with the various items set:
$last{seconds} - Seconds since activity
$last{message} - Message for activity

Mode and timeout? You already know — MODES above. 💫

  • LastSend(to=>string, hash) — sends the specified last to the specified jid. That hash is the seconds and message, exactly like the Net::Jabber::Query man page shows.
  • LastActivity() — returns the number of seconds since the user's last activity. That's it, that's the whole vibe check. 🕐

🌈 Multi-User Chat Functions 🌈

  • MUCJoin(room=>string, server=>string, nick=>string, password=>string) — sends the appropriate MUC protocol to join the specified room with the specified nick. Go be the main character in that group chat. 👑

🎀 Register Functions 🎀

  • RegisterSendData(string|JID, hash) — takes the contents of the hash and builds a jabebr:x:data return packet, which it sends in a Net::Jabber::Query jabber:iq:register namespace packet. The first argument is the JID to send the packet to. This function returns an array that looks like this:
[ type , message ]

If type is "ok" then registration ate and left no crumbs — successful! Otherwise message contains a little more detail about the error. 🙈

🔥 RPC Functions 🔥

  • RPCParse(IQ object) — returns an array. The first argument tells you the status: "ok" or "fault". The second argument is an array if it's "ok", or a hash if it's "fault".
  • RPCCall(to=>jid|string, methodName=>string, params=>array, mode=>string, timeout=>int) — takes the methodName and params, builds the RPC call, and sends it to the specified address. Returns the data described above from RPCParse.

Mode and timeout — yeah, MODES above. 💜

  • RPCResponse(to=>jid|string, params=>array, faultCode=>int, faultString=>string) — generates a response back to the caller. If any part of fault is specified, then fault wins. No competition, fault just takes it. 💀
Note: to make sure you get the correct type for a param sent back, you can specify the type by prepending it to the value:
"i4:5" or "int:5"
"boolean:0"
"string:56"
"double:5.0"
"datetime:20020415T11:11:11"
"base64:...."
  • RPCSetCallBacks(method=>function, method=>function, etc...) — sets the callback functions for the specified methods. The method comes from the <methodName/> and is case sensitive, so don't get cute with capitalisation. The single arguemnt is a ref to an array that contains the <params/>. The function you write should return one of two things:
["ok", [...] ]

The [...] is a list of the <params/> you want to return. Or:

["fault", {faultCode=>1,
           faultString=>...} ]

If you set the function to undef, then the method is removed from the list. Bye bestie. 🫶

🧚 Search Functions 🧚

  • SearchRequest(to=>string, mode=>string, timeout=>int) / SearchRequest() — sends an <iq/> request to the specified server/transport, and if nothing's specified it sends to the current active server instead. The function returns a hash containing the required fields. Here's an example of that hash:
$hash{fields}    - The raw fields from
                   the iq:register.  To
                   be used if there is
                   no x:data in the
                   packet.
$hash{instructions} - How to fill out
                      the form.
$hash{form}   - The new dynamic forms.

Inside $hash{form}, the fields that are present are the required fields the server needs.

Mode and timeout? One last time for the people in the back: MODES above. 🍓

  • SearchSend(to=>string|JID, hash) — takes the contents of the hash and passes it to the SetSearch function in the Net::Jabber::Query jabber:iq:search namespace. And then it sends the packet. Slay. ✨
  • SearchSendData(string|JID, hash) — takes everything chillin' in the hash and builds a jabber:x:data return packet, then sends it inside a Net::Jabber::Query jabber:iq:search namespace packet. The first argument is the JID you're sending to. (Tiny note: the original page spells the namespace jabebr:x:data — that's a typo bestie, the real one is jabber:x:data 💅)

⏰ Time Functions ⏰

  • TimeQuery(to=>string, mode=>string, timeout=>int) — asks the jid you named for its localtime. If to is blank, it just goes and queries the server instead. Returns a hash with all the juicy stuff filled in — but only if mode is set to "block":
$time{utc}     - Time in UTC
$time{tz}      - Timezone
$time{display} - Display string
  • TimeQuery() — yeah, you can call it with no args at all, same deal as above ✨
Peep the MODES section (back up above 👀) for how to actually use mode and timeout. Don't skip it, it's literally the whole vibe check for blocking vs non-blocking.
  • TimeSend(to=>string) — sends the current UTC time to the jid you specified. That's it. Slay, efficient, no notes. 🕐

🖥️ Version Functions 🖥️

  • VersionQuery(to=>string, mode=>string, timeout=>int) — asks the jid you specified for its client version info. If to is blank, it queries the server. Returns a hash with the good stuff set if mode is "block":
$version{name} - Name
$version{ver}  - Version
$version{os}   - Operating System/Platform
  • VersionQuery() — the no-argument version, same energy, same return 💖
Again: see MODES above for mode and timeout. It's giving "read the docs", because you literally should 🌸
  • VersionSend(to=>string, name=>string, ver=>string, os=>string) — sends the version info you hand it over to the jid sitting in to. Name, version, OS — the whole little identity card 🎀

👑 AUTHOR 👑

Ryan Eatmon. That's the icon, that's the main character, that's who wrote this. 🫶

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Fr fr, go wild with it, just keep the same terms. 💜

okay that's a wrap on the whole page bestie!! 🌈 you made it to the very end, I'm so proud 😭💖 this copy came from perl v5.42.2, dated 2026-02-15, and the page itself is Net::Ja...Protocol(3) — go build something iconic with it, mwah 💅✨🍓

📦 where this page comes from