1AnyEvent::XMPP::Writer(U3s)er Contributed Perl DocumentatAinoynEvent::XMPP::Writer(3)
2
3
4

NAME

6       AnyEvent::XMPP::Writer - "XML" writer for XMPP
7

SYNOPSIS

9          use AnyEvent::XMPP::Writer;
10          ...
11

DESCRIPTION

13       This module contains some helper functions for writing XMPP "XML",
14       which is not real XML at all ;-( I use XML::Writer and tune it until it
15       creates "XML" that is accepted by most servers propably (all of the
16       XMPP servers I tested should work (jabberd14, jabberd2, ejabberd,
17       googletalk).
18
19       I hope the semantics of XML::Writer don't change much in the future,
20       but if they do and you run into problems, please report them!
21
22       The whole "XML" concept of XMPP is fundamentally broken anyway. It's
23       supposed to be an subset of XML. But a subset of XML productions is not
24       XML. Strictly speaking you need a special XMPP "XML" parser and writer
25       to be 100% conformant.
26
27       On top of that XMPP requires you to parse these partial "XML"
28       documents.  But a partial XML document is not well-formed, heck, it's
29       not even a XML document!  And a parser should bail out with an error.
30       But XMPP doesn't care, it just relies on implementation dependend
31       behaviour of chunked parsing modes for SAX parsing.  This functionality
32       isn't even specified by the XML recommendation in any way.  The
33       recommendation even says that it's undefined what happens if you
34       process not-well-formed XML documents.
35
36       But I try to be as XMPP "XML" conformant as possible (it should be
37       around 99-100%).  But it's hard to say what XML is conformant, as the
38       specifications of XMPP "XML" and XML are contradicting. For example
39       XMPP also says you only have to generated and accept UTF-8 encodings of
40       XML, but the XML recommendation says that each parser has to accept
41       UTF-8 and UTF-16. So, what do you do? Do you use a XML conformant
42       parser or do you write your own?
43
44       I'm using XML::Parser::Expat because expat knows how to parse broken
45       (aka 'partial') "XML" documents, as XMPP requires. Another argument is
46       that if you capture a XMPP conversation to the end, and even if a
47       '</stream:stream>' tag was captured, you wont have a valid XML
48       document. The problem is that you have to resent a <stream> tag after
49       TLS and SASL authentication each! Awww... I'm repeating myself.
50
51       But well... AnyEvent::XMPP does it's best with expat to cope with the
52       fundamental brokeness of "XML" in XMPP.
53
54       Back to the issue with "XML" generation: I've discoverd that many XMPP
55       servers (eg.  jabberd14 and ejabberd) have problems with XML
56       namespaces. Thats the reason why I'm assigning the namespace prefixes
57       manually: The servers just don't accept validly namespaced XML. The
58       draft 3921bis does even state that a client SHOULD generate a 'stream'
59       prefix for the <stream> tag.
60
61       I advice you to explicitly set the namespaces too if you generate "XML"
62       for XMPP yourself, at least until all or most of the XMPP servers have
63       been fixed.  Which might take some years :-) And maybe will happen
64       never.
65
66       And another note: As XMPP requires all predefined entity characters to
67       be escaped in character data you need a "XML" writer that will escape
68       everything:
69
70          RFC 3920 - 11.1.  Restrictions:
71
72            character data or attribute values containing unescaped characters
73            that map to the predefined entities (Section 4.6 therein);
74            such characters MUST be escaped
75
76       This means: You have to escape '>' in the character data. I don't know
77       whether XML::Writer does that. And I honestly don't care much about
78       this. XMPP is broken by design and I have barely time to writer my own
79       XML parsers and writers to suit their sick taste of "XML". (Do I repeat
80       myself?)
81
82       I would be happy if they finally say (in RFC3920): "XMPP is NOT XML.
83       It's just XML-like, and some XML utilities allow you to process this
84       kind of XML.".
85

METHODS

87       new (%args)
88           This methods takes following arguments:
89
90           write_cb
91               The callback that is called when a XML stanza was completely
92               written and is ready for transfer. The first argument of the
93               callback will be the character data to send to the socket.
94
95           And calls "init".
96
97       init
98           (Re)initializes the writer.
99
100       flush ()
101           This method flushes the internal write buffer and will invoke the
102           "write_cb" callback. (see also "new ()" above)
103
104       send_init_stream ($language, $domain, $namespace)
105           This method will generate a XMPP stream header. $domain has to be
106           the domain of the server (or endpoint) we want to connect to.
107
108           $namespace is the namespace URI or the tag (from
109           AnyEvent::XMPP::Namespaces) for the stream namespace. (This is used
110           by AnyEvent::XMPP::Component to connect as component to a server).
111           $namespace can also be undefined, in this case the "client"
112           namespace will be used.
113
114       send_whitespace_ping
115           This method sends a single space to the server.
116
117       send_handshake ($streamid, $secret)
118           This method sends a component handshake. Please note that $secret
119           must be XML escaped!
120
121       send_end_of_stream
122           Sends end of the stream.
123
124       send_sasl_auth ($mechanisms, $user, $hostname, $pass)
125           This methods sends the start of a SASL authentication. $mechanisms
126           is an array reference, containing the mechanism names that are to
127           be tried.
128
129       send_sasl_response ($challenge)
130           This method generated the SASL authentication response to a
131           $challenge.  You must not call this method without calling
132           "send_sasl_auth ()" before.
133
134       send_starttls
135           Sends the starttls command to the server.
136
137       send_iq ($id, $type, $create_cb, %attrs)
138           This method sends an IQ stanza of type $type (to be compliant only
139           use: 'get', 'set', 'result' and 'error').
140
141           If $create_cb is a code reference it will be called with an
142           XML::Writer instance as first argument, which must be used to fill
143           the IQ stanza. The XML::Writer is in UNSAFE mode, so you can safely
144           use "raw()" to write out XML.
145
146           $create_cb is a hash reference the hash will be used as key=>value
147           arguments for the "simxml" function defined in
148           AnyEvent::XMPP::Util. "simxml" will then be used to generate the
149           contents of the IQ stanza. (This is very convenient when you want
150           to write the contents of stanzas in the code and don't want to
151           build a DOM tree yourself...).
152
153           If $create_cb is an array reference it's elements will be
154           interpreted as single $create_cb argument (which can either be a
155           hash reference or code reference themself) and executed
156           sequentially.
157
158           If $create_cb is undefined an empty tag will be generated.
159
160           Example:
161
162              $writer->send_iq ('newid', 'get', {
163                 defns => 'version',
164                 node  => { name => 'query', ns => 'version' }
165              }, to => 'jabber.org')
166
167           %attrs should have further attributes for the IQ stanza tag.  For
168           example 'to' or 'from'. If the %attrs contain a 'lang' attribute it
169           will be put into the 'xml' namespace. If the 'to' attribute
170           contains an undef it will be omitted.
171
172           $id is the id to give this IQ stanza and is mandatory in this API.
173
174           Please note that all attribute values and character data will be
175           filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).
176
177       send_presence ($id, $type, $create_cb, %attrs)
178           Sends a presence stanza.
179
180           $create_cb has the same meaning as for "send_iq".  %attrs will let
181           you pass further optional arguments like 'to'.
182
183           $type is the type of the presence, which may be one of:
184
185              unavailable, subscribe, subscribed, unsubscribe, unsubscribed, probe, error
186
187           Or undef, in case you want to send a 'normal' presence.  Or
188           something completely different if you don't like the RFC 3921 :-)
189
190           %attrs contains further attributes for the presence tag or may
191           contain one of the following exceptional keys:
192
193           If %attrs contains a 'show' key: a child xml tag with that name
194           will be generated with the value as the content, which should be
195           one of 'away', 'chat', 'dnd' and 'xa'.  If it contains an undefined
196           value no such tag will be generated, which usually means that the
197           'available' presence is meant.
198
199           If %attrs contains a 'status' key: a child xml tag with that name
200           will be generated with the value as content. If the value of the
201           'status' key is an hash reference the keys will be interpreted as
202           language identifiers for the xml:lang attribute of each status
203           element. If one of these keys is the empty string '' no xml:lang
204           attribute will be generated for it. The values will be the
205           character content of the status tags.
206
207           If %attrs contains a 'priority' key: a child xml tag with that name
208           will be generated with the value as content, which must be a number
209           between -128 and +127.
210
211           Note: If $create_cb is undefined and one of the above attributes
212           (show, status or priority) were given, the generates presence tag
213           won't be empty.
214
215           Please note that all attribute values and character data will be
216           filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).
217
218       send_message ($id, $to, $type, $create_cb, %attrs)
219           Sends a message stanza.
220
221           $to is the destination JID of the message. $type is the type of the
222           message, and if $type is undefined it will default to 'chat'.
223           $type must be one of the following: 'chat', 'error', 'groupchat',
224           'headline' or 'normal'.
225
226           $create_cb has the same meaning as in "send_iq".
227
228           %attrs contains further attributes for the message tag or may
229           contain one of the following exceptional keys:
230
231           If %attrs contains a 'body' key: a child xml tag with that name
232           will be generated with the value as content. If the value of the
233           'body' key is an hash reference the keys will be interpreted as
234           language identifiers for the xml:lang attribute of each body
235           element. If one of these keys is the empty string '' no xml:lang
236           attribute will be generated for it. The values will be the
237           character content of the body tags.
238
239           If %attrs contains a 'subject' key: a child xml tag with that name
240           will be generated with the value as content. If the value of the
241           'subject' key is an hash reference the keys will be interpreted as
242           language identifiers for the xml:lang attribute of each subject
243           element. If one of these keys is the empty string '' no xml:lang
244           attribute will be generated for it. The values will be the
245           character content of the subject tags.
246
247           If %attrs contains a 'thread' key: a child xml tag with that name
248           will be generated and the value will be the character content.
249
250           Please note that all attribute values and character data will be
251           filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).
252
253       write_error_tag ($error_stanza_node, $error_type, $error)
254           $error_type is one of 'cancel', 'continue', 'modify', 'auth' and
255           'wait'.  $error is the name of the error tag child element. If
256           $error is one of the following:
257
258              'bad-request', 'conflict', 'feature-not-implemented', 'forbidden', 'gone',
259              'internal-server-error', 'item-not-found', 'jid-malformed', 'not-acceptable',
260              'not-allowed', 'not-authorized', 'payment-required', 'recipient-unavailable',
261              'redirect', 'registration-required', 'remote-server-not-found',
262              'remote-server-timeout', 'resource-constraint', 'service-unavailable',
263              'subscription-required', 'undefined-condition', 'unexpected-request'
264
265           then a default can be select for $error_type, and the argument can
266           be undefined.
267
268           Note: This method is currently a bit limited in the generation of
269           the xml for the errors, if you need more please contact me.
270

AUTHOR

272       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
273
275       Copyright 2007, 2008 Robin Redeker, all rights reserved.
276
277       This program is free software; you can redistribute it and/or modify it
278       under the same terms as Perl itself.
279
280
281
282perl v5.12.0                      2009-08-14         AnyEvent::XMPP::Writer(3)
Impressum