ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Net-XMPP2/README
Revision: 1.9
Committed: Thu Jul 26 19:45:55 2007 UTC (16 years, 10 months ago) by elmex
Branch: MAIN
CVS Tags: HEAD
Changes since 1.8: +1 -1 lines
Log Message:
typo

File Contents

# Content
1 NAME
2 Net::XMPP2 - An implementation of the XMPP Protocol
3
4 VERSION
5 Version 0.04
6
7 SYNOPSIS
8 use Net::XMPP2::Connection;
9
10 or:
11
12 use Net::XMPP2::IM::Connection;
13
14 or:
15
16 use Net::XMPP2::Client;
17
18 DESCRIPTION
19 This is the head module of the Net::XMPP2 XMPP client protocol (as
20 described in RFC 3920 and RFC 3921) framework.
21
22 Net::XMPP2::Connection is a RFC 3920 conformant "XML" stream
23 implementation for clients, which handles TCP connect up to the resource
24 binding. And provides low level access to the XML nodes on the XML
25 stream along with some high level methods to send the predefined XML
26 stanzas.
27
28 Net::XMPP2::IM::Connection is a more high level module, which is derived
29 from Net::XMPP2::Connection. It handles all the instant messaging client
30 functionality described in RFC 3921.
31
32 Net::XMPP2::Client is a multi account client class. It manages
33 connections to multiple XMPP accounts and tries to offer a nice high
34 level interface to XMPP communication.
35
36 For a list of "Supported extensions" see below.
37
38 There are also other modules in this distribution, for example:
39 Net::XMPP2::Util, Net::XMPP2::Writer, Net::XMPP2::Parser and those I
40 forgot :-) Those modules might be helpful and/or required if you want to
41 use this framework for XMPP.
42
43 See also Net::XMPP2::Writer for a discussion about the brokeness of XML
44 in the XMPP specification.
45
46 If you have any questions or seek for help look below under "SUPPORT".
47
48 REQUIREMENTS
49 One of the major drawbacks I see for Net::XMPP2 is the long list of
50 required modules to make it work.
51
52 AnyEvent
53 For the I/O events and timers.
54
55 XML::Writer
56 For writing "XML".
57
58 XML::Parser::Expat
59 For parsing partial "XML" stuff.
60
61 MIME::Base64
62 For SASL authentication
63
64 Authen::SASL
65 For SASL authentication
66
67 Net::LibIDN
68 For stringprep profiles to handle JIDs.
69
70 Net::SSLeay
71 For SSL connections.
72
73 Net::DNS
74 For SRV RR lookups.
75
76 Digest::SHA1
77 For component authentication.
78
79 And yes, all these are essential for XMPP communication. Even though
80 'instant messaging' and 'presence' is a quite simple problem XMPP
81 somehow was successful at making the task complicated enough to keep me
82 busy for a long time. But all of that time wasn't only for the
83 technology required to get it started, mostly it was for all the quirks,
84 hacks and badly applied "XML" in the protocol which complicated the
85 matter.
86
87 RELEASE NOTES
88 Here are some notes to the releases (release of this version is at top):
89
90 Version
91 * 0.04
92 After realizing that in band registration in Net::XMPP2::Ext was
93 already in in version 0.03 I finally had to implement it.
94
95 While implementing in band registration I implemented XEP-0066: Out
96 of Band Data. You can now receive and send URLs from and to others.
97 See also Net::XMPP2::Ext::OOB.
98
99 I also fixed some bugs in Net::XMPP2::Ext::Disco.
100
101 * 0.03
102 This release adds new events for attaching information to "XML"
103 stanzas that are in transmission to the server. See also the events
104 "send_*_hook" in Net::XMPP2::Connection.
105
106 The event callbacks als don't have to return a true value anymore.
107 What the return values do depends on the event now.
108
109 The highlight of this release is the implementation of XEP-0114, the
110 Jabber Component Protocol.
111
112 It's possible to get a DOM tree from a Net::XMPP2::Node now and also
113 to receive the original parsed "XML" from it, which should enable
114 full access to the "XML" data that was received. This also allows
115 easy integration with other XML Perl modules.
116
117 You can also set the initial priority of the presence in
118 Net::XMPP2::IM::Connection now.
119
120 Please consult the Changes file for greater detail about bugfixes
121 and new features.
122
123 * 0.02
124 This release adds lots of small improvements to the API (mostly new
125 events), and also some bugfixes here and there. The release also
126 comes with some new examples, you might want to take a look at the
127 "EXAMPLES" section.
128
129 As a highlight I also present the implementation of XEP-0004 (Data
130 Forms), see also Net::XMPP2::Ext for a description.
131
132 I also added some convenience functions to Net::XMPP2::Util, for
133 example "simxml" which simplifies the generation of XMPP-like "XML".
134
135 * 0.01
136 This release has beta status. The code is already used daily in my
137 client and I keep looking out for bugs. If you find undocumented,
138 missing or faulty code/methods please drop me a mail! See also
139 "BUGS" below.
140
141 Potential edges when using this module: sparely documented methods,
142 missing functionality and generally bugs bugs and bugs. Even though
143 this module is in daily usage there are still lots of cases I might
144 have missed.
145
146 For the next release I'm planning to provide more examples in the
147 documentation and/or samples/ directory, along with bugfixes and
148 enhancements along with some todo items killed from the TODO file.
149
150 TODO
151 There are still lots of items on the TODO list (see also the TODO file
152 in the distribution of Net::XMPP2).
153
154 Why (yet) another XMPP module?
155 The main outstanding feature of this module in comparison to the other
156 XMPP (aka Jabber) modules out there is the support for AnyEvent.
157 AnyEvent permits you to use this module together with other I/O event
158 based programs and libraries (ie. Gtk2 or Event).
159
160 The other modules could often only be integrated in those applications
161 or libraries by using threads. I decided to write this module because I
162 think CPAN lacks an event based XMPP module. Threads are unfortunately
163 not an alternative in Perl at the moment due the limited threading
164 functionality they provide and the global speed hit. I also think that a
165 simple event based I/O framework might be a bit easier to handle than
166 threads.
167
168 Another thing was that I didn't like the APIs of the other modules. In
169 Net::XMPP2 I try to provide low level modules for speaking XMPP as
170 defined in RFC 3920 and RFC 3921 (see also Net::XMPP2::Connection and
171 Net::XMPP2::IM::Connection). But I also try to provide a high level API
172 for easier usage for instant messaging tasks and clients (eg.
173 Net::XMPP2::Client).
174
175 A note about TLS
176 This module also supports TLS, as the specification of XMPP requires an
177 implementation to support TLS.
178
179 Maybe there are still some bugs in the handling of TLS in
180 Net::XMPP2::Connection. So keep an eye on TLS with this module. If you
181 encounter any problems it would be very helpful if you could debug them
182 or at least send me a detailed report on how to reproduce the problem.
183
184 (As I use this module myself I don't expect TLS to be completly broken,
185 but it might break under different circumstances than I have here. Those
186 circumstances might be a different load of data pumped through the TLS
187 connection.)
188
189 I mainly expect problems where available data isn't properly read from
190 the socket or written to it. You might want to take a look at the
191 "debug_send" and "debug_recv" events in Net::XMPP2::Connection.
192
193 Supported extensions
194 See Net::XMPP2::Ext for a list.
195
196 EXAMPLES
197 Following examples are included in this distribution:
198
199 samples/simple_example_1
200 This example script just connects to a server and sends a message
201 and also displays incoming messages on stdout.
202
203 samples/devcl/devcl
204 This is a more advanced 'example'. It requires you to have Gtk2
205 installed. It's mostly used by the author to implement
206 proof-of-concepts. Currently you start the client like this:
207
208 ../Net-XMPP2/samples/devcl/# perl ./devcl <jid> <password>
209
210 The client's main window displays a protocol dump and there is
211 currently a service discovery browser implemented.
212
213 This might be a valuable source if you look for more real-world
214 applications of Net::XMPP2.
215
216 samples/conference_lister
217 See below.
218
219 samples/room_lister
220 See below.
221
222 samples/room_lister_stat
223 These three scripts implements a global room scan.
224 "conference_lister" takes a list of servers (the file is called
225 "servers.xml" which has the same format as the xml file at
226 <http://www.jabber.org/servers.xml>). It then scans all servers for
227 chat room services and lists them into a file "conferences.stor",
228 which is a Storable dump.
229
230 "room_lister" then reads that file and queries all services for
231 rooms, and then all rooms for their occupants. The output file is
232 "room_data.stor", also a Storable dump, which in turn can be read
233 with "room_lister_stat", which transform the data structures into
234 something human readable.
235
236 These scripts are a bit hacky and quite complicated, but maybe it's
237 of any value for someone. You might note "EVQ.pm" in samples which
238 is a module that handles request-throttling (You don't want to flood
239 the server and risk getting the admins attention :).
240
241 samples/simple_component
242 This is a (basic) skeleton for a jabber component.
243
244 samples/simple_oob_retriever
245 This is a simple out of band file transfer receiver bot. It uses
246 "curl" to fetch the files and also has the sample functionality of
247 sending a file url for someone who sends the bot a 'send <filename>'
248 message.
249
250 samples/simple_register_example
251 This is a example script which allows you to register, unregister
252 and change your password for accounts. Execute it without arguments
253 for more details.
254
255 For others, which the author might forgot or didn't want to list here
256 see the "samples/" directory.
257
258 More examples will be included in later releases, please feel free to
259 ask the "AUTHOR" if you have any questions about the API. There is also
260 an IRC channel, see "SUPPORT".
261
262 AUTHOR
263 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
264
265 BUGS
266 Please note that I'm currently (July 2007) the only developer on this
267 project and I'm very busy with my studies in Computer Science in Summer
268 2007. If you want to ease my workload or want timely releases, please
269 send me patches instead of bug reports or feature requests. I won't
270 forget the reports or requests if you can't or didn't send patches, but
271 I can't gurantee immediate response. But I will of course try to
272 fix/implement them as soon as possible!
273
274 Also try to be as precise as possible with bug reports, if you can't
275 send a patch, it would be best if you find out which code doesn't work
276 and tell me why.
277
278 Please report any bugs or feature requests to "bug-net-xmpp2 at
279 rt.cpan.org", or through the web interface at
280 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be
281 notified and then you'll automatically be notified of progress on your
282 bug as I make changes.
283
284 SUPPORT
285 You can find documentation for this module with the perldoc command.
286
287 perldoc Net::XMPP2
288
289 You can also look for information at:
290
291 * IRC: Net::XMPP2 IRC Channel
292 IRC Network: http://freenode.net/
293 Server : chat.freenode.net
294 Channel : #net_xmpp2
295
296 Feel free to join and ask questions!
297
298 * Net::XMPP2 Project Site
299 <http://www.ta-sa.org/>
300
301 * AnnoCPAN: Annotated CPAN documentation
302 <http://annocpan.org/dist/Net-XMPP2>
303
304 * CPAN Ratings
305 <http://cpanratings.perl.org/d/Net-XMPP2>
306
307 * RT: CPAN's request tracker
308 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-XMPP2>
309
310 * Search CPAN
311 <http://search.cpan.org/dist/Net-XMPP2>
312
313 ACKNOWLEDGEMENTS
314 Thanks to the XSF for the development of an open instant messaging
315 protocol (even though it uses "XML").
316
317 And thanks to all people who had to listen to my desperate curses about
318 the brokenness/braindeadness of XMPP. Without you I would've never
319 brought this module to a usable state.
320
321 Thanks to:
322
323 * Carlo von Loesch (aka lynX) <http://www.psyced.org/>
324 For pointing out some typos.
325
326 COPYRIGHT & LICENSE
327 Copyright 2007 Robin Redeker, all rights reserved.
328
329 This program is free software; you can redistribute it and/or modify it
330 under the same terms as Perl itself.
331