1Net::XMPP::Protocol(3)User Contributed Perl DocumentationNet::XMPP::Protocol(3)
2
6 Net::XMPP::Protocol - XMPP Protocol Module
7
9 Net::XMPP::Protocol is a module that provides a developer easy access
10 to the XMPP Instant Messaging protocol. It provides high level
11 functions to the Net::XMPP Client object. These functions are
12 inherited by that modules.
13
15 Protocol.pm seeks to provide enough high level APIs and automation of
16 the low level APIs that writing a XMPP Client in Perl is trivial. For
17 those that wish to work with the low level you can do that too, but
18 those functions are covered in the documentation for each module.
19 Net::XMPP::Protocol provides functions to login, send and receive
21 messages, set personal information, create a new user account, manage
22 the roster, and disconnect. You can use all or none of the functions,
23 there is no requirement.
24 For more information on how the details for how Net::XMPP is written
26 please see the help for Net::XMPP itself.
27 For more information on writing a Client see Net::XMPP::Client.
29 Modes
31 Several of the functions take a mode argument that let you specify how
32 the function should behave:
33 block
35 send the packet with an ID, and then block until an answer comes
36 back. You can optionally specify a timeout so that you do not
37 block forever.
38 nonblock
40 send the packet with an ID, but then return that id and control to
41 the master program. Net::XMPP is still tracking this packet, so
42 you must use the CheckID function to tell when it comes in. (This
43 might not be very useful...)
44 passthru
46 send the packet with an ID, but do NOT register it with Net::XMPP,
47 then return the ID. This is useful when combined with the XPath
48 function because you can register a one shot function tied to the
49 id you get back.
50 Basic Functions
52 use Net::XMPP qw( Client );
53 $Con = Net::XMPP::Client->new(); # From
54 $status = $Con->Connect(hostname=>"jabber.org"); # Net::XMPP::Client
55 $Con->SetCallBacks(send=>\&sendCallBack,
57 receive=>\&receiveCallBack,
58 message=>\&messageCallBack,
59 iq=>\&handleTheIQTag);
60 $Con->SetMessageCallBacks(normal=>\&messageNormalCB,
62 chat=>\&messageChatCB);
63 $Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
65 unavailable=>\&presenceUnavailableCB);
66 $Con->SetIQCallBacks("custom-namespace"=>
68 {
69 get=>\&iqCustomGetCB,
70 set=>\&iqCustomSetCB,
71 result=>\&iqCustomResultCB,
72 },
73 etc...
74 );
75 $Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
77 "/message[@type='chat']"=>&otherMessageChatCB,
78 ...
79 );
80 $Con->RemoveXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
82 $Con->SetDirectXPathCallBacks("/anything"=>&anythingCB,
84 "/anotherthing[@foo='bar']"=>&anotherthingFooBarCB,
85 ...
86 );
87 $Con->RemoveDirectXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
89 $error = $Con->GetErrorCode();
91 $Con->SetErrorCode("Timeout limit reached");
92 $status = $Con->Process();
94 $status = $Con->Process(5);
95 $Con->Send($object);
97 $Con->Send("<tag>XML</tag>");
98 $Con->Send($object,1);
100 $Con->Send("<tag>XML</tag>",1);
101 $Con->Disconnect();
103 ID Functions
105 $id = $Con->SendWithID($sendObj);
106 $id = $Con->SendWithID("<tag>XML</tag>");
107 $receiveObj = $Con->SendAndReceiveWithID($sendObj);
108 $receiveObj = $Con->SendAndReceiveWithID($sendObj,
109 10);
110 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
111 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
112 5);
113 $yesno = $Con->ReceivedID($id);
114 $receiveObj = $Con->GetID($id);
115 $receiveObj = $Con->WaitForID($id);
116 $receiveObj = $Con->WaitForID($id,
117 20);
118 Namespace Functions
120 $Con->AddNamespace(ns=>"foo:bar",
121 tag=>"myfoo",
122 xpath=>{Foo=>{ path=> "foo/text()" },
123 Bar=>{ path=> "bar/text()" },
124 FooBar=>{ type=> "master" },
125 }
126 );
127 Message Functions
129 $Con->MessageSend(to=>"bob@jabber.org",
130 subject=>"Lunch",
131 body=>"Let's go grab some...\n",
132 thread=>"ABC123",
133 priority=>10);
134 Presence Functions
136 $Con->PresenceSend();
137 $Con->PresenceSend(type=>"unavailable");
138 $Con->PresenceSend(show=>"away");
139 $Con->PresenceSend(signature=>...signature...);
140 Subscription Functions
142 $Con->Subscription(type=>"subscribe",
143 to=>"bob@jabber.org");
144 $Con->Subscription(type=>"unsubscribe",
146 to=>"bob@jabber.org");
147 $Con->Subscription(type=>"subscribed",
149 to=>"bob@jabber.org");
150 $Con->Subscription(type=>"unsubscribed",
152 to=>"bob@jabber.org");
153 Presence DB Functions
155 $Con->PresenceDB();
156 $Con->PresenceDBParse(Net::XMPP::Presence);
158 $Con->PresenceDBDelete("bob\@jabber.org");
160 $Con->PresenceDBDelete(Net::XMPP::JID);
161 $Con->PresenceDBClear();
163 $presence = $Con->PresenceDBQuery("bob\@jabber.org");
165 $presence = $Con->PresenceDBQuery(Net::XMPP::JID);
166 @resources = $Con->PresenceDBResources("bob\@jabber.org");
168 @resources = $Con->PresenceDBResources(Net::XMPP::JID);
169 IQ Functions
171 Auth Functions
172 @result = $Con->AuthSend();
173 @result = $Con->AuthSend(username=>"bob",
174 password=>"bobrulez",
175 resource=>"Bob");
176 Register Functions
178 %hash = $Con->RegisterRequest();
179 %hash = $Con->RegisterRequest(to=>"transport.jabber.org");
180 %hash = $Con->RegisterRequest(to=>"transport.jabber.org",
181 timeout=>10);
182 @result = $Con->RegisterSend(to=>"somewhere",
184 username=>"newuser",
185 resource=>"New User",
186 password=>"imanewbie",
187 email=>"newguy@new.com",
188 key=>"some key");
189 Roster Functions
191 $Roster = $Con->Roster();
192 %roster = $Con->RosterParse($iq);
194 %roster = $Con->RosterGet();
195 $Con->RosterRequest();
196 $Con->RosterAdd(jid=>"bob\@jabber.org",
197 name=>"Bob");
198 $Con->RosterRemove(jid=>"bob@jabber.org");
199 Roster DB Functions
201 $Con->RosterDB();
202 $Con->RosterDBParse(Net::XMPP::IQ);
204 $Con->RosterDBAdd("bob\@jabber.org",
206 name=>"Bob",
207 groups=>["foo"]
208 );
209 $Con->RosterDBRemove("bob\@jabber.org");
211 $Con->RosterDBRemove(Net::XMPP::JID);
212 $Con->RosterDBClear();
214 if ($Con->RosterDBExists("bob\@jabber.org")) { ...
216 if ($Con->RosterDBExists(Net::XMPP::JID)) { ...
217 @jids = $Con->RosterDBJIDs();
219 if ($Con->RosterDBGroupExists("foo")) { ...
221 @groups = $Con->RosterDBGroups();
223 @jids = $Con->RosterDBGroupJIDs("foo");
225 @jids = $Con->RosterDBNonGroupJIDs();
227 %hash = $Con->RosterDBQuery("bob\@jabber.org");
229 %hash = $Con->RosterDBQuery(Net::XMPP::JID);
230 $value = $Con->RosterDBQuery("bob\@jabber.org","name");
232 $value = $Con->RosterDBQuery(Net::XMPP::JID,"groups");
233
235 Basic Functions
236 GetErrorCode()
237 returns a string that will hopefully contain some useful
238 information about why a function returned an undef to you.
239 SetErrorCode
241 SetErrorCode(string)
242 set a useful error message before you return an undef to the
244 caller.
245 SetCallBacks
247 SetCallBacks(message=>function,
248 presence=>function,
249 iq=>function,
250 send=>function,
251 receive=>function,
252 update=>function)
253 sets the callback functions for the top level tags listed. The
255 available tags to look for are <message/>, <presence/>, and <iq/>.
256 If a packet is received with an ID which is found in the registered
257 ID list (see RegisterID below) then it is not sent to these
258 functions, instead it is inserted into a LIST and can be retrieved
259 by some functions we will mention later.
260 send and receive are used to log what XML is sent and received.
262 update is used as way to update your program while waiting for a
263 packet with an ID to be returned (useful for GUI apps).
264 A major change that came with the last release is that the session
266 id is passed to the callback as the first argument. This was done
267 to facilitate the Server module.
268 The next argument depends on which callback you are talking about.
270 message, presence, and iq all get passed in Net::XMPP objects that
271 match those types. send and receive get passed in strings. update
272 gets passed nothing, not even the session id.
273 If you set the function to undef, then the callback is removed from
275 the list.
276 SetPresenceCallBacks
278 SetPresenceCallBacks(type=>function etc...)
279 sets the callback functions for the specified presence type. The
281 function takes types as the main key, and lets you specify a
282 function for each type of packet you can get.
283 "available"
285 "unavailable"
286 "subscribe"
287 "unsubscribe"
288 "subscribed"
289 "unsubscribed"
290 "probe"
291 "error"
292 When it gets a <presence/> packet it checks the type='' for a
294 defined callback. If there is one then it calls the function with
295 two arguments:
296 the session ID, and the
298 Net::XMPP::Presence object.
299 If you set the function to undef, then the callback is removed from
301 the list.
302 NOTE: If you use this, which is a cleaner method, then you must
304 *NOT* specify a callback for presence in the SetCallBacks function.
305 Net::XMPP defines a few default
307 callbacks for various types:
308 "subscribe" -
310 replies with subscribed
311 "unsubscribe" -
313 replies with unsubscribed
314 "subscribed" -
316 replies with subscribed
317 "unsubscribed" -
319 replies with unsubscribed
320 SetMessageCallBacks
322 SetMessageCallBacks(type=>function, etc...)
323 sets the callback functions for the specified message type. The
325 function takes types as the main key, and lets you specify a
326 function for each type of packet you can get.
327 "normal"
329 "chat"
330 "groupchat"
331 "headline"
332 "error"
333 When it gets a <message/> packet it checks the type='' for a
335 defined callback. If there is one then it calls the function with
336 two arguments:
337 the session ID, and the
339 Net::XMPP::Message object.
340 If you set the function to undef, then the callback is removed from
342 the list.
343 NOTE: If you use this, which is a cleaner method, then you must
345 *NOT* specify a callback for message in the SetCallBacks function.
346 SetIQCallBacks
348 SetIQCallBacks(namespace=>{
349 get=>function,
350 set=>function,
351 result=>function
352 },
353 etc...)
354 sets the callback functions for the specified namespace. The
356 function takes namespaces as the main key, and lets you specify a
357 function for each type of packet you can get.
358 "get"
360 "set"
361 "result"
362 When it gets an <iq/> packet it checks the type='' and the xmlns=''
364 for a defined callback. If there is one then it calls the function
365 with two arguments: the session ID, and the Net::XMPP::xxxx object.
366 If you set the function to undef, then the callback is removed from
368 the list.
369 NOTE: If you use this, which is a cleaner method, then you must
371 *NOT* specify a callback for iq in the SetCallBacks function.
372 SetXPathCallBacks
374 SetXPathCallBacks(xpath=>function, etc...)
375 registers a callback function for each xpath specified. If
377 Net::XMPP matches the xpath, then it calls the function with two
378 arguments:
379 the session ID, and the
381 Net::XMPP::Message object.
382 Xpaths are rooted at each packet:
384 /message[@type="chat"]
386 /iq/*[xmlns="jabber:iq:roster"][1]
387 ...
388 RemoveXPathCallBacks
390 RemoveXPathCallBacks(xpath=>function, etc...)
391 unregisters a callback function for each xpath specified.
393 SetDirectXPathCallBacks
395 SetDirectXPathCallBacks(xpath=>function, etc...)
396 registers a callback function for each xpath specified. If
398 Net::XMPP matches the xpath, then it calls the function with two
399 arguments:
400 the session ID, and the
402 XML::Stream::Node object.
403 Xpaths are rooted at each packet:
405 /anything
407 /anotherthing/foo/[1]
408 ...
409 The big difference between this and regular XPathCallBacks is the
411 fact that this passes in the XML directly and not a Net::XMPP based
412 object.
413 RemoveDirectXPathCallBacks
415 RemoveDirectXPathCallBacks(xpath=>function, etc...)
416 unregisters a callback function for each xpath specified.
418 Process
420 Process(integer)
421 takes the timeout period as an argument. If no
422 timeout is listed then the function blocks until
423 a packet is received. Otherwise it waits that
424 number of seconds and then exits so your program
425 can continue doing useful things. NOTE: This is
426 important for GUIs. You need to leave time to
427 process GUI commands even if you are waiting for
428 packets. The following are the possible return
429 values, and what they mean:
430 1 - Status ok, data received.
432 0 - Status ok, no data received.
433 undef - Status not ok, stop processing.
434 IMPORTANT: You need to check the output of every Process. If you
436 get an undef then the connection died and you should behave
437 accordingly.
438 Send
440 Send(object, ignoreActivity)
441 Send(string, ignoreActivity)
442 takes either a Net::XMPP::xxxxx object or an XML string as an
444 argument and sends it to the server. If you set ignoreActivty to
445 1, then the XML::Stream module will not record this packet as
446 couting towards user activity.
447 ID Functions
449 SendWithID
450 SendWithID(object)
451 SendWithID(string)
452 takes either a Net::XMPP::xxxxx object or an XML string as an
454 argument, adds the next available ID number and sends that packet
455 to the server. Returns the ID number assigned.
456 SendAndReceiveWithID
458 SendAndReceiveWithID(object, timeout)
459 SendAndReceiveWithID(string, timeout)
460 uses SendWithID and WaitForID to provide a complete way to send and
462 receive packets with IDs. Can take either a Net::XMPP::xxxxx
463 object or an XML string. Returns the proper Net::XMPP::xxxxx
464 object based on the type of packet received. The timeout is passed
465 on to WaitForID, see that function for how the timeout works.
466 ReceivedID
468 ReceivedID(integer)
469 returns 1 if a packet has been received with specified ID, 0
471 otherwise.
472 GetID
474 GetID(integer)
475 returns the proper Net::XMPP::xxxxx object based on the type of
477 packet received with the specified ID. If the ID has been received
478 the GetID returns 0.
479 WaitForID
481 WaitForID(integer, timeout)
482 blocks until a packet with the ID is received. Returns the proper
484 Net::XMPP::xxxxx object based on the type of packet received. If
485 the timeout limit is reached then if the packet does come in, it
486 will be discarded.
487 NOTE: Only <iq/> officially support ids, so sending a <message/>,
489 or <presence/> with an id is a risk. The server will ignore the id
490 tag and pass it through, so both clients must support the id tag
491 for these functions to be useful.
492 Namespace Functions
494 AddNamespace
495 AddNamespace(ns=>string,
496 tag=>string,
497 xpath=>hash)
498 This function is very complex. It is a little too complex to
500 discuss within the confines of this small paragraph. Please refer
501 to the man page for Net::XMPP::Namespaces for the full
502 documentation on this subject.
503 Message Functions
505 MessageSend
506 MessageSend(hash)
507 takes the hash and passes it to SetMessage in Net::XMPP::Message
509 (refer there for valid settings). Then it sends the message to the
510 server.
511 Presence Functions
513 PresenceSend
514 PresenceSend()
515 PresenceSend(hash, signature=>string)
516 No arguments will send an empty Presence to the server to tell it
518 that you are available. If you provide a hash, then it will pass
519 that hash to the SetPresence() function as defined in the
520 Net::XMPP::Presence module. Optionally, you can specify a
521 signature and a jabber:x:signed will be placed in the <presence/>.
522 Subscription Functions
524 Subscription
525 Subscription(hash)
526 taks the hash and passes it to SetPresence in Net::XMPP::Presence
528 (refer there for valid settings). Then it sends the subscription
529 to server.
530 The valid types of subscription are:
532 subscribe - subscribe to JID's presence
534 unsubscribe - unsubscribe from JID's presence
535 subscribed - response to a subscribe
536 unsubscribed - response to an unsubscribe
537 Presence DB Functions
539 PresenceDB
540 PresenceDB()
541 Tell the object to initialize the callbacks to automatically
543 populate the Presence DB.
544 PresenceDBParse
546 PresenceDBParse(Net::XMPP::Presence)
547 for every presence that you receive pass the Presence object to the
549 DB so that it can track the resources and priorities for you.
550 Returns either the presence passed in, if it not able to parsed for
551 the DB, or the current presence as found by the PresenceDBQuery
552 function.
553 PresenceDBDelete
555 PresenceDBDelete(string|Net::XMPP::JID)
556 delete thes JID entry from the DB.
558 PresenceDBClear
560 PresenceDBClear()
561 delete all entries in the database.
563 PresenceDBQuery
565 PresenceDBQuery(string|Net::XMPP::JID)
566 returns the NX::Presence that was last received for the highest
568 priority of this JID. You can pass it a string or a NX::JID
569 object.
570 PresenceDBResources
572 PresenceDBResources(string|Net::XMPP::JID)
573 returns an array of resources in order from highest priority to
575 lowest.
576 IQ Functions
578 Auth Functions
579 AuthSend
580 AuthSend(username=>string,
581 password=>string,
582 resource=>string)
583 takes all of the information and builds a Net::XMPP::IQ::Auth
585 packet. It then sends that packet to the server with an ID and
586 waits for that ID to return. Then it looks in resulting packet and
587 determines if authentication was successful for not. The array
588 returned from AuthSend looks like this:
589 [ type , message ]
591 If type is "ok" then authentication was successful, otherwise
593 message contains a little more detail about the error.
594 IQ::Register Functions
596 RegisterRequest
597 RegisterRequest(to=>string, timeout=>int)
598 RegisterRequest()
599 send an <iq/> request to the specified server/transport, if not
601 specified it sends to the current active server. The function
602 returns a hash that contains the required fields. Here is an
603 example of the hash:
604 $hash{fields} - The raw fields from
606 the iq:register.
607 To be used if there
608 is no x:data in the
609 packet.
610 $hash{instructions} - How to fill out
612 the form.
613 $hash{form} - The new dynamic forms.
615 In $hash{form}, the fields that are present are the required fields
617 the server needs.
618 RegisterSend
620 RegisterSend(hash)
621 takes the contents of the hash and passes it to the SetRegister
623 function in the module Net::XMPP::Query jabber:iq:register
624 namespace. This function returns an array that looks like this:
625 [ type , message ]
627 If type is "ok" then registration was successful, otherwise message
629 contains a little more detail about the error.
630 Roster Functions
632 Roster
633 Roster()
634 returns a Net::XMPP::Roster object. This will automatically
636 intercept all of the roster and presence packets sent from the
637 server and give you an accurate Roster. For more information
638 please read the man page for Net::XMPP::Roster.
639 RosterParse
641 RosterParse(IQ object)
642 returns a hash that contains the roster parsed into the following
644 data structure:
645 $roster{'bob@jabber.org'}->{name}
647 - Name you stored in the roster
648 $roster{'bob@jabber.org'}->{subscription}
650 - Subscription status
651 (to, from, both, none)
652 $roster{'bob@jabber.org'}->{ask}
654 - The ask status from this user
655 (subscribe, unsubscribe)
656 $roster{'bob@jabber.org'}->{groups}
658 - Array of groups that
659 bob@jabber.org is in
660 RosterGet
662 RosterGet()
663 sends an empty Net::XMPP::IQ::Roster tag to the server so the
665 server will send the Roster to the client. Returns the above hash
666 from RosterParse.
667 RosterRequest
669 RosterRequest()
670 sends an empty Net::XMPP::IQ::Roster tag to the server so the
672 server will send the Roster to the client.
673 RosterAdd
675 RosterAdd(hash)
676 sends a packet asking that the jid be added to the roster. The
678 hash format is defined in the SetItem function in the
679 Net::XMPP::Query jabber:iq:roster namespace.
680 RosterRemove
682 RosterRemove(hash)
683 sends a packet asking that the jid be removed from the roster. The
685 hash format is defined in the SetItem function in the
686 Net::XMPP::Query jabber:iq:roster namespace.
687 Roster DB Functions
689 RosterDB
690 RosterDB()
691 Tell the object to initialize the callbacks to automatically
693 populate the Roster DB. If you do this, then make sure that you
694 call RosterRequest() instead of RosterGet() so that the callbacks
695 can catch it and parse it.
696 RosterDBParse
698 RosterDBParse(IQ object)
699 If you want to manually control the database, then you can pass in
701 all iq packets with jabber:iq:roster queries to this function.
702 RosterDBAdd
704 RosterDBAdd(jid,hash)
705 Add a new JID into the roster DB. The JID is either a string, or a
707 Net::XMPP::JID object. The hash must be the same format as the has
708 returned by RosterParse above, and is the actual hash, not a
709 reference.
710 RosterDBRemove
712 RosterDBRemove(jid)
713 Remove a JID from the roster DB. The JID is either a string, or a
715 Net::XMPP::JID object.
716 RosterDBClear
718 Remove all JIDs from the roster DB.
719 RosterDBExists
721 RosterDBExists(jid)
722 return 1 if the JID exists in the roster DB, undef otherwise. The
724 JID is either a string, or a Net::XMPP::JID object.
725 RosterDBJIDs
727 RosterDBJIDs()
728 returns a list of Net::XMPP::JID objects that represents all of the
730 JIDs in the DB.
731 RosterDBGroups
733 returns the complete list of roster groups in the roster.
734 RosterDBGroupExists
736 RosterDBGroupExists(group)
737 return 1 if the group is a group in the roster DB, undef otherwise.
739 RosterDBGroupJIDs
741 RosterDBGroupJIDs(group)
742 returns a list of Net::XMPP::JID objects that represents all of the
744 JIDs in the specified roster group.
745 RosterDBNonGroupJIDs
747 returns a list of Net::XMPP::JID objects that represents all of the
748 JIDs not in a roster group.
749 RosterDBQuery
751 RosterDBQuery(jid)
752 returns a hash containing the data from the roster DB for the
754 specified JID. The JID is either a string, or a Net::XMPP::JID
755 object. The hash format the same as in RosterParse above.
756 RosterDBQuery
758 RosterDBQuery(jid,key)
759 returns the entry from the above hash for the given key. The
761 available keys are:
762 name, ask, subsrcription and groups The JID is either a string,
763 or a Net::XMPP::JID object.
764
766 Originally authored by Ryan Eatmon.
767 Previously maintained by Eric Hacker.
769 Currently maintained by Darian Anthony Patrick.
771
773 This module is free software, you can redistribute it and/or modify it
774 under the LGPL 2.1.
775perl v5.36.0 2023-01-20 Net::XMPP::Protocol(3)