ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Net-XMPP2/README
Revision: 1.4
Committed: Wed Jul 11 20:56:49 2007 UTC (17 years, 7 months ago) by elmex
Branch: MAIN
Changes since 1.3: +102 -32 lines
Log Message:
finished up the next release.

File Contents

# User Rev Content
1 elmex 1.1 NAME
2     Net::XMPP2 - An implementation of the XMPP Protocol
3    
4     VERSION
5 elmex 1.4 Version 0.02
6 elmex 1.1
7     SYNOPSIS
8 elmex 1.2 use Net::XMPP2::Connection;
9    
10     or:
11    
12     use Net::XMPP2::IM::Connection;
13    
14 elmex 1.3 or:
15    
16     use Net::XMPP2::Client;
17    
18 elmex 1.2 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 elmex 1.4 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 elmex 1.2 stream along with some high level methods to send the predefined XML
26     stanzas.
27    
28 elmex 1.4 Net::XMPP2::IM::Connection is a more high level module, which is derived
29 elmex 1.2 from Net::XMPP2::Connection. It handles all the instant messaging client
30     functionality described in RFC 3921.
31    
32 elmex 1.3 Net::XMPP2::Client is a multi account client class. It manages
33 elmex 1.4 connections to multiple XMPP accounts and tries to offer a nice high
34     level interface to XMPP communication.
35 elmex 1.3
36 elmex 1.4 For a list of "Supported extensions" see below.
37 elmex 1.2
38     There are also other modules in this distribution, for example:
39 elmex 1.3 Net::XMPP2::Util, Net::XMPP2::Writer, Net::XMPP2::Parser and those I
40 elmex 1.2 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 elmex 1.3 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 elmex 1.4 And yes, all these are essential for XMPP communication. Even though
77 elmex 1.3 'instant messaging' and 'presence' is a quite simple problem XMPP
78 elmex 1.4 somehow was successful at making the task complicated enough to keep me
79     busy for a long time. But all of that time wasn't only for the
80     technology required to get it started, mostly it was for all the quirks,
81     hacks and badly applied "XML" in the protocol which complicated the
82     matter.
83 elmex 1.3
84     RELEASE NOTES
85     Here are some notes to the releases (release of this version is at top):
86    
87     Version
88 elmex 1.4 * 0.02
89     This release adds lots of small improvements on the API (mostly new
90     events), and also some bugfixes here and there. The release also
91     comes with some new examples, you might want to take a look at the
92     "EXAMPLES" section.
93    
94     As a highlight I also present the implementation of XEP-0004 (Data
95     Forms), see also Net::XMPP2::Ext for a description.
96    
97     I also added some convenience functions to Net::XMPP2::Util, for
98     example "simxml" which simplifies the generation of XMPP-like "XML".
99    
100 elmex 1.3 * 0.01
101     This release has beta status. The code is already used daily in my
102     client and I keep looking out for bugs. If you find undocumented,
103     missing or faulty code/methods please drop me a mail! See also
104     "BUGS" below.
105    
106     Potential edges when using this module: sparely documented methods,
107 elmex 1.4 missing functionality and generally bugs bugs and bugs. Even though
108 elmex 1.3 this module is in daily usage there are still lots of cases I might
109     have missed.
110    
111     For the next release I'm planning to provide more examples in the
112     documentation and/or samples/ directory, along with bugfixes and
113     enhancements along with some todo items killed from the TODO file.
114    
115     TODO
116     There are still lots of items on the TODO list (see also the TODO file
117     in the distribution of Net::XMPP2).
118    
119 elmex 1.4 Sadly this module still misses some decent DOM implementation. Do you
120     know some decent DOM Level 2 implementation for Perl? (I considered
121     switchting to XML::LibXML but I somehow have more trust in the "expat"
122     XML parser, maybe someone wants to implement XML::LibXML based parsing
123     for me (and of course a DOM interface for Net::XMPP2::Node?)
124    
125 elmex 1.2 Why (yet) another XMPP module?
126 elmex 1.4 The main outstanding feature of this module in comparison to the other
127 elmex 1.2 XMPP (aka Jabber) modules out there is the support for AnyEvent.
128     AnyEvent permits you to use this module together with other I/O event
129     based programs and libraries (ie. Gtk2 or Event).
130    
131     The other modules could often only be integrated in those applications
132 elmex 1.4 or libraries by using threads. I decided to write this module because I
133 elmex 1.2 think CPAN lacks an event based XMPP module. Threads are unfortunately
134     not an alternative in Perl at the moment due the limited threading
135     functionality they provide and the global speed hit. I also think that a
136     simple event based I/O framework might be a bit easier to handle than
137     threads.
138    
139     Another thing was that I didn't like the APIs of the other modules. In
140     Net::XMPP2 I try to provide low level modules for speaking XMPP as
141     defined in RFC 3920 and RFC 3921 (see also Net::XMPP2::Connection and
142     Net::XMPP2::IM::Connection). But I also try to provide a high level API
143 elmex 1.3 for easier usage for instant messaging tasks and clients (eg.
144     Net::XMPP2::Client).
145 elmex 1.2
146     A note about TLS
147     This module also supports TLS, as the specification of XMPP requires an
148     implementation to support TLS.
149    
150 elmex 1.4 Maybe there are still some bugs in the handling of TLS in
151 elmex 1.2 Net::XMPP2::Connection. So keep an eye on TLS with this module. If you
152     encounter any problems it would be very helpful if you could debug them
153     or at least send me a detailed report on how to reproduce the problem.
154    
155     (As I use this module myself I don't expect TLS to be completly broken,
156     but it might break under different circumstances than I have here. Those
157     circumstances might be a different load of data pumped through the TLS
158     connection.)
159    
160 elmex 1.4 I mainly expect problems where available data isn't properly read from
161     the socket or written to it. You might want to take a look at the
162 elmex 1.2 "debug_send" and "debug_recv" events in Net::XMPP2::Connection.
163    
164 elmex 1.4 Supported extensions
165 elmex 1.3 See Net::XMPP2::Ext for a list.
166 elmex 1.2
167 elmex 1.3 EXAMPLES
168 elmex 1.4 Following examples are included in this distribution:
169    
170     samples/simple_example_1
171     This example script just connects to a server and sends a message
172     and also displays incoming messages on stdout.
173    
174     samples/devcl/devcl
175     This is a more advanced 'example'. It requires you to have Gtk2
176     installed. It's mostly used by the author to implement
177     proof-of-concepts. Currently you start the client like this:
178    
179     ../Net-XMPP2/samples/devcl/# perl ./devcl <jid> <password>
180    
181     The client's main window displays a protocol dump and there is
182     currently a service discovery browser implemented.
183    
184     This might be a valuable source if you look for more real-world
185     applications of Net::XMPP2.
186    
187     samples/conference_lister
188     See below.
189    
190     samples/room_lister
191     See below.
192    
193     samples/room_lister_stat
194     These three scripts implements a global room scan.
195     "conference_lister" takes a list of servers (the file is called
196     "servers.xml" which has the same format as the xml file at
197     <http://www.jabber.org/servers.xml>). It then scans all servers for
198     chat room services and lists them into a file "conferences.stor",
199     which is a Storable dump.
200    
201     "room_lister" then reads that file and queries all services for
202     rooms, and then all rooms for their occupants. The output file is
203     "room_data.stor", also a Storable dump, which in turn can be read
204     with "room_lister_stat", which transform the data structures into
205     something human readable.
206    
207     These scripts are a bit hacky and quite complicated, but maybe it's
208     of any value for someone. You might note "EVQ.pm" in samples which
209     is a module that handles request-throttling (You don't want to flood
210     the server and risk getting the admins attention :).
211    
212     For others, which the author might forgot or didn't want to list here
213     see the "samples/" directory.
214    
215     More examples will be included in later releases, please feel free to
216     ask the "AUTHOR" if you have any questions about the API. There is also
217     an IRC channel, see "SUPPORT".
218 elmex 1.1
219     AUTHOR
220 elmex 1.3 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
221 elmex 1.1
222     BUGS
223 elmex 1.3 Please note that I'm currently (July 2007) the only developer on this
224     project and I'm very busy with my studies in Computer Science in Summer
225 elmex 1.4 2007. If you want to ease my workload or want timely releases, please
226     send me patches instead of bug reports or feature requests. I won't
227     forget the reports or requests if you can't or didn't send patches, but
228 elmex 1.3 it can take a long time until I get enough time to fix/implement them.
229    
230 elmex 1.4 Also try to be as precise as possible with bug reports, if you can't
231     send a patch, it would be best if you find out which code doesn't work
232     and tell me why.
233 elmex 1.3
234 elmex 1.1 Please report any bugs or feature requests to "bug-net-xmpp2 at
235     rt.cpan.org", or through the web interface at
236     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be
237 elmex 1.4 notified and then you'll automatically be notified of progress on your
238 elmex 1.1 bug as I make changes.
239    
240     SUPPORT
241     You can find documentation for this module with the perldoc command.
242    
243     perldoc Net::XMPP2
244    
245     You can also look for information at:
246    
247 elmex 1.3 * IRC: Net::XMPP2 IRC Channel
248     IRC Network: http://freenode.net/
249     Server : chat.freenode.net
250     Channel : #net_xmpp2
251    
252     Feel free to join and ask questions!
253    
254     * Net::XMPP2 Project Site
255     <http://www.ta-sa.org/>
256    
257 elmex 1.1 * AnnoCPAN: Annotated CPAN documentation
258     <http://annocpan.org/dist/Net-XMPP2>
259    
260     * CPAN Ratings
261     <http://cpanratings.perl.org/d/Net-XMPP2>
262    
263     * RT: CPAN's request tracker
264     <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-XMPP2>
265    
266     * Search CPAN
267     <http://search.cpan.org/dist/Net-XMPP2>
268    
269     ACKNOWLEDGEMENTS
270 elmex 1.3 Thanks to the XSF for the development of an open instant messaging
271 elmex 1.4 protocol (even though it uses "XML").
272 elmex 1.3
273     And thanks to all people who had to listen to my desperate curses about
274 elmex 1.4 the brokenness/braindeadness of XMPP. Without you I would've never
275 elmex 1.3 brought this module to a usable state.
276    
277 elmex 1.4 Thanks to:
278    
279     * Carlo von Loesch (aka lynX) <http://www.psyced.org/>
280     For pointing out some typos.
281    
282 elmex 1.1 COPYRIGHT & LICENSE
283     Copyright 2007 Robin Redeker, all rights reserved.
284    
285     This program is free software; you can redistribute it and/or modify it
286     under the same terms as Perl itself.
287