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

NAME

6       Net::XMPP - XMPP Perl Library
7

SYNOPSIS

9       Net::XMPP provides a Perl user with access to the Extensible Messaging
10       and Presence Protocol (XMPP).
11
12       For more information about XMPP visit:
13
14       <http://www.xmpp.org>
15

DESCRIPTION

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 and
21       easy to use.  Net::XMPP is a wrapper around the rest of the official
22       Net::XMPP::xxxxxx packages.
23
24       There is are example scripts in the example directory that provide you
25       with examples of very simple XMPP programs.
26
27       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

EXAMPLES

37         use Net::XMPP;
38         my $client = Net::XMPP::Client->new();
39

METHODS

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 you
44       will work with are the Message, Presence, and IQ modules. Each one
45       corresponds to the Jabber equivalent and allows you get and set all
46       parts of those packets.
47
48       There are a few functions that are the same across all of the objects:
49
50   Retrieval functions
51       GetXML
52           Returns the XML string that represents the data contained in the
53           object.
54
55             $xml  = $obj->GetXML();
56
57       GetChild
58           Returns an array of Net::XMPP::Stanza objects that represent all of
59           the stanzas in the object that are namespaced.  If you specify a
60           namespace then only stanza objects with that XMLNS are returned.
61
62             @xObj = $obj->GetChild();
63             @xObj = $obj->GetChild("my:namespace");
64
65       GetTag
66           Return the root tag name of the packet.
67
68       GetTree
69           Return the XML::Stream::Node object that contains the data.  See
70           XML::Stream::Node for methods you can call on this object.
71
72   Creation functions
73       NewChild
74             NewChild(namespace)
75             NewChild(namespace,tag)
76
77           Creates a new Net::XMPP::Stanza object with the specified namespace
78           and root tag of whatever the namespace says its root tag should be.
79           Optionally you may specify another root tag if the default is not
80           desired, or the namespace requres you to set one.
81
82             $xObj = $obj->NewChild("my:namespace");
83             $xObj = $obj->NewChild("my:namespace","foo");
84
85           ie. <foo xmlns='my:namespace'...></foo>
86
87       InsertRawXML
88             InsertRawXML(string)
89
90           puts the specified string raw into the XML packet that you call
91           this on.
92
93             $message->InsertRawXML("<foo></foo>")
94               <message...>...<foo></foo></message>
95
96             $x = $message->NewChild(..);
97             $x->InsertRawXML("test");
98
99             $query = $iq->GetChild(..);
100             $query->InsertRawXML("test");
101
102       ClearRawXML
103             ClearRawXML()
104
105           Removes the raw XML from the packet.
106
107   Removal functions
108       RemoveChild
109             RemoveChild()
110             RemoveChild(namespace)
111
112           Removes all of the namespaces child elements from the object.  If a
113           namespace is provided, then only the children with that namespace
114           are removed.
115
116   Test functions
117       DefinedChild
118             DefinedChild()
119             DefinedChild(namespace)
120
121           Returns 1 if there are any known namespaced stanzas in the packet,
122           0 otherwise.  Optionally you can specify a namespace and determine
123           if there are any stanzas with that namespace.
124
125             $test = $obj->DefinedChild();
126             $test = $obj->DefinedChild("my:namespace");
127

PACKAGES

129       For more information on each of these packages, please see the man page
130       for each one.
131
132   Net::XMPP::Client
133       This package contains the code needed to communicate with an XMPP
134       server: login, wait for messages, send messages, and logout.  It uses
135       XML::Stream to read the stream from the server and based on what kind
136       of tag it encounters it calls a function to handle the tag.
137
138   Net::XMPP::Protocol
139       A collection of high-level functions that Client uses to make their
140       lives easier.  These methods are inherited by the Client.
141
142   Net::XMPP::JID
143       The XMPP IDs consist of three parts: user id, server, and resource.
144       This module gives you access to those components without having to
145       parse the string yourself.
146
147   Net::XMPP::Message
148       Everything needed to create and read a <message/> received from the
149       server.
150
151   Net::XMPP::Presence
152       Everything needed to create and read a <presence/> received from the
153       server.
154
155   Net::XMPP::IQ
156       IQ is a wrapper around a number of modules that provide support for the
157       various Info/Query namespaces that XMPP recognizes.
158
159   Net::XMPP::Stanza
160       This module represents a namespaced stanza that is used to extend a
161       <message/>, <presence/>, and <iq/>.
162
163       The man page for Net::XMPP::Stanza contains a listing of all supported
164       namespaces, and the methods that are supported by the objects that
165       represent those namespaces.
166
167   Net::XMPP::Namespaces
168       XMPP allows for any stanza to be extended by any bit of XML.  This
169       module contains all of the internals for defining the XMPP based
170       extensions defined by the IETF.  The documentation for this module
171       explains more about how to add your own custom namespace and have it be
172       supported.
173

AUTHOR

175       Originally authored by Ryan Eatmon.
176
177       Previously maintained by Eric Hacker.
178
179       Currently maintained by Darian Anthony Patrick.
180

BUGS

182       See unpatched issues at
183       <https://rt.cpan.org/Dist/Display.html?Queue=Net-XMPP>.
184
185       There is at least one issue with XML::Stream providing different node
186       structures depending on how the node is created. Net::XMPP should now
187       be able to handle this, but who knows what else lurks.
188

190       This module is free software, you can redistribute it and/or modify it
191       under the LGPL 2.1.
192
193
194
195perl v5.34.0                      2021-07-22                      Net::XMPP(3)
Impressum