… | |
… | |
8 | use Net::XMPP2::Connection; |
8 | use Net::XMPP2::Connection; |
9 | |
9 | |
10 | or: |
10 | or: |
11 | |
11 | |
12 | use Net::XMPP2::IM::Connection; |
12 | use Net::XMPP2::IM::Connection; |
|
|
13 | |
|
|
14 | or: |
|
|
15 | |
|
|
16 | use Net::XMPP2::Client; |
13 | |
17 | |
14 | DESCRIPTION |
18 | DESCRIPTION |
15 | 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 |
16 | described in RFC 3920 and RFC 3921) framework. |
20 | described in RFC 3920 and RFC 3921) framework. |
17 | |
21 | |
… | |
… | |
23 | |
27 | |
24 | Net::XMPP2::IM::Connection is a more highlevel module, which is derived |
28 | Net::XMPP2::IM::Connection is a more highlevel module, which is derived |
25 | from Net::XMPP2::Connection. It handles all the instant messaging client |
29 | from Net::XMPP2::Connection. It handles all the instant messaging client |
26 | functionality described in RFC 3921. |
30 | functionality described in RFC 3921. |
27 | |
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 |
|
|
34 | highlevel interface to XMPP communication. |
|
|
35 | |
28 | For a list of "Supportet extensions" see below. |
36 | For a list of "Supportet extensions" see below. |
29 | |
37 | |
30 | There are also other modules in this distribution, for example: |
38 | There are also other modules in this distribution, for example: |
31 | 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 |
32 | 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 |
33 | use this framework for XMPP. |
41 | use this framework for XMPP. |
34 | |
42 | |
35 | See also Net::XMPP2::Writer for a discussion about the brokeness of XML |
43 | See also Net::XMPP2::Writer for a discussion about the brokeness of XML |
36 | in the XMPP specification. |
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 | And yes, all these are essential for XMPP communication. Even thought |
|
|
77 | 'instant messaging' and 'presence' is a quite simple problem XMPP |
|
|
78 | somehow was successful at complicating the task enough to keep me busy |
|
|
79 | for a long time. But all that time wasn't only for the technology |
|
|
80 | required to get it started, mostly it was for all the quirks, hacks and |
|
|
81 | badly applied "XML" in the protocol which complicated the matter. |
|
|
82 | |
|
|
83 | RELEASE NOTES |
|
|
84 | Here are some notes to the releases (release of this version is at top): |
|
|
85 | |
|
|
86 | Version |
|
|
87 | * 0.01 |
|
|
88 | 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, |
|
|
90 | missing or faulty code/methods please drop me a mail! See also |
|
|
91 | "BUGS" below. |
|
|
92 | |
|
|
93 | Potential edges when using this module: sparely documented methods, |
|
|
94 | missing functionality and generally bugs bugs and bugs. Even thought |
|
|
95 | this module is in daily usage there are still lots of cases I might |
|
|
96 | have missed. |
|
|
97 | |
|
|
98 | For the next release I'm planning to provide more examples in the |
|
|
99 | documentation and/or samples/ directory, along with bugfixes and |
|
|
100 | enhancements along with some todo items killed from the TODO file. |
|
|
101 | |
|
|
102 | TODO |
|
|
103 | There are still lots of items on the TODO list (see also the TODO file |
|
|
104 | in the distribution of Net::XMPP2). |
37 | |
105 | |
38 | Why (yet) another XMPP module? |
106 | Why (yet) another XMPP module? |
39 | The main outstanding feature of this module in comparsion to the other |
107 | The main outstanding feature of this module in comparsion to the other |
40 | XMPP (aka Jabber) modules out there is the support for AnyEvent. |
108 | XMPP (aka Jabber) modules out there is the support for AnyEvent. |
41 | AnyEvent permits you to use this module together with other I/O event |
109 | AnyEvent permits you to use this module together with other I/O event |
42 | based programs and libraries (ie. Gtk2 or Event). |
110 | based programs and libraries (ie. Gtk2 or Event). |
43 | |
111 | |
44 | The other modules could often only be integrated in those applications |
112 | The other modules could often only be integrated in those applications |
45 | or librarys by using threads. I decided to write this module because i |
113 | or librarys by using threads. I decided to write this module because I |
46 | think CPAN lacks an event based XMPP module. Threads are unfortunately |
114 | think CPAN lacks an event based XMPP module. Threads are unfortunately |
47 | not an alternative in Perl at the moment due the limited threading |
115 | not an alternative in Perl at the moment due the limited threading |
48 | functionality they provide and the global speed hit. I also think that a |
116 | functionality they provide and the global speed hit. I also think that a |
49 | simple event based I/O framework might be a bit easier to handle than |
117 | simple event based I/O framework might be a bit easier to handle than |
50 | threads. |
118 | threads. |
51 | |
119 | |
52 | Another thing was that I didn't like the APIs of the other modules. In |
120 | Another thing was that I didn't like the APIs of the other modules. In |
53 | Net::XMPP2 I try to provide low level modules for speaking XMPP as |
121 | Net::XMPP2 I try to provide low level modules for speaking XMPP as |
54 | defined in RFC 3920 and RFC 3921 (see also Net::XMPP2::Connection and |
122 | defined in RFC 3920 and RFC 3921 (see also Net::XMPP2::Connection and |
55 | Net::XMPP2::IM::Connection). But I also try to provide a high level API |
123 | Net::XMPP2::IM::Connection). But I also try to provide a high level API |
56 | for easier usage for instant messaging tasks and clients. |
124 | for easier usage for instant messaging tasks and clients (eg. |
|
|
125 | Net::XMPP2::Client). |
57 | |
126 | |
58 | A note about TLS |
127 | A note about TLS |
59 | This module also supports TLS, as the specification of XMPP requires an |
128 | This module also supports TLS, as the specification of XMPP requires an |
60 | implementation to support TLS. |
129 | implementation to support TLS. |
61 | |
130 | |
… | |
… | |
72 | I mainly expect problems where aviable data isn't properly read from the |
141 | I mainly expect problems where aviable data isn't properly read from the |
73 | socket or written to it. You might want to take a look at the |
142 | socket or written to it. You might want to take a look at the |
74 | "debug_send" and "debug_recv" events in Net::XMPP2::Connection. |
143 | "debug_send" and "debug_recv" events in Net::XMPP2::Connection. |
75 | |
144 | |
76 | Supportet extensions |
145 | Supportet extensions |
77 | This is the list of supported XMPP extensions: |
146 | See Net::XMPP2::Ext for a list. |
78 | |
147 | |
79 | XEP-0086 - Error Condition Mappings |
148 | EXAMPLES |
80 | "A mapping to enable legacy entities to correctly handle errors from XMPP-aware entities." |
149 | See "samples/test_client" for a first pointer. More examples will be |
81 | |
150 | included in later releases, please feel free to ask the "AUTHOR" if you |
82 | This extension will enable sending of the old error codes when |
151 | have any questions about the API. There is also an IRC channel, see |
83 | generating a stanza error with for example: |
152 | "SUPPORT". |
84 | Net::XMPP2::Writer::write_error_tag |
|
|
85 | |
|
|
86 | XEP-0077 - In-Band Registration |
|
|
87 | This extension lets you register new accounts "in-band". To use this |
|
|
88 | look at the description of the "register" option to the "new" method |
|
|
89 | of Net::XMPP2::Connection. |
|
|
90 | |
153 | |
91 | AUTHOR |
154 | AUTHOR |
92 | Robin Redeker, "<elmex at ta-sa.org>" |
155 | Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>" |
93 | |
156 | |
94 | BUGS |
157 | BUGS |
|
|
158 | 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 |
|
|
160 | 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 |
|
|
162 | 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. |
|
|
164 | |
|
|
165 | Also try to be as precise as possible with bugreports and best, if you |
|
|
166 | can't send a patch, would be if you find out which code doesn't work and |
|
|
167 | tell me why. |
|
|
168 | |
95 | Please report any bugs or feature requests to "bug-net-xmpp2 at |
169 | Please report any bugs or feature requests to "bug-net-xmpp2 at |
96 | rt.cpan.org", or through the web interface at |
170 | rt.cpan.org", or through the web interface at |
97 | <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be |
171 | <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-XMPP2>. I will be |
98 | notified, and then you'll automatically be notified of progress on your |
172 | notified, and then you'll automatically be notified of progress on your |
99 | bug as I make changes. |
173 | bug as I make changes. |
… | |
… | |
103 | |
177 | |
104 | perldoc Net::XMPP2 |
178 | perldoc Net::XMPP2 |
105 | |
179 | |
106 | You can also look for information at: |
180 | You can also look for information at: |
107 | |
181 | |
|
|
182 | * IRC: Net::XMPP2 IRC Channel |
|
|
183 | IRC Network: http://freenode.net/ |
|
|
184 | Server : chat.freenode.net |
|
|
185 | Channel : #net_xmpp2 |
|
|
186 | |
|
|
187 | Feel free to join and ask questions! |
|
|
188 | |
|
|
189 | * Net::XMPP2 Project Site |
|
|
190 | <http://www.ta-sa.org/> |
|
|
191 | |
108 | * AnnoCPAN: Annotated CPAN documentation |
192 | * AnnoCPAN: Annotated CPAN documentation |
109 | <http://annocpan.org/dist/Net-XMPP2> |
193 | <http://annocpan.org/dist/Net-XMPP2> |
110 | |
194 | |
111 | * CPAN Ratings |
195 | * CPAN Ratings |
112 | <http://cpanratings.perl.org/d/Net-XMPP2> |
196 | <http://cpanratings.perl.org/d/Net-XMPP2> |
… | |
… | |
116 | |
200 | |
117 | * Search CPAN |
201 | * Search CPAN |
118 | <http://search.cpan.org/dist/Net-XMPP2> |
202 | <http://search.cpan.org/dist/Net-XMPP2> |
119 | |
203 | |
120 | ACKNOWLEDGEMENTS |
204 | ACKNOWLEDGEMENTS |
|
|
205 | Thanks to the XSF for the development of an open instant messaging |
|
|
206 | protocol (even thought it uses "XML"). |
|
|
207 | |
|
|
208 | 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 |
|
|
210 | brought this module to a usable state. |
|
|
211 | |
121 | COPYRIGHT & LICENSE |
212 | COPYRIGHT & LICENSE |
122 | Copyright 2007 Robin Redeker, all rights reserved. |
213 | Copyright 2007 Robin Redeker, all rights reserved. |
123 | |
214 | |
124 | This program is free software; you can redistribute it and/or modify it |
215 | This program is free software; you can redistribute it and/or modify it |
125 | under the same terms as Perl itself. |
216 | under the same terms as Perl itself. |