1Net::XMPP(3) User Contributed Perl Documentation Net::XMPP(3)
2
6 Net::XMPP - XMPP Perl Library
7
9 Net::XMPP provides a Perl user with access to the Extensible
10 Messaging and Presence Protocol (XMPP).
11 For more information about XMPP visit:
13 http://www.xmpp.org
15
17 Net::XMPP is a convenient tool to use for any perl script that would
18 like to utilize the XMPP Instant Messaging protocol. While not a
19 client in and of itself, it provides all of the necessary back-end
20 functions to make a CGI client or command-line perl client feasible
21 and easy to use. Net::XMPP is a wrapper around the rest of the
22 official Net::XMPP::xxxxxx packages.
23 There is are example scripts in the example directory that provide you
25 with examples of very simple XMPP programs.
26 NOTE: The parser that XML::Stream::Parser provides, as are most Perl
28 parsers, is synchronous. If you are in the middle of parsing a packet
29 and call a user defined callback, the Parser is blocked until your
30 callback finishes. This means you cannot be operating on a packet,
31 send out another packet and wait for a response to that packet. It
32 will never get to you. Threading might solve this, but as of this
33 writing threading in Perl is not quite up to par yet. This issue will
34 be revisted in the future.
35
37 use Net::XMPP;
38 my $client = new Net::XMPP::Client();
39
41 The Net::XMPP module does not define any methods that you will call
42 directly in your code. Instead you will instantiate objects that call
43 functions from this module to do work. The three main objects that
44 you will work with are the Message, Presence, and IQ modules. Each one
45 corresponds to the Jabber equivilant and allows you get and set all
46 parts of those packets.
47 There are a few functions that are the same across all of the objects:
49 Retrieval functions
51 GetXML() - returns the XML string that represents the data contained
53 in the object.
54 $xml = $obj->GetXML();
56 GetChild() - returns an array of Net::XMPP::Stanza objects
58 GetChild(namespace) that represent all of the stanzas in the object
59 that are namespaced. If you specify a namespace
60 then only stanza objects with that XMLNS are
61 returned.
62 @xObj = $obj->GetChild();
64 @xObj = $obj->GetChild("my:namespace");
65 GetTag() - return the root tag name of the packet.
67 GetTree() - return the XML::Stream::Node object that contains the data.
69 See XML::Stream::Node for methods you can call on this
70 object.
71 Creation functions
73 NewChild(namespace) - creates a new Net::XMPP::Stanza object with
75 NewChild(namespace,tag) the specified namespace and root tag of
76 whatever the namespace says its root tag
77 should be. Optionally you may specify
78 another root tag if the default is not
79 desired, or the namespace requres you to set
80 one.
81 $xObj = $obj->NewChild("my:namespace");
83 $xObj = $obj->NewChild("my:namespace","foo");
84 ie. <foo xmlns='my:namespace'...></foo>
85 InsertRawXML(string) - puts the specified string raw into the XML
87 packet that you call this on.
88 $message->InsertRawXML("<foo></foo>")
90 <message...>...<foo></foo></message>
91 $x = $message->NewChild(..);
93 $x->InsertRawXML("test");
94 $query = $iq->GetChild(..);
96 $query->InsertRawXML("test");
97 ClearRawXML() - removes the raw XML from the packet.
99 Removal functions
101 RemoveChild() - removes all of the namespaces child elements
103 RemoveChild(namespace) from the object. If a namespace is provided,
104 then only the children with that namespace are
105 removed.
106 Test functions
108 DefinedChild() - returns 1 if there are any known namespaced
110 DefinedChild(namespace) stanzas in the packet, 0 otherwise.
111 Optionally you can specify a namespace and
112 determine if there are any stanzas with that
113 namespace.
114 $test = $obj->DefinedChild();
116 $test = $obj->DefinedChild("my:namespace");
117
119 For more information on each of these packages, please see the man page
120 for each one.
121 Net::XMPP::Client
123 This package contains the code needed to communicate with an XMPP
125 server: login, wait for messages, send messages, and logout. It uses
126 XML::Stream to read the stream from the server and based on what kind
127 of tag it encounters it calls a function to handle the tag.
128 Net::XMPP::Protocol
130 A collection of high-level functions that Client uses to make their
132 lives easier. These methods are inherited by the Client.
133 Net::XMPP::JID
135 The XMPP IDs consist of three parts: user id, server, and resource.
137 This module gives you access to those components without having to
138 parse the string yourself.
139 Net::XMPP::Message
141 Everything needed to create and read a <message/> received from the
143 server.
144 Net::XMPP::Presence
146 Everything needed to create and read a <presence/> received from the
148 server.
149 Net::XMPP::IQ
151 IQ is a wrapper around a number of modules that provide support for
153 the various Info/Query namespaces that XMPP recognizes.
154 Net::XMPP::Stanza
156 This module represents a namespaced stanza that is used to extend a
158 <message/>, <presence/>, and <iq/>.
159 The man page for Net::XMPP::Stanza contains a listing of all supported
161 namespaces, and the methods that are supported by the objects that
162 represent those namespaces.
163 Net::XMPP::Namespaces
165 XMPP allows for any stanza to be extended by any bit of XML. This
167 module contains all of the internals for defining the XMPP based
168 extensions defined by the IETF. The documentation for this module
169 explains more about how to add your own custom namespace and have it
170 be supported.
171
173 Ryan Eatmon Currently maintained by Eric Hacker.
174
176 Probably. There is at least one issue with XLM::Stream providing dif‐
177 ferent node structures depending on how the node is created. Net::XMPP
178 should now be able to handle this, but who knows what else lurks.
179
181 This module is free software, you can redistribute it and/or modify it
182 under the LGPL.
183perl v5.8.8 2007-04-02 Net::XMPP(3)