ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Net-XMPP2/README
(Generate patch)

Comparing Net-XMPP2/README (file contents):
Revision 1.3 by elmex, Thu Jul 5 17:43:30 2007 UTC vs.
Revision 1.4 by elmex, Wed Jul 11 20:56:49 2007 UTC

1NAME 1NAME
2 Net::XMPP2 - An implementation of the XMPP Protocol 2 Net::XMPP2 - An implementation of the XMPP Protocol
3 3
4VERSION 4VERSION
5 Version 0.01 5 Version 0.02
6 6
7SYNOPSIS 7SYNOPSIS
8 use Net::XMPP2::Connection; 8 use Net::XMPP2::Connection;
9 9
10 or: 10 or:
… …
18DESCRIPTION 18DESCRIPTION
19 This is the head module of the Net::XMPP2 XMPP client protocol (as 19 This is the head module of the Net::XMPP2 XMPP client protocol (as
20 described in RFC 3920 and RFC 3921) framework. 20 described in RFC 3920 and RFC 3921) framework.
21 21
22 Net::XMPP2::Connection is a RFC 3920 conformant "XML" stream 22 Net::XMPP2::Connection is a RFC 3920 conformant "XML" stream
23 implementation for clients, which handles tcp connect up to the resource 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 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 25 stream along with some high level methods to send the predefined XML
26 stanzas. 26 stanzas.
27 27
28 Net::XMPP2::IM::Connection is a more highlevel module, which is derived 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 29 from Net::XMPP2::Connection. It handles all the instant messaging client
30 functionality described in RFC 3921. 30 functionality described in RFC 3921.
31 31
32 Net::XMPP2::Client is a multi account client class. It manages 32 Net::XMPP2::Client is a multi account client class. It manages
33 connections to multiple XMPP accounts and tries to offer a nice 33 connections to multiple XMPP accounts and tries to offer a nice high
34 highlevel interface to XMPP communication. 34 level interface to XMPP communication.
35 35
36 For a list of "Supportet extensions" see below. 36 For a list of "Supported extensions" see below.
37 37
38 There are also other modules in this distribution, for example: 38 There are also other modules in this distribution, for example:
39 Net::XMPP2::Util, Net::XMPP2::Writer, Net::XMPP2::Parser and those I 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 40 forgot :-) Those modules might be helpful and/or required if you want to
41 use this framework for XMPP. 41 use this framework for XMPP.
… …
71 For SSL connections. 71 For SSL connections.
72 72
73 Net::DNS 73 Net::DNS
74 For SRV RR lookups. 74 For SRV RR lookups.
75 75
76 And yes, all these are essential for XMPP communication. Even thought 76 And yes, all these are essential for XMPP communication. Even though
77 'instant messaging' and 'presence' is a quite simple problem XMPP 77 'instant messaging' and 'presence' is a quite simple problem XMPP
78 somehow was successful at complicating the task enough to keep me busy 78 somehow was successful at making the task complicated enough to keep me
79 for a long time. But all that time wasn't only for the technology 79 busy for a long time. But all of that time wasn't only for the
80 required to get it started, mostly it was for all the quirks, hacks and 80 technology required to get it started, mostly it was for all the quirks,
81 badly applied "XML" in the protocol which complicated the matter. 81 hacks and badly applied "XML" in the protocol which complicated the
82 matter.
82 83
83RELEASE NOTES 84RELEASE NOTES
84 Here are some notes to the releases (release of this version is at top): 85 Here are some notes to the releases (release of this version is at top):
85 86
86 Version 87 Version
88 * 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
87 * 0.01 100 * 0.01
88 This release has beta status. The code is already used daily in my 101 This release has beta status. The code is already used daily in my
89 client and I keep looking out for bugs. If you find undocumented, 102 client and I keep looking out for bugs. If you find undocumented,
90 missing or faulty code/methods please drop me a mail! See also 103 missing or faulty code/methods please drop me a mail! See also
91 "BUGS" below. 104 "BUGS" below.
92 105
93 Potential edges when using this module: sparely documented methods, 106 Potential edges when using this module: sparely documented methods,
94 missing functionality and generally bugs bugs and bugs. Even thought 107 missing functionality and generally bugs bugs and bugs. Even though
95 this module is in daily usage there are still lots of cases I might 108 this module is in daily usage there are still lots of cases I might
96 have missed. 109 have missed.
97 110
98 For the next release I'm planning to provide more examples in the 111 For the next release I'm planning to provide more examples in the
99 documentation and/or samples/ directory, along with bugfixes and 112 documentation and/or samples/ directory, along with bugfixes and
… …
101 114
102 TODO 115 TODO
103 There are still lots of items on the TODO list (see also the TODO file 116 There are still lots of items on the TODO list (see also the TODO file
104 in the distribution of Net::XMPP2). 117 in the distribution of Net::XMPP2).
105 118
119 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
106Why (yet) another XMPP module? 125Why (yet) another XMPP module?
107 The main outstanding feature of this module in comparsion to the other 126 The main outstanding feature of this module in comparison to the other
108 XMPP (aka Jabber) modules out there is the support for AnyEvent. 127 XMPP (aka Jabber) modules out there is the support for AnyEvent.
109 AnyEvent permits you to use this module together with other I/O event 128 AnyEvent permits you to use this module together with other I/O event
110 based programs and libraries (ie. Gtk2 or Event). 129 based programs and libraries (ie. Gtk2 or Event).
111 130
112 The other modules could often only be integrated in those applications 131 The other modules could often only be integrated in those applications
113 or librarys by using threads. I decided to write this module because I 132 or libraries by using threads. I decided to write this module because I
114 think CPAN lacks an event based XMPP module. Threads are unfortunately 133 think CPAN lacks an event based XMPP module. Threads are unfortunately
115 not an alternative in Perl at the moment due the limited threading 134 not an alternative in Perl at the moment due the limited threading
116 functionality they provide and the global speed hit. I also think that a 135 functionality they provide and the global speed hit. I also think that a
117 simple event based I/O framework might be a bit easier to handle than 136 simple event based I/O framework might be a bit easier to handle than
118 threads. 137 threads.
… …
126 145
127A note about TLS 146A note about TLS
128 This module also supports TLS, as the specification of XMPP requires an 147 This module also supports TLS, as the specification of XMPP requires an
129 implementation to support TLS. 148 implementation to support TLS.
130 149
131 There are maybe still some bugs in the handling of TLS in 150 Maybe there are still some bugs in the handling of TLS in
132 Net::XMPP2::Connection. So keep an eye on TLS with this module. If you 151 Net::XMPP2::Connection. So keep an eye on TLS with this module. If you
133 encounter any problems it would be very helpful if you could debug them 152 encounter any problems it would be very helpful if you could debug them
134 or at least send me a detailed report on how to reproduce the problem. 153 or at least send me a detailed report on how to reproduce the problem.
135 154
136 (As I use this module myself I don't expect TLS to be completly broken, 155 (As I use this module myself I don't expect TLS to be completly broken,
137 but it might break under different circumstances than I have here. Those 156 but it might break under different circumstances than I have here. Those
138 circumstances might be a different load of data pumped through the TLS 157 circumstances might be a different load of data pumped through the TLS
139 connection.) 158 connection.)
140 159
141 I mainly expect problems where aviable data isn't properly read from the 160 I mainly expect problems where available data isn't properly read from
142 socket or written to it. You might want to take a look at the 161 the socket or written to it. You might want to take a look at the
143 "debug_send" and "debug_recv" events in Net::XMPP2::Connection. 162 "debug_send" and "debug_recv" events in Net::XMPP2::Connection.
144 163
145Supportet extensions 164Supported extensions
146 See Net::XMPP2::Ext for a list. 165 See Net::XMPP2::Ext for a list.
147 166
148EXAMPLES 167EXAMPLES
149 See "samples/test_client" for a first pointer. More examples will be 168 Following examples are included in this distribution:
150 included in later releases, please feel free to ask the "AUTHOR" if you 169
151 have any questions about the API. There is also an IRC channel, see 170 samples/simple_example_1
152 "SUPPORT". 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".
153 218
154AUTHOR 219AUTHOR
155 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>" 220 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
156 221
157BUGS 222BUGS
158 Please note that I'm currently (July 2007) the only developer on this 223 Please note that I'm currently (July 2007) the only developer on this
159 project and I'm very busy with my studies in Computer Science in Summer 224 project and I'm very busy with my studies in Computer Science in Summer
160 2007. If you want to ease my workload or want timely releases please 225 2007. If you want to ease my workload or want timely releases, please
161 send me patches instead only bug reports or feature requests. I won't 226 send me patches instead of bug reports or feature requests. I won't
162 forget the reports or requests if you can't or didn't send patches but 227 forget the reports or requests if you can't or didn't send patches, but
163 it can take a long time until I get enough time to fix/implement them. 228 it can take a long time until I get enough time to fix/implement them.
164 229
165 Also try to be as precise as possible with bugreports and best, if you 230 Also try to be as precise as possible with bug reports, if you can't
166 can't send a patch, would be if you find out which code doesn't work and 231 send a patch, it would be best if you find out which code doesn't work
167 tell me why. 232 and tell me why.
168 233
169 Please report any bugs or feature requests to "bug-net-xmpp2 at 234 Please report any bugs or feature requests to "bug-net-xmpp2 at
170 rt.cpan.org", or through the web interface at 235 rt.cpan.org", or through the web interface at
171 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be 236 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be
172 notified, and then you'll automatically be notified of progress on your 237 notified and then you'll automatically be notified of progress on your
173 bug as I make changes. 238 bug as I make changes.
174 239
175SUPPORT 240SUPPORT
176 You can find documentation for this module with the perldoc command. 241 You can find documentation for this module with the perldoc command.
177 242
… …
201 * Search CPAN 266 * Search CPAN
202 <http://search.cpan.org/dist/Net-XMPP2> 267 <http://search.cpan.org/dist/Net-XMPP2>
203 268
204ACKNOWLEDGEMENTS 269ACKNOWLEDGEMENTS
205 Thanks to the XSF for the development of an open instant messaging 270 Thanks to the XSF for the development of an open instant messaging
206 protocol (even thought it uses "XML"). 271 protocol (even though it uses "XML").
207 272
208 And thanks to all people who had to listen to my desperate curses about 273 And thanks to all people who had to listen to my desperate curses about
209 the brokeness/braindeadness of XMPP, without you I would've never 274 the brokenness/braindeadness of XMPP. Without you I would've never
210 brought this module to a usable state. 275 brought this module to a usable state.
276
277 Thanks to:
278
279 * Carlo von Loesch (aka lynX) <http://www.psyced.org/>
280 For pointing out some typos.
211 281
212COPYRIGHT & LICENSE 282COPYRIGHT & LICENSE
213 Copyright 2007 Robin Redeker, all rights reserved. 283 Copyright 2007 Robin Redeker, all rights reserved.
214 284
215 This program is free software; you can redistribute it and/or modify it 285 This program is free software; you can redistribute it and/or modify it

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines