On Apache
Under GNU General Public License
2025-11-21 17:01 @216.73.216.130 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Net::XMPP::Protocol(3pm) User Contributed Perl Documentation Net::XMPP::Protocol(3pm)
NAME
Net::XMPP::Protocol - XMPP Protocol Module
SYNOPSIS
Net::XMPP::Protocol is a module that provides a developer easy access to the XMPP Instant
Messaging protocol. It provides high level functions to the Net::XMPP Client object.
These functions are inherited by that modules.
DESCRIPTION
Protocol.pm seeks to provide enough high level APIs and automation of the low level APIs
that writing a XMPP Client in Perl is trivial. For those that wish to work with the low
level you can do that too, but those functions are covered in the documentation for each
module.
Net::XMPP::Protocol provides functions to login, 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.
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 let you specify how the function should
behave:
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.
nonblock
send the packet with an ID, but then return that id and control 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
send the packet with an ID, but do NOT register it with Net::XMPP, 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.
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 AT 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 AT jabber.org");
$Con->Subscription(type=>"unsubscribe",
to=>"bob AT jabber.org");
$Con->Subscription(type=>"subscribed",
to=>"bob AT jabber.org");
$Con->Subscription(type=>"unsubscribed",
to=>"bob AT 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
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 AT 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 AT 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.
SetErrorCode
SetErrorCode(string)
set a useful error message before you return an undef to the caller.
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 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.
The next argument depends on which callback you are 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.
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.
"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:
the session ID, and the
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.
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.
"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.
"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.
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()
returns a Net::XMPP::Roster object. This will automatically intercept all of the
roster and presence packets sent from the server and give you an accurate Roster. For
more information please read the man page for Net::XMPP::Roster.
RosterParse
RosterParse(IQ object)
returns a hash that contains the roster parsed into the following data structure:
$roster{'bob AT jabber.org'}->{name}
- Name you stored in the roster
$roster{'bob AT jabber.org'}->{subscription}
- Subscription status
(to, from, both, none)
$roster{'bob AT jabber.org'}->{ask}
- The ask status from this user
(subscribe, unsubscribe)
$roster{'bob AT jabber.org'}->{groups}
- Array of groups that
bob AT jabber.org is in
RosterGet
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
RosterRequest()
sends an empty Net::XMPP::IQ::Roster tag to the server so the server will send the
Roster to the client.
RosterAdd
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
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
RosterDB()
Tell 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
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
RosterDBAdd(jid,hash)
Add 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 has returned by RosterParse above,
and is the actual hash, not a reference.
RosterDBRemove
RosterDBRemove(jid)
Remove a JID from the roster DB. The JID is either a string, or a Net::XMPP::JID
object.
RosterDBClear
Remove all JIDs from the roster DB.
RosterDBExists
RosterDBExists(jid)
return 1 if the JID exists in the roster DB, undef otherwise. The JID is either a
string, or a Net::XMPP::JID object.
RosterDBJIDs
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
RosterDBGroupExists(group)
return 1 if the group is a group in the roster DB, undef otherwise.
RosterDBGroupJIDs
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
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 the same as in
RosterParse above.
RosterDBQuery
RosterDBQuery(jid,key)
returns the entry from the above hash for the given key. The available keys are:
name, ask, subsrcription 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.
COPYRIGHT
This module is free software, you can redistribute it and/or modify it under the LGPL 2.1.
perl v5.32.0 2021-01-01 Net::XMPP::Protocol(3pm)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2025-11-21 17:01 @216.73.216.130 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)