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
10         Messaging 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
21         and easy to use.  Net::XMPP is a wrapper around the rest of the
22         official 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
28         NOTE: The parser that XML::Stream::Parser provides, as are most Perl
29         parsers, is synchronous.  If you are in the middle of parsing a packet
30         and call a user defined callback, the Parser is blocked until your
31         callback finishes.  This means you cannot be operating on a packet,
32         send out another packet and wait for a response to that packet.  It
33         will never get to you.  Threading might solve this, but as of this
34         writing threading in Perl is not quite up to par yet.  This issue will
35         be revisted in the future.
36

EXAMPLES

38             use Net::XMPP;
39             my $client = new Net::XMPP::Client();
40

METHODS

42         The Net::XMPP module does not define any methods that you will call
43         directly in your code.  Instead you will instantiate objects that call
44         functions from this module to do work.  The three main objects that
45         you will work with are the Message, Presence, and IQ modules. Each one
46         corresponds to the Jabber equivilant and allows you get and set all
47         parts of those packets.
48
49         There are a few functions that are the same across all of the objects:
50
51   Retrieval functions
52         GetXML() - returns the XML string that represents the data contained
53                    in the object.
54
55                    $xml  = $obj->GetXML();
56
57         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
63                               @xObj = $obj->GetChild();
64                               @xObj = $obj->GetChild("my:namespace");
65
66         GetTag() - return the root tag name of the packet.
67
68         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
72   Creation functions
73         NewChild(namespace)     - creates a new Net::XMPP::Stanza object with
74         NewChild(namespace,tag)   the specified namespace and root tag of
75                                   whatever the namespace says its root tag
76                                   should be.  Optionally you may specify
77                                   another root tag if the default is not
78                                   desired, or the namespace requres you to set
79                                   one.
80
81                                   $xObj = $obj->NewChild("my:namespace");
82                                   $xObj = $obj->NewChild("my:namespace","foo");
83                                     ie. <foo xmlns='my:namespace'...></foo>
84
85         InsertRawXML(string) - puts the specified string raw into the XML
86                                packet that you call this on.
87
88                                $message->InsertRawXML("<foo></foo>")
89                                  <message...>...<foo></foo></message>
90
91                                $x = $message->NewChild(..);
92                                $x->InsertRawXML("test");
93
94                                $query = $iq->GetChild(..);
95                                $query->InsertRawXML("test");
96
97         ClearRawXML() - removes the raw XML from the packet.
98
99   Removal functions
100         RemoveChild()          - removes all of the namespaces child elements
101         RemoveChild(namespace)   from the object.  If a namespace is provided,
102                                  then only the children with that namespace are
103                                  removed.
104
105   Test functions
106         DefinedChild()          - returns 1 if there are any known namespaced
107         DefinedChild(namespace)   stanzas in the packet, 0 otherwise.
108                                   Optionally you can specify a namespace and
109                                   determine if there are any stanzas with that
110                                   namespace.
111
112                                   $test = $obj->DefinedChild();
113                                   $test = $obj->DefinedChild("my:namespace");
114

PACKAGES

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

AUTHOR

162       Ryan Eatmon Currently maintained by Eric Hacker.
163

BUGS

165       Probably. There is at least one issue with XLM::Stream providing
166       different node structures depending on how the node is created.
167       Net::XMPP should now be able to handle this, but who knows what else
168       lurks.
169
171       This module is free software, you can redistribute it and/or modify it
172       under the LGPL.
173
174
175
176perl v5.12.0                      2010-05-04                      Net::XMPP(3)
Impressum