1Net::XMPP::Protocol(3)User Contributed Perl DocumentationNet::XMPP::Protocol(3)
2
3
4

NAME

6       Net::XMPP::Protocol - XMPP Protocol Module
7

SYNOPSIS

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

DESCRIPTION

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
20       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
25       For more information on how the details for how Net::XMPP is written
26       please see the help for Net::XMPP itself.
27
28       For more information on writing a Client see Net::XMPP::Client.
29
30   Modes
31       Several of the functions take a mode argument that let you specify how
32       the function should behave:
33
34       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
39       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
45       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
51   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
56           $Con->SetCallBacks(send=>\&sendCallBack,
57                              receive=>\&receiveCallBack,
58                              message=>\&messageCallBack,
59                              iq=>\&handleTheIQTag);
60
61           $Con->SetMessageCallBacks(normal=>\&messageNormalCB,
62                                     chat=>\&messageChatCB);
63
64           $Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
65                                      unavailable=>\&presenceUnavailableCB);
66
67           $Con->SetIQCallBacks("custom-namespace"=>
68                                                    {
69                                                        get=>\&iqCustomGetCB,
70                                                        set=>\&iqCustomSetCB,
71                                                        result=>\&iqCustomResultCB,
72                                                    },
73                                                    etc...
74                                                   );
75
76           $Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
77                                   "/message[@type='chat']"=>&otherMessageChatCB,
78                                   ...
79                                  );
80
81           $Con->RemoveXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
82
83           $Con->SetDirectXPathCallBacks("/anything"=>&anythingCB,
84                                         "/anotherthing[@foo='bar']"=>&anotherthingFooBarCB,
85                                         ...
86                                        );
87
88           $Con->RemoveDirectXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
89
90           $error = $Con->GetErrorCode();
91           $Con->SetErrorCode("Timeout limit reached");
92
93           $status = $Con->Process();
94           $status = $Con->Process(5);
95
96           $Con->Send($object);
97           $Con->Send("<tag>XML</tag>");
98
99           $Con->Send($object,1);
100           $Con->Send("<tag>XML</tag>",1);
101
102           $Con->Disconnect();
103
104   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
119   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
128   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
135   Presence Functions
136           $Con->PresenceSend();
137           $Con->PresenceSend(type=>"unavailable");
138           $Con->PresenceSend(show=>"away");
139           $Con->PresenceSend(signature=>...signature...);
140
141   Subscription Functions
142           $Con->Subscription(type=>"subscribe",
143                              to=>"bob@jabber.org");
144
145           $Con->Subscription(type=>"unsubscribe",
146                              to=>"bob@jabber.org");
147
148           $Con->Subscription(type=>"subscribed",
149                              to=>"bob@jabber.org");
150
151           $Con->Subscription(type=>"unsubscribed",
152                              to=>"bob@jabber.org");
153
154   Presence DB Functions
155           $Con->PresenceDB();
156
157           $Con->PresenceDBParse(Net::XMPP::Presence);
158
159           $Con->PresenceDBDelete("bob\@jabber.org");
160           $Con->PresenceDBDelete(Net::XMPP::JID);
161
162           $Con->PresenceDBClear();
163
164           $presence  = $Con->PresenceDBQuery("bob\@jabber.org");
165           $presence  = $Con->PresenceDBQuery(Net::XMPP::JID);
166
167           @resources = $Con->PresenceDBResources("bob\@jabber.org");
168           @resources = $Con->PresenceDBResources(Net::XMPP::JID);
169
170   IQ  Functions
171   Auth Functions
172           @result = $Con->AuthSend();
173           @result = $Con->AuthSend(username=>"bob",
174                                    password=>"bobrulez",
175                                    resource=>"Bob");
176
177   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
183           @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
190   Roster Functions
191           $Roster = $Con->Roster();
192
193           %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
200   Roster DB Functions
201           $Con->RosterDB();
202
203           $Con->RosterDBParse(Net::XMPP::IQ);
204
205           $Con->RosterDBAdd("bob\@jabber.org",
206                             name=>"Bob",
207                             groups=>["foo"]
208                            );
209
210           $Con->RosterDBRemove("bob\@jabber.org");
211           $Con->RosterDBRemove(Net::XMPP::JID);
212
213           $Con->RosterDBClear();
214
215           if ($Con->RosterDBExists("bob\@jabber.org")) { ...
216           if ($Con->RosterDBExists(Net::XMPP::JID)) { ...
217
218           @jids = $Con->RosterDBJIDs();
219
220           if ($Con->RosterDBGroupExists("foo")) { ...
221
222           @groups = $Con->RosterDBGroups();
223
224           @jids = $Con->RosterDBGroupJIDs("foo");
225
226           @jids = $Con->RosterDBNonGroupJIDs();
227
228           %hash = $Con->RosterDBQuery("bob\@jabber.org");
229           %hash = $Con->RosterDBQuery(Net::XMPP::JID);
230
231           $value = $Con->RosterDBQuery("bob\@jabber.org","name");
232           $value = $Con->RosterDBQuery(Net::XMPP::JID,"groups");
233

METHODS

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
240       SetErrorCode
241             SetErrorCode(string)
242
243           set a useful error message before you return an undef to the
244           caller.
245
246       SetCallBacks
247             SetCallBacks(message=>function,
248                            presence=>function,
249                            iq=>function,
250                            send=>function,
251                            receive=>function,
252                            update=>function)
253
254           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
261           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
265           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
269           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
274           If you set the function to undef, then the callback is removed from
275           the list.
276
277       SetPresenceCallBacks
278             SetPresenceCallBacks(type=>function etc...)
279
280           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
284             "available"
285             "unavailable"
286             "subscribe"
287             "unsubscribe"
288             "subscribed"
289             "unsubscribed"
290             "probe"
291             "error"
292
293           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
297             the session ID, and the
298             Net::XMPP::Presence object.
299
300           If you set the function to undef, then the callback is removed from
301           the list.
302
303           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
306            Net::XMPP defines a few default
307            callbacks for various types:
308
309            "subscribe" -
310              replies with subscribed
311
312            "unsubscribe" -
313              replies with unsubscribed
314
315            "subscribed" -
316              replies with subscribed
317
318            "unsubscribed" -
319              replies with unsubscribed
320
321       SetMessageCallBacks
322               SetMessageCallBacks(type=>function, etc...)
323
324           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
328            "normal"
329            "chat"
330            "groupchat"
331            "headline"
332            "error"
333
334           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
338             the session ID, and the
339             Net::XMPP::Message object.
340
341           If you set the function to undef, then the callback is removed from
342           the list.
343
344           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
347       SetIQCallBacks
348             SetIQCallBacks(namespace=>{
349                                get=>function,
350                                set=>function,
351                                result=>function
352                              },
353                              etc...)
354
355           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
359             "get"
360             "set"
361             "result"
362
363           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
367           If you set the function to undef, then the callback is removed from
368           the list.
369
370           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
373       SetXPathCallBacks
374             SetXPathCallBacks(xpath=>function, etc...)
375
376           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
380             the session ID, and the
381             Net::XMPP::Message object.
382
383           Xpaths are rooted at each packet:
384
385             /message[@type="chat"]
386             /iq/*[xmlns="jabber:iq:roster"][1]
387             ...
388
389       RemoveXPathCallBacks
390            RemoveXPathCallBacks(xpath=>function, etc...)
391
392           unregisters a callback function for each xpath specified.
393
394       SetDirectXPathCallBacks
395            SetDirectXPathCallBacks(xpath=>function, etc...)
396
397           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
401             the session ID, and the
402             XML::Stream::Node object.
403
404           Xpaths are rooted at each packet:
405
406             /anything
407             /anotherthing/foo/[1]
408             ...
409
410           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
414       RemoveDirectXPathCallBacks
415             RemoveDirectXPathCallBacks(xpath=>function, etc...)
416
417           unregisters a callback function for each xpath specified.
418
419       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
431               1   - Status ok, data received.
432               0   - Status ok, no data received.
433             undef - Status not ok, stop processing.
434
435           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
439       Send
440               Send(object, ignoreActivity)
441               Send(string, ignoreActivity)
442
443           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
448   ID Functions
449       SendWithID
450               SendWithID(object)
451               SendWithID(string)
452
453           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
457       SendAndReceiveWithID
458               SendAndReceiveWithID(object, timeout)
459               SendAndReceiveWithID(string, timeout)
460
461           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
467       ReceivedID
468            ReceivedID(integer)
469
470           returns 1 if a packet has been received with specified ID, 0
471           otherwise.
472
473       GetID
474               GetID(integer)
475
476           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
480       WaitForID
481             WaitForID(integer, timeout)
482
483           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
488           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
493   Namespace Functions
494       AddNamespace
495               AddNamespace(ns=>string,
496                            tag=>string,
497                            xpath=>hash)
498
499           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
504   Message Functions
505       MessageSend
506               MessageSend(hash)
507
508           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
512   Presence Functions
513       PresenceSend
514             PresenceSend()
515             PresenceSend(hash, signature=>string)
516
517           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
523   Subscription Functions
524       Subscription
525            Subscription(hash)
526
527           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
531           The valid types of subscription are:
532
533             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
538   Presence DB Functions
539       PresenceDB
540            PresenceDB()
541
542           Tell the object to initialize the callbacks to automatically
543           populate the Presence DB.
544
545       PresenceDBParse
546             PresenceDBParse(Net::XMPP::Presence)
547
548           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
554       PresenceDBDelete
555             PresenceDBDelete(string|Net::XMPP::JID)
556
557           delete thes JID entry from the DB.
558
559       PresenceDBClear
560            PresenceDBClear()
561
562           delete all entries in the database.
563
564       PresenceDBQuery
565             PresenceDBQuery(string|Net::XMPP::JID)
566
567           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
571       PresenceDBResources
572             PresenceDBResources(string|Net::XMPP::JID)
573
574           returns an array of resources in order from highest priority to
575           lowest.
576
577   IQ Functions
578   Auth Functions
579       AuthSend
580               AuthSend(username=>string,
581                        password=>string,
582                        resource=>string)
583
584           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
590             [ type , message ]
591
592           If type is "ok" then authentication was successful, otherwise
593           message contains a little more detail about the error.
594
595   IQ::Register Functions
596       RegisterRequest
597            RegisterRequest(to=>string,  timeout=>int)
598            RegisterRequest()
599
600           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
605           $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
611           $hash{instructions} - How to fill out
612                                 the form.
613
614           $hash{form}   - The new dynamic forms.
615
616           In $hash{form}, the fields that are present are the required fields
617           the server needs.
618
619       RegisterSend
620             RegisterSend(hash)
621
622           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
626             [ type , message ]
627
628           If type is "ok" then registration was successful, otherwise message
629           contains a little more detail about the error.
630
631   Roster Functions
632       Roster
633               Roster()
634
635           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
640       RosterParse
641               RosterParse(IQ object)
642
643           returns a hash that contains the roster parsed into the following
644           data structure:
645
646             $roster{'bob@jabber.org'}->{name}
647                                 - Name you stored in the roster
648
649             $roster{'bob@jabber.org'}->{subscription}
650                                 - Subscription status
651                                   (to, from, both, none)
652
653             $roster{'bob@jabber.org'}->{ask}
654                                 - The ask status from this user
655                                   (subscribe, unsubscribe)
656
657             $roster{'bob@jabber.org'}->{groups}
658                                 - Array of groups that
659                                   bob@jabber.org is in
660
661       RosterGet
662             RosterGet()
663
664           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
668       RosterRequest
669             RosterRequest()
670
671           sends an empty Net::XMPP::IQ::Roster tag to the server so the
672           server will send the Roster to the client.
673
674       RosterAdd
675               RosterAdd(hash)
676
677           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
681       RosterRemove
682            RosterRemove(hash)
683
684           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
688   Roster DB Functions
689       RosterDB
690               RosterDB()
691
692           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
697       RosterDBParse
698               RosterDBParse(IQ object)
699
700           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
703       RosterDBAdd
704             RosterDBAdd(jid,hash)
705
706           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
711       RosterDBRemove
712             RosterDBRemove(jid)
713
714           Remove a JID from the roster DB. The JID is either a string, or a
715           Net::XMPP::JID object.
716
717       RosterDBClear
718           Remove all JIDs from the roster DB.
719
720       RosterDBExists
721            RosterDBExists(jid)
722
723           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
726       RosterDBJIDs
727             RosterDBJIDs()
728
729           returns a list of Net::XMPP::JID objects that represents all of the
730           JIDs in the DB.
731
732       RosterDBGroups
733           returns the complete list of roster groups in the roster.
734
735       RosterDBGroupExists
736               RosterDBGroupExists(group)
737
738           return 1 if the group is a group in the roster DB, undef otherwise.
739
740       RosterDBGroupJIDs
741               RosterDBGroupJIDs(group)
742
743           returns a list of Net::XMPP::JID objects that represents all of the
744           JIDs in the specified roster group.
745
746       RosterDBNonGroupJIDs
747           returns a list of Net::XMPP::JID objects that represents all of the
748           JIDs not in a roster group.
749
750       RosterDBQuery
751             RosterDBQuery(jid)
752
753           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
757       RosterDBQuery
758             RosterDBQuery(jid,key)
759
760           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

AUTHOR

766       Originally authored by Ryan Eatmon.
767
768       Previously maintained by Eric Hacker.
769
770       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.
775
776
777
778perl v5.34.0                      2022-01-21            Net::XMPP::Protocol(3)
Impressum