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
10 access to the XMPP Instant Messaging protocol. It provides high
11 level 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 - send the packet with an ID, and then block until an answer
35 comes back. You can optionally specify a timeout so that
36 you do not block forever.
37 nonblock - send the packet with an ID, but then return that id and
39 control to the master program. Net::XMPP is still
40 tracking this packet, so you must use the CheckID function
41 to tell when it comes in. (This might not be very
42 useful...)
43 passthru - send the packet with an ID, but do NOT register it with
45 Net::XMPP, then return the ID. This is useful when
46 combined with the XPath function because you can register
47 a one shot function tied to the id you get back.
48 Basic Functions
50 use Net::XMPP qw( Client );
51 $Con = new Net::XMPP::Client(); # From
52 $status = $Con->Connect(hostname=>"jabber.org"); # Net::XMPP::Client
53 $Con->SetCallBacks(send=>\&sendCallBack,
55 receive=>\&receiveCallBack,
56 message=>\&messageCallBack,
57 iq=>\&handleTheIQTag);
58 $Con->SetMessageCallBacks(normal=>\&messageNormalCB,
60 chat=>\&messageChatCB);
61 $Con->SetPresenceCallBacks(available=>\&presenceAvailableCB,
63 unavailable=>\&presenceUnavailableCB);
64 $Con->SetIQCallBacks("custom-namespace"=>
66 {
67 get=>\&iqCustomGetCB,
68 set=>\&iqCustomSetCB,
69 result=>\&iqCustomResultCB,
70 },
71 etc...
72 );
73 $Con->SetXPathCallBacks("/message[@type='chat']"=>&messageChatCB,
75 "/message[@type='chat']"=>&otherMessageChatCB,
76 ...
77 );
78 $Con->RemoveXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
80 $Con->SetDirectXPathCallBacks("/anything"=>&anythingCB,
82 "/anotherthing[@foo='bar']"=>&anotherthingFooBarCB,
83 ...
84 );
85 $Con->RemoveDirectXPathCallBacks("/message[@type='chat']"=>&otherMessageChatCB);
87 $error = $Con->GetErrorCode();
89 $Con->SetErrorCode("Timeout limit reached");
90 $status = $Con->Process();
92 $status = $Con->Process(5);
93 $Con->Send($object);
95 $Con->Send("<tag>XML</tag>");
96 $Con->Send($object,1);
98 $Con->Send("<tag>XML</tag>",1);
99 $Con->Disconnect();
101 ID Functions
103 $id = $Con->SendWithID($sendObj);
104 $id = $Con->SendWithID("<tag>XML</tag>");
105 $receiveObj = $Con->SendAndReceiveWithID($sendObj);
106 $receiveObj = $Con->SendAndReceiveWithID($sendObj,
107 10);
108 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
109 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
110 5);
111 $yesno = $Con->ReceivedID($id);
112 $receiveObj = $Con->GetID($id);
113 $receiveObj = $Con->WaitForID($id);
114 $receiveObj = $Con->WaitForID($id,
115 20);
116 Namespace Functions
118 $Con->AddNamespace(ns=>"foo:bar",
119 tag=>"myfoo",
120 xpath=>{Foo=>{ path=> "foo/text()" },
121 Bar=>{ path=> "bar/text()" },
122 FooBar=>{ type=> "master" },
123 }
124 );
125 Message Functions
127 $Con->MessageSend(to=>"bob@jabber.org",
128 subject=>"Lunch",
129 body=>"Let's go grab some...\n",
130 thread=>"ABC123",
131 priority=>10);
132 Presence Functions
134 $Con->PresenceSend();
135 $Con->PresenceSend(type=>"unavailable");
136 $Con->PresenceSend(show=>"away");
137 $Con->PresenceSend(signature=>...signature...);
138 Subscription Functions
140 $Con->Subscription(type=>"subscribe",
141 to=>"bob@jabber.org");
142 $Con->Subscription(type=>"unsubscribe",
144 to=>"bob@jabber.org");
145 $Con->Subscription(type=>"subscribed",
147 to=>"bob@jabber.org");
148 $Con->Subscription(type=>"unsubscribed",
150 to=>"bob@jabber.org");
151 Presence DB Functions
153 $Con->PresenceDB();
154 $Con->PresenceDBParse(Net::XMPP::Presence);
156 $Con->PresenceDBDelete("bob\@jabber.org");
158 $Con->PresenceDBDelete(Net::XMPP::JID);
159 $Con->PresenceDBClear();
161 $presence = $Con->PresenceDBQuery("bob\@jabber.org");
163 $presence = $Con->PresenceDBQuery(Net::XMPP::JID);
164 @resources = $Con->PresenceDBResources("bob\@jabber.org");
166 @resources = $Con->PresenceDBResources(Net::XMPP::JID);
167 IQ Functions
169 Auth Functions
170 @result = $Con->AuthSend();
171 @result = $Con->AuthSend(username=>"bob",
172 password=>"bobrulez",
173 resource=>"Bob");
174 Register Functions
176 %hash = $Con->RegisterRequest();
177 %hash = $Con->RegisterRequest(to=>"transport.jabber.org");
178 %hash = $Con->RegisterRequest(to=>"transport.jabber.org",
179 timeout=>10);
180 @result = $Con->RegisterSend(to=>"somewhere",
182 username=>"newuser",
183 resource=>"New User",
184 password=>"imanewbie",
185 email=>"newguy@new.com",
186 key=>"some key");
187 Roster Functions
189 $Roster = $Con->Roster();
190 %roster = $Con->RosterParse($iq);
192 %roster = $Con->RosterGet();
193 $Con->RosterRequest();
194 $Con->RosterAdd(jid=>"bob\@jabber.org",
195 name=>"Bob");
196 $Con->RosterRemove(jid=>"bob@jabber.org");
197 Roster DB Functions
199 $Con->RosterDB();
200 $Con->RosterDBParse(Net::XMPP::IQ);
202 $Con->RosterDBAdd("bob\@jabber.org",
204 name=>"Bob",
205 groups=>["foo"]
206 );
207 $Con->RosterDBRemove("bob\@jabber.org");
209 $Con->RosterDBRemove(Net::XMPP::JID);
210 $Con->RosterDBClear();
212 if ($Con->RosterDBExists("bob\@jabber.org")) { ...
214 if ($Con->RosterDBExists(Net::XMPP::JID)) { ...
215 @jids = $Con->RosterDBJIDs();
217 if ($Con->RosterDBGroupExists("foo")) { ...
219 @groups = $Con->RosterDBGroups();
221 @jids = $Con->RosterDBGroupJIDs("foo");
223 @jids = $Con->RosterDBNonGroupJIDs();
225 %hash = $Con->RosterDBQuery("bob\@jabber.org");
227 %hash = $Con->RosterDBQuery(Net::XMPP::JID);
228 $value = $Con->RosterDBQuery("bob\@jabber.org","name");
230 $value = $Con->RosterDBQuery(Net::XMPP::JID,"groups");
231
233 Basic Functions
234 GetErrorCode() - returns a string that will hopefully contain some
235 useful information about why a function returned
236 an undef to you.
237 SetErrorCode(string) - set a useful error message before you return
239 an undef to the caller.
240 SetCallBacks(message=>function, - sets the callback functions for
242 presence=>function, the top level tags listed. The
243 iq=>function, available tags to look for are
244 send=>function, <message/>, <presence/>, and
245 receive=>function, <iq/>. If a packet is received
246 update=>function) with an ID which is found in the
247 registerd ID list (see RegisterID
248 below) then it is not sent to
249 these functions, instead it
250 is inserted into a LIST and can
251 be retrieved by some functions
252 we will mention later.
253 send and receive are used to
255 log what XML is sent and received.
256 update is used as way to update
257 your program while waiting for
258 a packet with an ID to be
259 returned (useful for GUI apps).
260 A major change that came with
262 the last release is that the
263 session id is passed to the
264 callback as the first argument.
265 This was done to facilitate
266 the Server module.
267 The next argument depends on
269 which callback you are talking
270 about. message, presence, and iq
271 all get passed in Net::XMPP
272 objects that match those types.
273 send and receive get passed in
274 strings. update gets passed
275 nothing, not even the session id.
276 If you set the function to undef,
278 then the callback is removed from
279 the list.
280 SetPresenceCallBacks(type=>function - sets the callback functions for
282 etc...) the specified presence type.
283 The function takes types as the
284 main key, and lets you specify
285 a function for each type of
286 packet you can get.
287 "available"
288 "unavailable"
289 "subscribe"
290 "unsubscribe"
291 "subscribed"
292 "unsubscribed"
293 "probe"
294 "error"
295 When it gets a <presence/>
296 packet it checks the type=''
297 for a defined callback. If
298 there is one then it calls the
299 function with two arguments:
300 the session ID, and the
301 Net::XMPP::Presence object.
302 If you set the function to
304 undef, then the callback is
305 removed from the list.
306 NOTE: If you use this, which is a cleaner method,
308 then you must *NOT* specify a callback for
309 presence in the SetCallBacks function.
310 Net::XMPP defines a few default
312 callbacks for various types:
313 "subscribe" -
315 replies with subscribed
316 "unsubscribe" -
318 replies with unsubscribed
319 "subscribed" -
321 replies with subscribed
322 "unsubscribed" -
324 replies with unsubscribed
325 SetMessageCallBacks(type=>function, - sets the callback functions for
328 etc...) the specified message type. The
329 function takes types as the
330 main key, and lets you specify
331 a function for each type of
332 packet you can get.
333 "normal"
334 "chat"
335 "groupchat"
336 "headline"
337 "error"
338 When it gets a <message/> packet
339 it checks the type='' for a
340 defined callback. If there is
341 one then it calls the function
342 with two arguments:
343 the session ID, and the
344 Net::XMPP::Message object.
345 If you set the function to
347 undef, then the callback is
348 removed from the list.
349 NOTE: If you use this, which is a cleaner method,
351 then you must *NOT* specify a callback for
352 message in the SetCallBacks function.
353 SetIQCallBacks(namespace=>{ - sets the callback functions for
356 get=>function, the specified namespace. The
357 set=>function, function takes namespaces as the
358 result=>function main key, and lets you specify a
359 }, function for each type of packet
360 etc...) you can get.
361 "get"
362 "set"
363 "result"
364 When it gets an <iq/> packet it
365 checks the type='' and the
366 xmlns='' for a defined callback.
367 If there is one then it calls
368 the function with two arguments:
369 the session ID, and the
370 Net::XMPP::xxxx object.
371 If you set the function to undef,
373 then the callback is removed from
374 the list.
375 NOTE: If you use this, which is a cleaner method,
377 then you must *NOT* specify a callback for
378 iq in the SetCallBacks function.
379 SetXPathCallBacks(xpath=>function, - registers a callback function
381 etc...) for each xpath specified. If
382 Net::XMPP matches the xpath,
383 then it calls the function with
384 two arguments:
385 the session ID, and the
386 Net::XMPP::Message object.
387 Xpaths are rooted at each
389 packet:
390 /message[@type="chat"]
391 /iq/*[xmlns="jabber:iq:roster"][1]
392 ...
393 RemoveXPathCallBacks(xpath=>function, - unregisters a callback
395 etc...) function for each xpath
396 specified.
397 SetDirectXPathCallBacks(xpath=>function, - registers a callback function
399 etc...) for each xpath specified. If
400 Net::XMPP matches the xpath,
401 then it calls the function with
402 two arguments:
403 the session ID, and the
404 XML::Stream::Node object.
405 Xpaths are rooted at each
407 packet:
408 /anything
409 /anotherthing/foo/[1]
410 ...
411 The big difference between this
413 and regular XPathCallBacks is
414 the fact that this passes in
415 the XML directly and not a
416 Net::XMPP based object.
417 RemoveDirectXPathCallBacks(xpath=>function, - unregisters a callback
419 etc...) function for each xpath
420 specified.
421 Process(integer) - takes the timeout period as an argument. If no
423 timeout is listed then the function blocks until
424 a packet is received. Otherwise it waits that
425 number of seconds and then exits so your program
426 can continue doing useful things. NOTE: This is
427 important for GUIs. You need to leave time to
428 process GUI commands even if you are waiting for
429 packets. The following are the possible return
430 values, and what they mean:
431 1 - Status ok, data received.
433 0 - Status ok, no data received.
434 undef - Status not ok, stop processing.
435 IMPORTANT: You need to check the output of every
437 Process. If you get an undef then the connection
438 died and you should behave accordingly.
439 Send(object, - takes either a Net::XMPP::xxxxx object or
441 ignoreActivity) an XML string as an argument and sends it to
442 Send(string, the server. If you set ignoreActivty to 1,
443 ignoreActivity) then the XML::Stream module will not record
444 this packet as couting towards user activity.
445 =head2 ID Functions
446 SendWithID(object) - takes either a Net::XMPP::xxxxx object or an
448 SendWithID(string) XML string as an argument, adds the next
449 available ID number and sends that packet to
450 the server. Returns the ID number assigned.
451 SendAndReceiveWithID(object, - uses SendWithID and WaitForID to
453 timeout) provide a complete way to send and
454 SendAndReceiveWithID(string, receive packets with IDs. Can take
455 timeout) either a Net::XMPP::xxxxx object
456 or an XML string. Returns the
457 proper Net::XMPP::xxxxx object
458 based on the type of packet
459 received. The timeout is passed
460 on to WaitForID, see that function
461 for how the timeout works.
462 ReceivedID(integer) - returns 1 if a packet has been received with
464 specified ID, 0 otherwise.
465 GetID(integer) - returns the proper Net::XMPP::xxxxx object based
467 on the type of packet received with the specified
468 ID. If the ID has been received the GetID returns
469 0.
470 WaitForID(integer, - blocks until a packet with the ID is received.
472 timeout) Returns the proper Net::XMPP::xxxxx object
473 based on the type of packet received. If the
474 timeout limit is reached then if the packet
475 does come in, it will be discarded.
476 NOTE: Only <iq/> officially support ids, so sending a <message/>, or
479 <presence/> with an id is a risk. The server will ignore the
480 id tag and pass it through, so both clients must support the
481 id tag for these functions to be useful.
482 Namespace Functions
484 AddNamespace(ns=>string, - This function is very complex.
485 tag=>string, It is a little too complex to
486 xpath=>hash) discuss within the confines of
487 this small paragraph. Please
488 refer to the man page for
489 Net::XMPP::Namespaces for the
490 full documentation on this
491 subject.
492 Message Functions
494 MessageSend(hash) - takes the hash and passes it to SetMessage in
495 Net::XMPP::Message (refer there for valid
496 settings). Then it sends the message to the
497 server.
498 Presence Functions
500 PresenceSend() - no arguments will send an empty
501 PresenceSend(hash, Presence to the server to tell it
502 signature=>string) that you are available. If you
503 provide a hash, then it will pass
504 that hash to the SetPresence()
505 function as defined in the
506 Net::XMPP::Presence module.
507 Optionally, you can specify a
508 signature and a jabber:x:signed
509 will be placed in the <presence/>.
510 Subscription Functions
512 Subscription(hash) - taks the hash and passes it to SetPresence in
513 Net::XMPP::Presence (refer there for valid
514 settings). Then it sends the subscription to
515 server.
516 The valid types of subscription are:
518 subscribe - subscribe to JID's presence
520 unsubscribe - unsubscribe from JID's presence
521 subscribed - response to a subscribe
522 unsubscribed - response to an unsubscribe
523 Presence DB Functions
525 PresenceDB() - Tell the object to initialize the callbacks to
526 automatically populate the Presence DB.
527 PresenceDBParse(Net::XMPP::Presence) - for every presence that you
529 receive pass the Presence
530 object to the DB so that
531 it can track the resources
532 and priorities for you.
533 Returns either the presence
534 passed in, if it not able
535 to parsed for the DB, or the
536 current presence as found by
537 the PresenceDBQuery
538 function.
539 PresenceDBDelete(string|Net::XMPP::JID) - delete thes JID entry
541 from the DB.
542 PresenceDBClear() - delete all entries in the database.
544 PresenceDBQuery(string|Net::XMPP::JID) - returns the NX::Presence
546 that was last received for
547 the highest priority of
548 this JID. You can pass
549 it a string or a NX::JID
550 object.
551 PresenceDBResources(string|Net::XMPP::JID) - returns an array of
553 resources in order
554 from highest priority
555 to lowest.
556 IQ Functions
558 Auth Functions
559 AuthSend(username=>string, - takes all of the information and
560 password=>string, builds a Net::XMPP::IQ::Auth packet.
561 resource=>string) It then sends that packet to the
562 server with an ID and waits for that
563 ID to return. Then it looks in
564 resulting packet and determines if
565 authentication was successful for not.
566 The array returned from AuthSend looks
567 like this:
568 [ type , message ]
569 If type is "ok" then authentication
570 was successful, otherwise message
571 contains a little more detail about the
572 error.
573 IQ::Register Functions
575 RegisterRequest(to=>string, - send an <iq/> request to the specified
576 timeout=>int) server/transport, if not specified it
577 RegisterRequest() sends to the current active server.
578 The function returns a hash that
579 contains the required fields. Here
580 is an example of the hash:
581 $hash{fields} - The raw fields from
583 the iq:register.
584 To be used if there
585 is no x:data in the
586 packet.
587 $hash{instructions} - How to fill out
588 the form.
589 $hash{form} - The new dynamic forms.
590 In $hash{form}, the fields that are
592 present are the required fields the
593 server needs.
594 RegisterSend(hash) - takes the contents of the hash and passes it
596 to the SetRegister function in the module
597 Net::XMPP::Query jabber:iq:register namespace.
598 This function returns an array that looks like
599 this:
600 [ type , message ]
602 If type is "ok" then registration was
604 successful, otherwise message contains a
605 little more detail about the error.
606 Roster Functions
608 Roster() - returns a Net::XMPP::Roster object. This will automatically
609 intercept all of the roster and presence packets sent from
610 the server and give you an accurate Roster. For more
611 information please read the man page for Net::XMPP::Roster.
612 RosterParse(IQ object) - returns a hash that contains the roster
614 parsed into the following data structure:
615 $roster{'bob@jabber.org'}->{name}
617 - Name you stored in the roster
618 $roster{'bob@jabber.org'}->{subscription}
620 - Subscription status
621 (to, from, both, none)
622 $roster{'bob@jabber.org'}->{ask}
624 - The ask status from this user
625 (subscribe, unsubscribe)
626 $roster{'bob@jabber.org'}->{groups}
628 - Array of groups that
629 bob@jabber.org is in
630 RosterGet() - sends an empty Net::XMPP::IQ::Roster tag to the
632 server so the server will send the Roster to the
633 client. Returns the above hash from RosterParse.
634 RosterRequest() - sends an empty Net::XMPP::IQ::Roster tag to the
636 server so the server will send the Roster to the
637 client.
638 RosterAdd(hash) - sends a packet asking that the jid be
640 added to the roster. The hash format
641 is defined in the SetItem function
642 in the Net::XMPP::Query jabber:iq:roster
643 namespace.
644 RosterRemove(hash) - sends a packet asking that the jid be
646 removed from the roster. The hash
647 format is defined in the SetItem function
648 in the Net::XMPP::Query jabber:iq:roster
649 namespace.
650 Roster DB Functions
652 RosterDB() - Tell the object to initialize the callbacks to
653 automatically populate the Roster DB. If you do this,
654 then make sure that you call RosterRequest() instead of
655 RosterGet() so that the callbacks can catch it and
656 parse it.
657 RosterDBParse(IQ object) - If you want to manually control the
659 database, then you can pass in all iq
660 packets with jabber:iq:roster queries to
661 this function.
662 RosterDBAdd(jid,hash) - Add a new JID into the roster DB. The JID
664 is either a string, or a Net::XMPP::JID
665 object. The hash must be the same format as
666 the has returned by RosterParse above, and
667 is the actual hash, not a reference.
668 RosterDBRemove(jid) - Remove a JID from the roster DB. The JID is
670 either a string, or a Net::XMPP::JID object.
671 RosterDBClear() - Remove all JIDs from the roster DB.
673 RosterDBExists(jid) - return 1 if the JID exists in the roster DB,
675 undef otherwise. The JID is either a string,
676 or a Net::XMPP::JID object.
677 RosterDBJIDs() - returns a list of Net::XMPP::JID objects that
679 represents all of the JIDs in the DB.
680 RosterDBGroups() - returns the complete list of roster groups in the
682 roster.
683 RosterDBGroupExists(group) - return 1 if the group is a group in the
685 roster DB, undef otherwise.
686 RosterDBGroupJIDs(group) - returns a list of Net::XMPP::JID objects
688 that represents all of the JIDs in the
689 specified roster group.
690 RosterDBNonGroupJIDs() - returns a list of Net::XMPP::JID objects
692 that represents all of the JIDs not in a
693 roster group.
694 RosterDBQuery(jid) - returns a hash containing the data from the
696 roster DB for the specified JID. The JID is
697 either a string, or a Net::XMPP::JID object.
698 The hash format the same as in RosterParse
699 above.
700 RosterDBQuery(jid,key) - returns the entry from the above hash for
702 the given key. The available keys are:
703 name, ask, subsrcription and groups
704 The JID is either a string, or a
705 Net::XMPP::JID object.
706
708 Ryan Eatmon
709
711 This module is free software, you can redistribute it and/or modify it
712 under the LGPL.
713perl v5.12.0 2010-05-04 Net::XMPP::Protocol(3)