Debian Codegraph @

README

raw
1 NAME
2 AnyEvent::XMPP - An implementation of the XMPP Protocol
3
4 VERSION
5 Version 0.55
6
7 SYNOPSIS
8 use AnyEvent::XMPP::Connection;
9
10 or:
11
12 use AnyEvent::XMPP::IM::Connection;
13
14 or:
15
16 use AnyEvent::XMPP::Client;
17
18 DESCRIPTION
19 This is the head module of the AnyEvent::XMPP XMPP client protocol (as
20 described in RFC 3920 and RFC 3921) framework.
21
22 AnyEvent::XMPP::Connection is a RFC 3920 conforming "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 AnyEvent::XMPP::IM::Connection is a more high level module, which is
29 derived from AnyEvent::XMPP::Connection. It handles all the instant
30 messaging client functionality described in RFC 3921.
31
32 AnyEvent::XMPP::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 AnyEvent::XMPP::Util, AnyEvent::XMPP::Writer, AnyEvent::XMPP::Parser and
40 those I forgot :-) Those modules might be helpful and/or required if you
41 want to use this framework for XMPP.
42
43 See also AnyEvent::XMPP::Writer for a discussion about the brokenness of
44 XML 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 AnyEvent::XMPP is the long list of
50 required modules to make it work.
51
52 AnyEvent
53 For the I/O events, timers, TCP, TLS, DNS and I/O buffering.
54
55 Object::Event
56 The former AnyEvent::XMPP::Event module has been outsourced to the
57 Object::Event module to provide a more generic way for more other
58 modules to register and call event callbacks.
59
60 XML::Writer
61 For writing "XML".
62
63 XML::Parser::Expat
64 For parsing partial "XML" stuff.
65
66 MIME::Base64
67 For SASL authentication
68
69 Authen::SASL
70 For SASL authentication
71
72 Net::LibIDN
73 For stringprep profiles to handle JIDs.
74
75 Digest::SHA
76 For component authentication and old-style authentication.
77
78 And yes, all these are essential for XMPP communication. Even though
79 'instant messaging' and 'presence' is a quite simple problem XMPP
80 somehow was successful at making the task complicated enough to keep me
81 busy for a long time. But all of that time wasn't only for the
82 technology required to get it started, mostly it was for all the quirks,
83 hacks and badly applied "XML" in the protocol which complicated the
84 matter.
85
86 RELEASE NOTES
87 Here are some notes to the last releases (release of this version is at
88 top):
89
90 Version
91 * 0.55
92
93 Bugfixes, see Changes file.
94
95 * 0.54
96
97 Add AnyEvent::XMPP::Ext::Receipts, small bugfixes, see Changes file.
98
99 * 0.53
100
101 Maintenance release. Patches for various small issues, see Changes
102 file.
103
104 * 0.52
105
106 Maintenance release.
107
108 * 0.51
109
110 Maintenance release. Added a patch which fixes Object::Event
111 compatibility and another fix w.r.t. memory leak in the parser. And
112 added the original node to AnyEvent::XMPP::IM::Message (thanks go to
113 [email protected]).
114
115 NOTE: Version 0.6 of AnyEvent::XMPP will be API incompatible! If you
116 are already eager to try the new version out contact me!
117
118 * 0.5
119
120 Maintenance release. Added a patch from Marcus Dubois for
121 Ext::Pubsub. Also fixed some memleaks in AnyEvent::XMPP::Parser.
122
123 Also wanted to note that the next version of AnyEvent::XMPP will
124 have an incompatible API. If you are eager to try out the new
125 complete rewrite of AnyEvent::XMPP contact me.
126
127 * 0.4
128
129 Minor fixes and feature enhancements: Added old_style_ssl option for
130 direct port 5223 SSL connections. Providing 'get_own_contact' for
131 keeping track of own resources.
132
133 The AnyEvent::XMPP::Ext::MUC extension was rewritten and provides a
134 more sane API now.
135
136 For details consult the Changes file in the distribution.
137
138 * 0.3
139
140 Fixed some small bugs and improved documentation a bit, especially
141 w.r.t. parameter passing of host and ports.
142
143 * 0.2
144
145 Renamed module from Net::XMPP2 to AnyEvent::XMPP. Net::XMPP2 is
146 herby deprecated!
147
148 Rewrote the low-level socket stuff to use AnyEvent::Socket and
149 AnyEvent::Handle. Removed blocking write functionality, which can't
150 be supported that easily with AnyEvent::Handle (however, if you want
151 to wait until the send-buffer is empty you best use the
152 "send_buffer_empty" event of AnyEvent::XMPP::Connection).
153
154 For more details consult the Changes file of the AnyEvent::XMPP
155 distribution.
156
157 * older
158
159 For older release notes please have a look at the Changes file or
160 CPAN.
161
162 TODO
163 There are still lots of items on the TODO list (see also the TODO file
164 in the distribution of AnyEvent::XMPP).
165
166 TEST SUITE
167 If you are a developer and want to test either a server or maybe just
168 whether this module passes some basic tests you might want to run the
169 developer test suite.
170
171 This test suite is not enabled by default because it requires some human
172 interaction to set it up, please see AnyEvent::XMPP::TestClient for
173 hints about the setup procedure for the test suite.
174
175 I wrote the test suite mostly because I wanted to make sure I didn't
176 break something essential before a release. The tests don't cover
177 everything and I don't plan to write a test for every single function in
178 the API, that would slow down development considerably for me. But I
179 hope that some grave show stopper bugs in releases are prevented with
180 this test suite.
181
182 The tests are also useful if you want to test a server implementation.
183 But there are maybe of course conformance issues with AnyEvent::XMPP
184 itself, so if you find something where AnyEvent::XMPP doesn't conform to
185 the XMPP RFCs or XEPs consult the BUGS section below.
186
187 If you find a server that doesn't handle something correctly but you
188 need to interact with it you are free to implement workarounds and send
189 me a patch, or even ask me whether I might want to look into the issue
190 (I can't guarantee anything here, but I want this module to be as
191 interoperable as possible. But if the implementation of a workaround for
192 some non-conformant software will complicate the code too much I'm
193 probably not going to implement it.).
194
195 Of course, if you find a bug in some server implementation don't forget
196 to file a bugreport to them, one hack less in AnyEvent::XMPP means more
197 time for bug fixing and improvements and new features.
198
199 Why (yet) another XMPP module?
200 The main outstanding feature of this module in comparison to the other
201 XMPP (aka Jabber) modules out there is the support for AnyEvent.
202 AnyEvent permits you to use this module together with other I/O event
203 based programs and libraries (ie. Gtk2 or Event).
204
205 The other modules could often only be integrated in those applications
206 or libraries by using threads. I decided to write this module because I
207 think CPAN lacks an event based XMPP module. Threads are unfortunately
208 not an alternative in Perl at the moment due the limited threading
209 functionality they provide and the global speed hit. I also think that a
210 simple event based I/O framework might be a bit easier to handle than
211 threads.
212
213 Another thing was that I didn't like the APIs of the other modules. In
214 AnyEvent::XMPP I try to provide low level modules for speaking XMPP as
215 defined in RFC 3920 and RFC 3921 (see also AnyEvent::XMPP::Connection
216 and AnyEvent::XMPP::IM::Connection). But I also try to provide a high
217 level API for easier usage for instant messaging tasks and clients (eg.
218 AnyEvent::XMPP::Client).
219
220 Supported extensions
221 See AnyEvent::XMPP::Ext for a list.
222
223 EXAMPLES
224 Following examples are included in this distribution:
225
226 samples/simple_example_1
227 This example script just connects to a server and sends a message
228 and also displays incoming messages on stdout.
229
230 samples/conference_lister
231 See below.
232
233 samples/room_lister
234 See below.
235
236 samples/room_lister_stat
237 These three scripts implements a global room scan.
238 "conference_lister" takes a list of servers (the file is called
239 "servers.xml" which has the same format as the xml file at
240 <http://www.jabber.org/servers.xml>). It then scans all servers for
241 chat room services and lists them into a file "conferences.stor",
242 which is a Storable dump.
243
244 "room_lister" then reads that file and queries all services for
245 rooms, and then all rooms for their occupants. The output file is
246 "room_data.stor", also a Storable dump, which in turn can be read
247 with "room_lister_stat", which transform the data structures into
248 something human readable.
249
250 These scripts are a bit hacky and quite complicated, but maybe it's
251 of any value for someone. You might note "EVQ.pm" in samples which
252 is a module that handles request-throttling (You don't want to flood
253 the server and risk getting the admins attention :).
254
255 samples/simple_component
256 This is a (basic) skeleton for a jabber component.
257
258 samples/simple_oob_retriever
259 This is a simple out of band file transfer receiver bot. It uses
260 "curl" to fetch the files and also has the sample functionality of
261 sending a file url for someone who sends the bot a 'send <filename>'
262 message.
263
264 samples/simple_register_example
265 This is a example script which allows you to register, unregister
266 and change your password for accounts. Execute it without arguments
267 for more details.
268
269 samples/disco_info
270 This is a small example tool that allows you to fetch the software
271 version, disco info and disco items information about a JID.
272
273 samples/talkbot
274 This is a simple bot that will read lines from a file and recite
275 them when you send it a message. It will also automatically allow
276 you to subscribe to it. Start it without commandline arguments to be
277 informed about the usage.
278
279 samples/retrieve_roster
280 This is a simple example script that will retrieve the roster for an
281 account and print it to stdout. You start it like this:
282
283 samples/# ./retrieve_roster <jid> <password>
284
285 samples/display_avatar
286 This is just a small example which should display the avatar of the
287 account you connect to. It can be used like this:
288
289 samples/# ./display_avatar <jid> <password>
290
291 For others, which the author might forgot or didn't want to list here
292 see the "samples/" directory.
293
294 More examples will be included in later releases, please feel free to
295 ask the "AUTHOR" if you have any questions about the API. There is also
296 an IRC channel, see "SUPPORT".
297
298 AUTHOR
299 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
300
301 BUGS
302 Please note that I'm currently (July 2007) the only developer on this
303 project and I'm very busy with my studies in Computer Science. If you
304 want to ease my workload or want timely releases, please send me patches
305 instead of bug reports or feature requests. I won't forget the reports
306 or requests if you can't or didn't send patches, but I can't gurantee
307 immediate response. But I will of course try to fix/implement them as
308 soon as possible!
309
310 Also try to be as precise as possible with bug reports, if you can't
311 send a patch, it would be best if you find out which code doesn't work
312 and tell me why.
313
314 Please report any bugs or feature requests to "bug-net-xmpp2 at
315 rt.cpan.org", or through the web interface at
316 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-XMPP>. I will
317 be notified and then you'll automatically be notified of progress on
318 your bug as I make changes.
319
320 SUPPORT
321 You can find documentation for this module with the perldoc command.
322
323 perldoc AnyEvent::XMPP
324
325 You can also look for information at:
326
327 * IRC: AnyEvent::XMPP IRC Channel
328
329 IRC Network: http://freenode.net/
330 Server : chat.freenode.net
331 Channel : #ae_xmpp
332
333 Feel free to join and ask questions!
334
335 * AnyEvent::XMPP Project Site
336
337 <http://www.ta-sa.org/net_xmpp2>
338
339 * AnnoCPAN: Annotated CPAN documentation
340
341 <http://annocpan.org/dist/AnyEvent-XMPP>
342
343 * CPAN Ratings
344
345 <http://cpanratings.perl.org/d/AnyEvent-XMPP>
346
347 * RT: CPAN's request tracker
348
349 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=AnyEvent-XMPP>
350
351 * Search CPAN
352
353 <http://search.cpan.org/dist/AnyEvent-XMPP>
354
355 ACKNOWLEDGEMENTS
356 Thanks to the XSF for the development of an open instant messaging
357 protocol (even though it uses "XML").
358
359 And thanks to all people who had to listen to my desperate curses about
360 the brokenness/braindeadness of XMPP. Without you I would've never
361 brought this module to a usable state.
362
363 Thanks to:
364
365 * J. Cameijo Cerdeira
366
367 For pointing out a serious bug in "split_jid" in
368 AnyEvent::XMPP::Util and suggesting to add a timeout argument to the
369 "connect" method of AnyEvent::XMPP::SimpleConnection.
370
371 * Carlo von Loesch (aka lynX) <http://www.psyced.org/>
372
373 For pointing out some typos.
374
375 * All other people ..
376
377 ... I mentioned in the CONTRIBUTORS file which comes with the
378 AnyEvent::XMPP distribution.
379
380 COPYRIGHT & LICENSE
381 Copyright 2007, 2008 Robin Redeker, all rights reserved.
382
383 This program is free software; you can redistribute it and/or modify it
384 under the same terms as Perl itself.
385