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
33 the function should behave:
34 block - send the packet with an ID, and then block until an answer
36 comes back. You can optionally specify a timeout so that
37 you do not block forever.
38 nonblock - send the packet with an ID, but then return that id and
40 control to the master program. Net::XMPP is still
41 tracking this packet, so you must use the CheckID function
42 to tell when it comes in. (This might not be very
43 useful...)
44 passthru - send the packet with an ID, but do NOT register it with
46 Net::XMPP, then return the ID. This is useful when
47 combined with the XPath function because you can register
48 a one shot function tied to the id you get back.
49 Basic Functions
51 use Net::XMPP qw( Client );
53 $Con = new Net::XMPP::Client(); # 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);
107 $id = $Con->SendWithID("<tag>XML</tag>");
108 $receiveObj = $Con->SendAndReceiveWithID($sendObj);
109 $receiveObj = $Con->SendAndReceiveWithID($sendObj,
110 10);
111 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>");
112 $receiveObj = $Con->SendAndReceiveWithID("<tag>XML</tag>",
113 5);
114 $yesno = $Con->ReceivedID($id);
115 $receiveObj = $Con->GetID($id);
116 $receiveObj = $Con->WaitForID($id);
117 $receiveObj = $Con->WaitForID($id,
118 20);
119 Namespace Functions
121 $Con->AddNamespace(ns=>"foo:bar",
123 tag=>"myfoo",
124 xpath=>{Foo=>{ path=> "foo/text()" },
125 Bar=>{ path=> "bar/text()" },
126 FooBar=>{ type=> "master" },
127 }
128 );
129 Message Functions
131 $Con->MessageSend(to=>"bob@jabber.org",
133 subject=>"Lunch",
134 body=>"Let's go grab some...\n",
135 thread=>"ABC123",
136 priority=>10);
137 Presence Functions
139 $Con->PresenceSend();
141 $Con->PresenceSend(type=>"unavailable");
142 $Con->PresenceSend(show=>"away");
143 $Con->PresenceSend(signature=>...signature...);
144 Subscription Functions
146 $Con->Subscription(type=>"subscribe",
148 to=>"bob@jabber.org");
149 $Con->Subscription(type=>"unsubscribe",
151 to=>"bob@jabber.org");
152 $Con->Subscription(type=>"subscribed",
154 to=>"bob@jabber.org");
155 $Con->Subscription(type=>"unsubscribed",
157 to=>"bob@jabber.org");
158 Presence DB Functions
160 $Con->PresenceDB();
162 $Con->PresenceDBParse(Net::XMPP::Presence);
164 $Con->PresenceDBDelete("bob\@jabber.org");
166 $Con->PresenceDBDelete(Net::XMPP::JID);
167 $Con->PresenceDBClear();
169 $presence = $Con->PresenceDBQuery("bob\@jabber.org");
171 $presence = $Con->PresenceDBQuery(Net::XMPP::JID);
172 @resources = $Con->PresenceDBResources("bob\@jabber.org");
174 @resources = $Con->PresenceDBResources(Net::XMPP::JID);
175 IQ Functions
177 Auth Functions
179 @result = $Con->AuthSend();
181 @result = $Con->AuthSend(username=>"bob",
182 password=>"bobrulez",
183 resource=>"Bob");
184 Register Functions
186 %hash = $Con->RegisterRequest();
188 %hash = $Con->RegisterRequest(to=>"transport.jabber.org");
189 %hash = $Con->RegisterRequest(to=>"transport.jabber.org",
190 timeout=>10);
191 @result = $Con->RegisterSend(to=>"somewhere",
193 username=>"newuser",
194 resource=>"New User",
195 password=>"imanewbie",
196 email=>"newguy@new.com",
197 key=>"some key");
198 Roster Functions
200 $Roster = $Con->Roster();
202 %roster = $Con->RosterParse($iq);
204 %roster = $Con->RosterGet();
205 $Con->RosterRequest();
206 $Con->RosterAdd(jid=>"bob\@jabber.org",
207 name=>"Bob");
208 $Con->RosterRemove(jid=>"bob@jabber.org");
209 Roster DB Functions
211 $Con->RosterDB();
213 $Con->RosterDBParse(Net::XMPP::IQ);
215 $Con->RosterDBAdd("bob\@jabber.org",
217 name=>"Bob",
218 groups=>["foo"]
219 );
220 $Con->RosterDBRemove("bob\@jabber.org");
222 $Con->RosterDBRemove(Net::XMPP::JID);
223 $Con->RosterDBClear();
225 if ($Con->RosterDBExists("bob\@jabber.org")) { ...
227 if ($Con->RosterDBExists(Net::XMPP::JID)) { ...
228 @jids = $Con->RosterDBJIDs();
230 if ($Con->RosterDBGroupExists("foo")) { ...
232 @groups = $Con->RosterDBGroups();
234 @jids = $Con->RosterDBGroupJIDs("foo");
236 @jids = $Con->RosterDBNonGroupJIDs();
238 %hash = $Con->RosterDBQuery("bob\@jabber.org");
240 %hash = $Con->RosterDBQuery(Net::XMPP::JID);
241 $value = $Con->RosterDBQuery("bob\@jabber.org","name");
243 $value = $Con->RosterDBQuery(Net::XMPP::JID,"groups");
244
246 Basic Functions
247 GetErrorCode() - returns a string that will hopefully contain some
249 useful information about why a function returned
250 an undef to you.
251 SetErrorCode(string) - set a useful error message before you return
253 an undef to the caller.
254 SetCallBacks(message=>function, - sets the callback functions for
256 presence=>function, the top level tags listed. The
257 iq=>function, available tags to look for are
258 send=>function, <message/>, <presence/>, and
259 receive=>function, <iq/>. If a packet is received
260 update=>function) with an ID which is found in the
261 registerd ID list (see RegisterID
262 below) then it is not sent to
263 these functions, instead it
264 is inserted into a LIST and can
265 be retrieved by some functions
266 we will mention later.
267 send and receive are used to
269 log what XML is sent and received.
270 update is used as way to update
271 your program while waiting for
272 a packet with an ID to be
273 returned (useful for GUI apps).
274 A major change that came with
276 the last release is that the
277 session id is passed to the
278 callback as the first argument.
279 This was done to facilitate
280 the Server module.
281 The next argument depends on
283 which callback you are talking
284 about. message, presence, and iq
285 all get passed in Net::XMPP
286 objects that match those types.
287 send and receive get passed in
288 strings. update gets passed
289 nothing, not even the session id.
290 If you set the function to undef,
292 then the callback is removed from
293 the list.
294 SetPresenceCallBacks(type=>function - sets the callback functions for
296 etc...) the specified presence type.
297 The function takes types as the
298 main key, and lets you specify
299 a function for each type of
300 packet you can get.
301 "available"
302 "unavailable"
303 "subscribe"
304 "unsubscribe"
305 "subscribed"
306 "unsubscribed"
307 "probe"
308 "error"
309 When it gets a <presence/>
310 packet it checks the type=''
311 for a defined callback. If
312 there is one then it calls the
313 function with two arguments:
314 the session ID, and the
315 Net::XMPP::Presence object.
316 If you set the function to
318 undef, then the callback is
319 removed from the list.
320 NOTE: If you use this, which is a cleaner method,
322 then you must *NOT* specify a callback for
323 presence in the SetCallBacks function.
324 Net::XMPP defines a few default
326 callbacks for various types:
327 "subscribe" -
329 replies with subscribed
330 "unsubscribe" -
332 replies with unsubscribed
333 "subscribed" -
335 replies with subscribed
336 "unsubscribed" -
338 replies with unsubscribed
339 SetMessageCallBacks(type=>function, - sets the callback functions for
341 etc...) the specified message type. The
342 function takes types as the
343 main key, and lets you specify
344 a function for each type of
345 packet you can get.
346 "normal"
347 "chat"
348 "groupchat"
349 "headline"
350 "error"
351 When it gets a <message/> packet
352 it checks the type='' for a
353 defined callback. If there is
354 one then it calls the function
355 with two arguments:
356 the session ID, and the
357 Net::XMPP::Message object.
358 If you set the function to
360 undef, then the callback is
361 removed from the list.
362 NOTE: If you use this, which is a cleaner method,
364 then you must *NOT* specify a callback for
365 message in the SetCallBacks function.
366 SetIQCallBacks(namespace=>{ - sets the callback functions for
368 get=>function, the specified namespace. The
369 set=>function, function takes namespaces as the
370 result=>function main key, and lets you specify a
371 }, function for each type of packet
372 etc...) you can get.
373 "get"
374 "set"
375 "result"
376 When it gets an <iq/> packet it
377 checks the type='' and the
378 xmlns='' for a defined callback.
379 If there is one then it calls
380 the function with two arguments:
381 the session ID, and the
382 Net::XMPP::xxxx object.
383 If you set the function to undef,
385 then the callback is removed from
386 the list.
387 NOTE: If you use this, which is a cleaner method,
389 then you must *NOT* specify a callback for
390 iq in the SetCallBacks function.
391 SetXPathCallBacks(xpath=>function, - registers a callback function
393 etc...) for each xpath specified. If
394 Net::XMPP matches the xpath,
395 then it calls the function with
396 two arguments:
397 the session ID, and the
398 Net::XMPP::Message object.
399 Xpaths are rooted at each
401 packet:
402 /message[@type="chat"]
403 /iq/*[xmlns="jabber:iq:roster"][1]
404 ...
405 RemoveXPathCallBacks(xpath=>function, - unregisters a callback
407 etc...) function for each xpath
408 specified.
409 SetDirectXPathCallBacks(xpath=>function, - registers a callback function
411 etc...) for each xpath specified. If
412 Net::XMPP matches the xpath,
413 then it calls the function with
414 two arguments:
415 the session ID, and the
416 XML::Stream::Node object.
417 Xpaths are rooted at each
419 packet:
420 /anything
421 /anotherthing/foo/[1]
422 ...
423 The big difference between this
425 and regular XPathCallBacks is
426 the fact that this passes in
427 the XML directly and not a
428 Net::XMPP based object.
429 RemoveDirectXPathCallBacks(xpath=>function, - unregisters a callback
431 etc...) function for each xpath
432 specified.
433 Process(integer) - takes the timeout period as an argument. If no
435 timeout is listed then the function blocks until
436 a packet is received. Otherwise it waits that
437 number of seconds and then exits so your program
438 can continue doing useful things. NOTE: This is
439 important for GUIs. You need to leave time to
440 process GUI commands even if you are waiting for
441 packets. The following are the possible return
442 values, and what they mean:
443 1 - Status ok, data received.
445 0 - Status ok, no data received.
446 undef - Status not ok, stop processing.
447 IMPORTANT: You need to check the output of every
449 Process. If you get an undef then the connection
450 died and you should behave accordingly.
451 Send(object, - takes either a Net::XMPP::xxxxx object or
453 ignoreActivity) an XML string as an argument and sends it to
454 Send(string, the server. If you set ignoreActivty to 1,
455 ignoreActivity) then the XML::Stream module will not record
456 this packet as couting towards user activity.
457 =head2 ID Functions
458 SendWithID(object) - takes either a Net::XMPP::xxxxx object or an
460 SendWithID(string) XML string as an argument, adds the next
461 available ID number and sends that packet to
462 the server. Returns the ID number assigned.
463 SendAndReceiveWithID(object, - uses SendWithID and WaitForID to
465 timeout) provide a complete way to send and
466 SendAndReceiveWithID(string, receive packets with IDs. Can take
467 timeout) either a Net::XMPP::xxxxx object
468 or an XML string. Returns the
469 proper Net::XMPP::xxxxx object
470 based on the type of packet
471 received. The timeout is passed
472 on to WaitForID, see that function
473 for how the timeout works.
474 ReceivedID(integer) - returns 1 if a packet has been received with
476 specified ID, 0 otherwise.
477 GetID(integer) - returns the proper Net::XMPP::xxxxx object based
479 on the type of packet received with the specified
480 ID. If the ID has been received the GetID returns
481 0.
482 WaitForID(integer, - blocks until a packet with the ID is received.
484 timeout) Returns the proper Net::XMPP::xxxxx object
485 based on the type of packet received. If the
486 timeout limit is reached then if the packet
487 does come in, it will be discarded.
488 NOTE: Only <iq/> officially support ids, so sending a <message/>, or
490 <presence/> with an id is a risk. The server will ignore the
491 id tag and pass it through, so both clients must support the
492 id tag for these functions to be useful.
493 Namespace Functions
495 AddNamespace(ns=>string, - This function is very complex.
497 tag=>string, It is a little too complex to
498 xpath=>hash) discuss within the confines of
499 this small paragraph. Please
500 refer to the man page for
501 Net::XMPP::Namespaces for the
502 full documentation on this
503 subject.
504 Message Functions
506 MessageSend(hash) - takes the hash and passes it to SetMessage in
508 Net::XMPP::Message (refer there for valid
509 settings). Then it sends the message to the
510 server.
511 Presence Functions
513 PresenceSend() - no arguments will send an empty
515 PresenceSend(hash, Presence to the server to tell it
516 signature=>string) that you are available. If you
517 provide a hash, then it will pass
518 that hash to the SetPresence()
519 function as defined in the
520 Net::XMPP::Presence module.
521 Optionally, you can specify a
522 signature and a jabber:x:signed
523 will be placed in the <presence/>.
524 Subscription Functions
526 Subscription(hash) - taks the hash and passes it to SetPresence in
528 Net::XMPP::Presence (refer there for valid
529 settings). Then it sends the subscription to
530 server.
531 The valid types of subscription are:
533 subscribe - subscribe to JID's presence
535 unsubscribe - unsubscribe from JID's presence
536 subscribed - response to a subscribe
537 unsubscribed - response to an unsubscribe
538 Presence DB Functions
540 PresenceDB() - Tell the object to initialize the callbacks to
542 automatically populate the Presence DB.
543 PresenceDBParse(Net::XMPP::Presence) - for every presence that you
545 receive pass the Presence
546 object to the DB so that
547 it can track the resources
548 and priorities for you.
549 Returns either the presence
550 passed in, if it not able
551 to parsed for the DB, or the
552 current presence as found by
553 the PresenceDBQuery
554 function.
555 PresenceDBDelete(string⎪Net::XMPP::JID) - delete thes JID entry
557 from the DB.
558 PresenceDBClear() - delete all entries in the database.
560 PresenceDBQuery(string⎪Net::XMPP::JID) - returns the NX::Presence
562 that was last received for
563 the highest priority of
564 this JID. You can pass
565 it a string or a NX::JID
566 object.
567 PresenceDBResources(string⎪Net::XMPP::JID) - returns an array of
569 resources in order
570 from highest priority
571 to lowest.
572 IQ Functions
574 Auth Functions
576 AuthSend(username=>string, - takes all of the information and
578 password=>string, builds a Net::XMPP::IQ::Auth packet.
579 resource=>string) It then sends that packet to the
580 server with an ID and waits for that
581 ID to return. Then it looks in
582 resulting packet and determines if
583 authentication was successful for not.
584 The array returned from AuthSend looks
585 like this:
586 [ type , message ]
587 If type is "ok" then authentication
588 was successful, otherwise message
589 contains a little more detail about the
590 error.
591 IQ::Register Functions
593 RegisterRequest(to=>string, - send an <iq/> request to the specified
595 timeout=>int) server/transport, if not specified it
596 RegisterRequest() sends to the current active server.
597 The function returns a hash that
598 contains the required fields. Here
599 is an example of the hash:
600 $hash{fields} - The raw fields from
602 the iq:register.
603 To be used if there
604 is no x:data in the
605 packet.
606 $hash{instructions} - How to fill out
607 the form.
608 $hash{form} - The new dynamic forms.
609 In $hash{form}, the fields that are
611 present are the required fields the
612 server needs.
613 RegisterSend(hash) - takes the contents of the hash and passes it
615 to the SetRegister function in the module
616 Net::XMPP::Query jabber:iq:register namespace.
617 This function returns an array that looks like
618 this:
619 [ type , message ]
621 If type is "ok" then registration was
623 successful, otherwise message contains a
624 little more detail about the error.
625 Roster Functions
627 Roster() - returns a Net::XMPP::Roster object. This will automatically
629 intercept all of the roster and presence packets sent from
630 the server and give you an accurate Roster. For more
631 information please read the man page for Net::XMPP::Roster.
632 RosterParse(IQ object) - returns a hash that contains the roster
634 parsed into the following data structure:
635 $roster{'bob@jabber.org'}->{name}
637 - Name you stored in the roster
638 $roster{'bob@jabber.org'}->{subscription}
640 - Subscription status
641 (to, from, both, none)
642 $roster{'bob@jabber.org'}->{ask}
644 - The ask status from this user
645 (subscribe, unsubscribe)
646 $roster{'bob@jabber.org'}->{groups}
648 - Array of groups that
649 bob@jabber.org is in
650 RosterGet() - sends an empty Net::XMPP::IQ::Roster tag to the
652 server so the server will send the Roster to the
653 client. Returns the above hash from RosterParse.
654 RosterRequest() - sends an empty Net::XMPP::IQ::Roster tag to the
656 server so the server will send the Roster to the
657 client.
658 RosterAdd(hash) - sends a packet asking that the jid be
660 added to the roster. The hash format
661 is defined in the SetItem function
662 in the Net::XMPP::Query jabber:iq:roster
663 namespace.
664 RosterRemove(hash) - sends a packet asking that the jid be
666 removed from the roster. The hash
667 format is defined in the SetItem function
668 in the Net::XMPP::Query jabber:iq:roster
669 namespace.
670 Roster DB Functions
672 RosterDB() - Tell the object to initialize the callbacks to
674 automatically populate the Roster DB. If you do this,
675 then make sure that you call RosterRequest() instead of
676 RosterGet() so that the callbacks can catch it and
677 parse it.
678 RosterDBParse(IQ object) - If you want to manually control the
680 database, then you can pass in all iq
681 packets with jabber:iq:roster queries to
682 this function.
683 RosterDBAdd(jid,hash) - Add a new JID into the roster DB. The JID
685 is either a string, or a Net::XMPP::JID
686 object. The hash must be the same format as
687 the has returned by RosterParse above, and
688 is the actual hash, not a reference.
689 RosterDBRemove(jid) - Remove a JID from the roster DB. The JID is
691 either a string, or a Net::XMPP::JID object.
692 RosterDBClear() - Remove all JIDs from the roster DB.
694 RosterDBExists(jid) - return 1 if the JID exists in the roster DB,
696 undef otherwise. The JID is either a string,
697 or a Net::XMPP::JID object.
698 RosterDBJIDs() - returns a list of Net::XMPP::JID objects that
700 represents all of the JIDs in the DB.
701 RosterDBGroups() - returns the complete list of roster groups in the
703 roster.
704 RosterDBGroupExists(group) - return 1 if the group is a group in the
706 roster DB, undef otherwise.
707 RosterDBGroupJIDs(group) - returns a list of Net::XMPP::JID objects
709 that represents all of the JIDs in the
710 specified roster group.
711 RosterDBNonGroupJIDs() - returns a list of Net::XMPP::JID objects
713 that represents all of the JIDs not in a
714 roster group.
715 RosterDBQuery(jid) - returns a hash containing the data from the
717 roster DB for the specified JID. The JID is
718 either a string, or a Net::XMPP::JID object.
719 The hash format the same as in RosterParse
720 above.
721 RosterDBQuery(jid,key) - returns the entry from the above hash for
723 the given key. The available keys are:
724 name, ask, subsrcription and groups
725 The JID is either a string, or a
726 Net::XMPP::JID object.
727
729 Ryan Eatmon
730
732 This module is free software, you can redistribute it and/or modify it
733 under the LGPL.
734perl v5.8.8 2007-04-02 Net::XMPP::Protocol(3)