Net::X...rotocol(3pm)

📦
version 1.05 · 8 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay so bestie, welcome to Net::XMPP::Protocol — the XMPP Protocol Module. 🦋 (The header on this page reads Net::XMPP::Protocol(3pm) and it's filed under User Contributed Perl Documentation — that's your receipt, keep it 🧾.)

✨ SYNOPSIS ✨

Net::XMPP::Protocol is a module that gives a developer easy access to the XMPP Instant Messaging protocol. It literally hands you high-level functions for the Net::XMPP Client object, and those functions are inherited by that module. no cap, that's the whole pitch 👑

🦋 DESCRIPTION 🦋

Protocol.pm is out here trying to provide enough high-level APIs — and enough automation of the low-level APIs — that writing an XMPP Client in Perl is trivial. Like, actually trivial. 🎀

And if you're the type who wants to work with the low level directly? You can do that too, bestie, nobody's stopping you — but those functions are covered in the documentation for each module, not here.

Net::XMPP::Protocol gives you functions to log in, send and receive messages, set personal information, create a new user account, manage the roster, and disconnect. You can use all or none of the functions — there is no requirement. pick your faves, it's giving à la carte 🍓

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

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

🎀 Modes 🎀

Several of the functions take a mode argument that lets you specify how the function should behave. Three flavors, all iconic in their own way:

  • block — sends the packet with an ID, and then blocks until an answer comes back. You can optionally specify a timeout so that you do not block forever. (please use the timeout, i'm begging 🙈)
  • nonblock — sends the packet with an ID, but then returns that id and control back to the master program. Net::XMPP is still tracking this packet, so you must use the CheckID function to tell when it comes in. (This might not be very useful...) 💀
  • passthru — sends the packet with an ID, but does NOT register it with Net::XMPP, then returns 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. big brain energy 🔥

🌸 Basic Functions 🌸

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

$Con->SetCallBacks(send=>\&sendCallBack,
                   receive=>\&receiveCallBack,
                   message=>\&messageCallBack,
                   iq=>\&handleTheIQTag);

$Con->SetMessageCallBacks(normal=>\&messageNormalCB,
                          chat=>\&messageChatCB);

$Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
                           unavailable=>\&presenceUnavailableCB);

$Con->SetIQCallBacks("custom-namespace"=>
                                         {
                                             get=>\&iqCustomGetCB,
                                             set=>\&iqCustomSetCB,
                                             result=>\&iqCustomResultCB,
                                         },
                                         etc...
                                        );

$Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
                        "/message[@type='chat']"=>&otherMessageChatCB,
                        ...
                       );

$Con->RemoveXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);

$Con->SetDirectXPathCallBacks("/anything"=>&anythingCB,
                              "/anotherthing[@foo='bar']"=>&anotherthingFooBarCB,
                              ...
                             );

$Con->RemoveDirectXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);

$error = $Con->GetErrorCode();
$Con->SetErrorCode("Timeout limit reached");

$status = $Con->Process();
$status = $Con->Process(5);

$Con->Send($object);
$Con->Send("<tag>XML</tag>");

$Con->Send($object,1);
$Con->Send("<tag>XML</tag>",1);

$Con->Disconnect();

💅 ID Functions 💅

$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);

🧚 Namespace Functions 🧚

$Con->AddNamespace(ns=>"foo:bar",
                   tag=>"myfoo",
                   xpath=>{Foo=>{ path=> "foo/text()" },
                           Bar=>{ path=> "bar/text()" },
                           FooBar=>{ type=> "master" },
                          }
                  );

💌 Message Functions 💌

$Con->MessageSend(to=>"bob@jabber.org",
                  subject=>"Lunch",
                  body=>"Let's go grab some...\n",
                  thread=>"ABC123",
                  priority=>10);

🌈 Presence Functions 🌈

$Con->PresenceSend();
$Con->PresenceSend(type=>"unavailable");
$Con->PresenceSend(show=>"away");
$Con->PresenceSend(signature=>...signature...);

💫 Subscription Functions 💫

$Con->Subscription(type=>"subscribe",
                   to=>"bob@jabber.org");

$Con->Subscription(type=>"unsubscribe",
                   to=>"bob@jabber.org");

$Con->Subscription(type=>"subscribed",
                   to=>"bob@jabber.org");

$Con->Subscription(type=>"unsubscribed",
                   to=>"bob@jabber.org");

🍓 Presence DB Functions 🍓

$Con->PresenceDB();

$Con->PresenceDBParse(Net::XMPP::Presence);

$Con->PresenceDBDelete("bob\@jabber.org");
$Con->PresenceDBDelete(Net::XMPP::JID);

$Con->PresenceDBClear();

$presence  = $Con->PresenceDBQuery("bob\@jabber.org");
$presence  = $Con->PresenceDBQuery(Net::XMPP::JID);

@resources = $Con->PresenceDBResources("bob\@jabber.org");
@resources = $Con->PresenceDBResources(Net::XMPP::JID);

⭐ IQ Functions ⭐

okay so this heading is literally here and there's nothing under it before Auth Functions. that's it. that's the section. empty. we respect the emptiness 🫶

🔐 Auth Functions 🔐

@result = $Con->AuthSend();
@result = $Con->AuthSend(username=>"bob",
                         password=>"bobrulez",
                         resource=>"Bob");

📝 Register Functions 📝

%hash   = $Con->RegisterRequest();
%hash   = $Con->RegisterRequest(to=>"transport.jabber.org");
%hash   = $Con->RegisterRequest(to=>"transport.jabber.org",
                                timeout=>10);

@result = $Con->RegisterSend(to=>"somewhere",
                             username=>"newuser",
                             resource=>"New User",
                             password=>"imanewbie",
                             email=>"newguy@new.com",
                             key=>"some key");

👑 Roster Functions 👑

$Roster = $Con->Roster();

%roster = $Con->RosterParse($iq);
%roster = $Con->RosterGet();
$Con->RosterRequest();
$Con->RosterAdd(jid=>"bob\@jabber.org",
                name=>"Bob");
$Con->RosterRemove(jid=>"bob@jabber.org");

💀 Roster DB Functions 💀

$Con->RosterDB();

$Con->RosterDBParse(Net::XMPP::IQ);

$Con->RosterDBAdd("bob\@jabber.org",
                  name=>"Bob",
                  groups=>["foo"]
                 );

$Con->RosterDBRemove("bob\@jabber.org");
$Con->RosterDBRemove(Net::XMPP::JID);

$Con->RosterDBClear();

if ($Con->RosterDBExists("bob\@jabber.org")) { ...
if ($Con->RosterDBExists(Net::XMPP::JID)) { ...

@jids = $Con->RosterDBJIDs();

if ($Con->RosterDBGroupExists("foo")) { ...

@groups = $Con->RosterDBGroups();

@jids = $Con->RosterDBGroupJIDs("foo");

@jids = $Con->RosterDBNonGroupJIDs();

%hash = $Con->RosterDBQuery("bob\@jabber.org");
%hash = $Con->RosterDBQuery(Net::XMPP::JID);

$value = $Con->RosterDBQuery("bob\@jabber.org","name");
$value = $Con->RosterDBQuery(Net::XMPP::JID,"groups");

🌟 METHODS 🌟

💖 Basic Functions 💖

GetErrorCode()

returns a string that will hopefully contain some useful information about why a function returned an undef to you. like a little note from your code saying "hey, here's what went wrong" 😭

SetErrorCode

SetErrorCode(string)

set a useful error message before you return an undef to the caller. be nice to your caller, they're doing their best 🫶

SetCallBacks

SetCallBacks(message=>function,
               presence=>function,
               iq=>function,
               send=>function,
               receive=>function,
               update=>function)

sets the callback functions for the top level tags listed. The available tags to look for are <message/>, <presence/>, and <iq/>. If a packet is received with an ID which is found in the registered ID list (see RegisterID below) then it is not sent to these functions — instead it is inserted into a LIST and can be retrieved by some functions we will mention later. 👀

send and receive are used to log what XML is sent and received. update is used as a way to update your program while waiting for a packet with an ID to be returned (useful for GUI apps).

A major change that came with the last release is that the session id is passed to the callback as the first argument. This was done to facilitate the Server module. (slay, breaking changes 💅)

The next argument depends on which callback you're talking about. message, presence, and iq all get passed in Net::XMPP objects that match those types. send and receive get passed in strings. update gets passed nothing, not even the session id. rude but okay 😤

If you set the function to undef, then the callback is removed from the list.

SetPresenceCallBacks

SetPresenceCallBacks(type=>function etc...)

sets the callback functions for the specified presence type. The function takes types as the main key, and lets you specify a function for each type of packet you can get. The full roster of types:

  • "available"
  • "unavailable"
  • "subscribe"
  • "unsubscribe"
  • "subscribed"
  • "unsubscribed"
  • "probe"
  • "error"

When it gets a <presence/> packet it checks the type='' for a defined callback. If there is one, then it calls the function with two arguments:

  1. the session ID, and the
  2. Net::XMPP::Presence object.

If you set the function to undef, then the callback is removed from the list.

🚨 NOTE: If you use this, which is a cleaner method, then you must *NOT* specify a callback for presence in the SetCallBacks function. no cap, do not do it, the vibes will be off 💀

okay so Net::XMPP defines a few default callbacks for various types:

  • "subscribe" — replies with subscribed
  • "unsubscribe" — replies with unsubscribed
  • "subscribed" — replies with subscribed
  • "unsubscribed" — replies with unsubscribed

💬 SetMessageCallBacks

SetMessageCallBacks(type=>function, etc...)

sets the callback functions for the specified message type. The function takes types as the main key, and lets you specify a function for each type of packet you can get.

The types are literally:

  • "normal"
  • "chat"
  • "groupchat"
  • "headline"
  • "error"

When it gets a <message/> packet it checks the type='' for a defined callback. If there is one then it calls the function with two arguments:

  • the session ID, and
  • the Net::XMPP::Message object.

If you set the function to undef, then the callback is removed from the list.

⚠️ NOTE: If you use this, which is a cleaner method, then you must *NOT* specify a callback for message in the SetCallBacks function.

🧠 SetIQCallBacks

SetIQCallBacks(namespace=>{
                   get=>function,
                   set=>function,
                   result=>function
                 },
                 etc...)

sets the callback functions for the specified namespace. The function takes namespaces as the main key, and lets you specify a function for each type of packet you can get.

The types are:

  • "get"
  • "set"
  • "result"

When it gets an <iq/> packet it checks the type='' and the xmlns='' for a defined callback. If there is one then it calls the function with two arguments: the session ID, and the Net::XMPP::xxxx object.

If you set the function to undef, then the callback is removed from the list.

⚠️ NOTE: If you use this, which is a cleaner method, then you must *NOT* specify a callback for iq in the SetCallBacks function.

🧚 SetXPathCallBacks

SetXPathCallBacks(xpath=>function, etc...)

registers a callback function for each xpath specified. If Net::XMPP matches the xpath, then it calls the function with two arguments:

  • the session ID, and
  • the Net::XMPP::Message object.

Xpaths are rooted at each packet:

/message[@type="chat"]
/iq/*[xmlns="jabber:iq:roster"][1]
...

🫶 RemoveXPathCallBacks

RemoveXPathCallBacks(xpath=>function, etc...)

unregisters a callback function for each xpath specified.

🦋 SetDirectXPathCallBacks

SetDirectXPathCallBacks(xpath=>function, etc...)

registers a callback function for each xpath specified. If Net::XMPP matches the xpath, then it calls the function with two arguments:

  • the session ID, and
  • the XML::Stream::Node object.

Xpaths are rooted at each packet:

/anything
/anotherthing/foo/[1]
...

The big difference between this and regular XPathCallBacks is the fact that this passes in the XML directly and not a Net::XMPP based object.

💅 RemoveDirectXPathCallBacks

RemoveDirectXPathCallBacks(xpath=>function, etc...)

unregisters a callback function for each xpath specified.

🔥 Process

Process(integer)

takes the timeout period as an argument. If no timeout is listed then the function blocks until a packet is received. Otherwise it waits that number of seconds and then exits so your program can continue doing useful things.

💡 NOTE: This is important for GUIs. You need to leave time to process GUI commands even if you are waiting for packets.

The following are the possible return values, and what they mean:

1   - Status ok, data received.
0   - Status ok, no data received.
undef - Status not ok, stop processing.
🚨 IMPORTANT: You need to check the output of every Process. If you get an undef then the connection died and you should behave accordingly. no cap, bestie, this one matters.

📤 Send

Send(object, ignoreActivity)
Send(string, ignoreActivity)

takes either a Net::XMPP::xxxxx object or an XML string as an argument and sends it to the server. If you set ignoreActivty to 1, then the XML::Stream module will not record this packet as couting towards user activity.

🆔 ID Functions

🌟 SendWithID

SendWithID(object)
SendWithID(string)

takes either a Net::XMPP::xxxxx object or an XML string as an argument, adds the next available ID number and sends that packet to the server. Returns the ID number assigned.

💌 SendAndReceiveWithID

SendAndReceiveWithID(object, timeout)
SendAndReceiveWithID(string, timeout)

uses SendWithID and WaitForID to provide a complete way to send and receive packets with IDs. Can take either a Net::XMPP::xxxxx object or an XML string. Returns the proper Net::XMPP::xxxxx object based on the type of packet received. The timeout is passed on to WaitForID, see that function for how the timeout works.

📬 ReceivedID

ReceivedID(integer)

returns 1 if a packet has been received with specified ID, 0 otherwise.

🎀 GetID

GetID(integer)

returns the proper Net::XMPP::xxxxx object based on the type of packet received with the specified ID. If the ID has been received the GetID returns 0.

⏳ WaitForID

WaitForID(integer, timeout)

blocks until a packet with the ID is received. Returns the proper Net::XMPP::xxxxx object based on the type of packet received. If the timeout limit is reached then if the packet does come in, it will be discarded.

⚠️ NOTE: Only <iq/> officially support ids, so sending a <message/>, or <presence/> with an id is a risk. The server will ignore the id tag and pass it through, so both clients must support the id tag for these functions to be useful.

🌐 Namespace Functions

🌈 AddNamespace

AddNamespace(ns=>string,
             tag=>string,
             xpath=>hash)

This function is very complex. It is a little too complex to discuss within the confines of this small paragraph. Please refer to the man page for Net::XMPP::Namespaces for the full documentation on this subject.

✉️ Message Functions

💌 MessageSend

MessageSend(hash)

takes the hash and passes it to SetMessage in Net::XMPP::Message (refer there for valid settings). Then it sends the message to the server.

🟢 Presence Functions

🫧 PresenceSend

PresenceSend()
PresenceSend(hash, signature=>string)

No arguments will send an empty Presence to the server to tell it that you are available. If you provide a hash, then it will pass that hash to the SetPresence() function as defined in the Net::XMPP::Presence module. Optionally, you can specify a signature and a jabber:x:signed will be placed in the <presence/>.

🔔 Subscription Functions

📩 Subscription

Subscription(hash)

taks the hash and passes it to SetPresence in Net::XMPP::Presence (refer there for valid settings). Then it sends the subscription to server.

The valid types of subscription are:

subscribe    - subscribe to JID's presence
unsubscribe  - unsubscribe from JID's presence
subscribed   - response to a subscribe
unsubscribed - response to an unsubscribe

🗂️ Presence DB Functions

🗃️ PresenceDB

PresenceDB()

Tell the object to initialize the callbacks to automatically populate the Presence DB.

🔍 PresenceDBParse

PresenceDBParse(Net::XMPP::Presence)

for every presence that you receive pass the Presence object to the DB so that it can track the resources and priorities for you. Returns either the presence passed in, if it not able to parsed for the DB, or the current presence as found by the PresenceDBQuery function.

🗑️ PresenceDBDelete

PresenceDBDelete(string|Net::XMPP::JID)

delete thes JID entry from the DB.

🧹 PresenceDBClear

PresenceDBClear()

delete all entries in the database.

🔎 PresenceDBQuery

PresenceDBQuery(string|Net::XMPP::JID)

returns the NX::Presence that was last received for the highest priority of this JID. You can pass it a string or a NX::JID object.

📚 PresenceDBResources

PresenceDBResources(string|Net::XMPP::JID)

returns an array of resources in order from highest priority to lowest.

🧠 IQ Functions

🔐 Auth Functions

🔑 AuthSend

AuthSend(username=>string,
         password=>string,
         resource=>string)

takes all of the information and builds a Net::XMPP::IQ::Auth packet. It then sends that packet to the server with an ID and waits for that ID to return. Then it looks in resulting packet and determines if authentication was successful for not. The array returned from AuthSend looks like this:

[ type , message ]

If type is "ok" then authentication was successful, otherwise message contains a little more detail about the error.

📝 IQ::Register Functions

📨 RegisterRequest

RegisterRequest(to=>string,  timeout=>int)
RegisterRequest()

send an <iq/> request to the specified server/transport, if not specified it sends to the current active server. The function returns a hash that contains the required fields. Here is an example of the 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.

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

📮 RegisterSend

RegisterSend(hash)

takes the contents of the hash and passes it to the SetRegister function in the module Net::XMPP::Query jabber:iq:register namespace. This function returns an array that looks like this:

[ type , message ]

If type is "ok" then registration was successful, otherwise message contains a little more detail about the error.

📇 Roster Functions

👑 Roster

Roster()

This call returns a Net::XMPP::Roster object, and it's lowkey iconic: it automatically intercepts all the roster and presence packets sent from the server and gives you an accurate Roster. For more information, please read the man page for Net::XMPP::Roster. 🦋

✨ RosterParse(IQ object) ✨

Returns a hash that contains the roster parsed into this exact data structure:

$roster{'bob@jabber.org'}->{name}
                    - Name you stored in the roster

$roster{'bob@jabber.org'}->{subscription}
                    - Subscription status
                      (to, from, both, none)

$roster{'bob@jabber.org'}->{ask}
                    - The ask status from this user
                      (subscribe, unsubscribe)

$roster{'bob@jabber.org'}->{groups}
                    - Array of groups that
                      bob@jabber.org is in

✨ RosterGet() ✨

Sends an empty Net::XMPP::IQ::Roster tag to the server so the server will send the Roster to the client. Returns the above hash from RosterParse. 💖

✨ RosterRequest() ✨

Sends an empty Net::XMPP::IQ::Roster tag to the server so the server will send the Roster to the client.

✨ RosterAdd(hash) ✨

Sends a packet asking that the jid be added to the roster. The hash format is defined in the SetItem function in the Net::XMPP::Query jabber:iq:roster namespace.

✨ RosterRemove(hash) ✨

Sends a packet asking that the jid be removed from the roster. The hash format is defined in the SetItem function in the Net::XMPP::Query jabber:iq:roster namespace.

✨ ROSTER DB FUNCTIONS ✨

RosterDB()

Tells the object to initialize the callbacks to automatically populate the Roster DB. If you do this, then make sure that you call RosterRequest() instead of RosterGet() so that the callbacks can catch it and parse it. 🫶

RosterDBParse(IQ object)

If you want to manually control the database, then you can pass in all iq packets with jabber:iq:roster queries to this function. 🧚

RosterDBAdd(jid,hash)

Adds a new JID into the roster DB. The JID is either a string, or a Net::XMPP::JID object. The hash must be the same format as the hash returned by RosterParse above, and is the actual hash, not a reference. 💅

RosterDBRemove(jid)

Removes a JID from the roster DB. The JID is either a string, or a Net::XMPP::JID object.

RosterDBClear

Removes all JIDs from the roster DB. All of them. Gone. 🫧

RosterDBExists(jid)

Returns 1 if the JID exists in the roster DB, undef otherwise. The JID is either a string, or a Net::XMPP::JID object.

RosterDBJIDs()

Returns a list of Net::XMPP::JID objects that represents all of the JIDs in the DB. 👑

RosterDBGroups

Returns the complete list of roster groups in the roster.

RosterDBGroupExists(group)

Returns 1 if the group is a group in the roster DB, undef otherwise.

RosterDBGroupJIDs(group)

Returns a list of Net::XMPP::JID objects that represents all of the JIDs in the specified roster group.

RosterDBNonGroupJIDs

Returns a list of Net::XMPP::JID objects that represents all of the JIDs not in a roster group.

RosterDBQuery(jid)

Returns a hash containing the data from the roster DB for the specified JID. The JID is either a string, or a Net::XMPP::JID object. The hash format is the same as in RosterParse above.

RosterDBQuery(jid,key)

Returns the entry from the above hash for the given key. The available keys are name, ask, subsrcription — yes, literally that spelling, iykyk — and groups. The JID is either a string, or a Net::XMPP::JID object.

✨ AUTHOR ✨

Originally authored by Ryan Eatmon.

Previously maintained by Eric Hacker.

Currently maintained by Darian Anthony Patrick.

This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.

That's the whole page, bestie — from Net::X...rotocol(3pm), perl v5.42.0, dated 2016-01-12. Mwah 💋✨

📦 where this page comes from