AnyEvent::XMPP::Writer man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

AnyEvent::XMPP::WriterUser Contributed Perl DocumentaAnyEvent::XMPP::Writer(3)

NAME
       AnyEvent::XMPP::Writer - "XML" writer for XMPP

SYNOPSIS
	  use AnyEvent::XMPP::Writer;
	  ...

DESCRIPTION
       This module contains some helper functions for writing XMPP "XML",
       which is not real XML at all ;-( I use XML::Writer and tune it until it
       creates "XML" that is accepted by most servers propably (all of the
       XMPP servers I tested should work (jabberd14, jabberd2, ejabberd,
       googletalk).

       I hope the semantics of XML::Writer don't change much in the future,
       but if they do and you run into problems, please report them!

       The whole "XML" concept of XMPP is fundamentally broken anyway. It's
       supposed to be an subset of XML. But a subset of XML productions is not
       XML. Strictly speaking you need a special XMPP "XML" parser and writer
       to be 100% conformant.

       On top of that XMPP requires you to parse these partial "XML"
       documents.  But a partial XML document is not well-formed, heck, it's
       not even a XML document!	 And a parser should bail out with an error.
       But XMPP doesn't care, it just relies on implementation dependend
       behaviour of chunked parsing modes for SAX parsing.  This functionality
       isn't even specified by the XML recommendation in any way.  The
       recommendation even says that it's undefined what happens if you
       process not-well-formed XML documents.

       But I try to be as XMPP "XML" conformant as possible (it should be
       around 99-100%).	 But it's hard to say what XML is conformant, as the
       specifications of XMPP "XML" and XML are contradicting. For example
       XMPP also says you only have to generated and accept UTF-8 encodings of
       XML, but the XML recommendation says that each parser has to accept
       UTF-8 and UTF-16. So, what do you do? Do you use a XML conformant
       parser or do you write your own?

       I'm using XML::Parser::Expat because expat knows how to parse broken
       (aka 'partial') "XML" documents, as XMPP requires. Another argument is
       that if you capture a XMPP conversation to the end, and even if a
       '</stream:stream>' tag was captured, you wont have a valid XML
       document. The problem is that you have to resent a <stream> tag after
       TLS and SASL authentication each! Awww... I'm repeating myself.

       But well... AnyEvent::XMPP does it's best with expat to cope with the
       fundamental brokeness of "XML" in XMPP.

       Back to the issue with "XML" generation: I've discoverd that many XMPP
       servers (eg.  jabberd14 and ejabberd) have problems with XML
       namespaces. Thats the reason why I'm assigning the namespace prefixes
       manually: The servers just don't accept validly namespaced XML. The
       draft 3921bis does even state that a client SHOULD generate a 'stream'
       prefix for the <stream> tag.

       I advice you to explicitly set the namespaces too if you generate "XML"
       for XMPP yourself, at least until all or most of the XMPP servers have
       been fixed.  Which might take some years :-) And maybe will happen
       never.

       And another note: As XMPP requires all predefined entity characters to
       be escaped in character data you need a "XML" writer that will escape
       everything:

	  RFC 3920 - 11.1.  Restrictions:

	    character data or attribute values containing unescaped characters
	    that map to the predefined entities (Section 4.6 therein);
	    such characters MUST be escaped

       This means: You have to escape '>' in the character data. I don't know
       whether XML::Writer does that. And I honestly don't care much about
       this. XMPP is broken by design and I have barely time to writer my own
       XML parsers and writers to suit their sick taste of "XML". (Do I repeat
       myself?)

       I would be happy if they finally say (in RFC3920): "XMPP is NOT XML.
       It's just XML-like, and some XML utilities allow you to process this
       kind of XML.".

METHODS
       new (%args)
	   This methods takes following arguments:

	   write_cb
	       The callback that is called when a XML stanza was completely
	       written and is ready for transfer. The first argument of the
	       callback will be the character data to send to the socket.

	   And calls "init".

       init
	   (Re)initializes the writer.

       flush ()
	   This method flushes the internal write buffer and will invoke the
	   "write_cb" callback. (see also "new ()" above)

       send_init_stream ($language, $domain, $namespace)
	   This method will generate a XMPP stream header. $domain has to be
	   the domain of the server (or endpoint) we want to connect to.

	   $namespace is the namespace URI or the tag (from
	   AnyEvent::XMPP::Namespaces) for the stream namespace. (This is used
	   by AnyEvent::XMPP::Component to connect as component to a server).
	   $namespace can also be undefined, in this case the "client"
	   namespace will be used.

       send_whitespace_ping
	   This method sends a single space to the server.

       send_handshake ($streamid, $secret)
	   This method sends a component handshake. Please note that $secret
	   must be XML escaped!

       send_end_of_stream
	   Sends end of the stream.

       send_sasl_auth ($mechanisms, $user, $hostname, $pass)
	   This methods sends the start of a SASL authentication. $mechanisms
	   is an array reference, containing the mechanism names that are to
	   be tried.

       send_sasl_response ($challenge)
	   This method generated the SASL authentication response to a
	   $challenge.	You must not call this method without calling
	   "send_sasl_auth ()" before.

       send_starttls
	   Sends the starttls command to the server.

       send_iq ($id, $type, $create_cb, %attrs)
	   This method sends an IQ stanza of type $type (to be compliant only
	   use: 'get', 'set', 'result' and 'error').

	   If $create_cb is a code reference it will be called with an
	   XML::Writer instance as first argument, which must be used to fill
	   the IQ stanza. The XML::Writer is in UNSAFE mode, so you can safely
	   use "raw()" to write out XML.

	   $create_cb is a hash reference the hash will be used as key=>value
	   arguments for the "simxml" function defined in
	   AnyEvent::XMPP::Util. "simxml" will then be used to generate the
	   contents of the IQ stanza. (This is very convenient when you want
	   to write the contents of stanzas in the code and don't want to
	   build a DOM tree yourself...).

	   If $create_cb is an array reference it's elements will be
	   interpreted as single $create_cb argument (which can either be a
	   hash reference or code reference themself) and executed
	   sequentially.

	   If $create_cb is undefined an empty tag will be generated.

	   Example:

	      $writer->send_iq ('newid', 'get', {
		 defns => 'version',
		 node  => { name => 'query', ns => 'version' }
	      }, to => 'jabber.org')

	   %attrs should have further attributes for the IQ stanza tag.	 For
	   example 'to' or 'from'. If the %attrs contain a 'lang' attribute it
	   will be put into the 'xml' namespace. If the 'to' attribute
	   contains an undef it will be omitted.

	   $id is the id to give this IQ stanza and is mandatory in this API.

	   Please note that all attribute values and character data will be
	   filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).

       send_presence ($id, $type, $create_cb, %attrs)
	   Sends a presence stanza.

	   $create_cb has the same meaning as for "send_iq".  %attrs will let
	   you pass further optional arguments like 'to'.

	   $type is the type of the presence, which may be one of:

	      unavailable, subscribe, subscribed, unsubscribe, unsubscribed, probe, error

	   Or undef, in case you want to send a 'normal' presence.  Or
	   something completely different if you don't like the RFC 3921 :-)

	   %attrs contains further attributes for the presence tag or may
	   contain one of the following exceptional keys:

	   If %attrs contains a 'show' key: a child xml tag with that name
	   will be generated with the value as the content, which should be
	   one of 'away', 'chat', 'dnd' and 'xa'.  If it contains an undefined
	   value no such tag will be generated, which usually means that the
	   'available' presence is meant.

	   If %attrs contains a 'status' key: a child xml tag with that name
	   will be generated with the value as content. If the value of the
	   'status' key is an hash reference the keys will be interpreted as
	   language identifiers for the xml:lang attribute of each status
	   element. If one of these keys is the empty string '' no xml:lang
	   attribute will be generated for it. The values will be the
	   character content of the status tags.

	   If %attrs contains a 'priority' key: a child xml tag with that name
	   will be generated with the value as content, which must be a number
	   between -128 and +127.

	   Note: If $create_cb is undefined and one of the above attributes
	   (show, status or priority) were given, the generates presence tag
	   won't be empty.

	   Please note that all attribute values and character data will be
	   filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).

       send_message ($id, $to, $type, $create_cb, %attrs)
	   Sends a message stanza.

	   $to is the destination JID of the message. $type is the type of the
	   message, and if $type is undefined it will default to 'chat'.
	   $type must be one of the following: 'chat', 'error', 'groupchat',
	   'headline' or 'normal'.

	   $create_cb has the same meaning as in "send_iq".

	   %attrs contains further attributes for the message tag or may
	   contain one of the following exceptional keys:

	   If %attrs contains a 'body' key: a child xml tag with that name
	   will be generated with the value as content. If the value of the
	   'body' key is an hash reference the keys will be interpreted as
	   language identifiers for the xml:lang attribute of each body
	   element. If one of these keys is the empty string '' no xml:lang
	   attribute will be generated for it. The values will be the
	   character content of the body tags.

	   If %attrs contains a 'subject' key: a child xml tag with that name
	   will be generated with the value as content. If the value of the
	   'subject' key is an hash reference the keys will be interpreted as
	   language identifiers for the xml:lang attribute of each subject
	   element. If one of these keys is the empty string '' no xml:lang
	   attribute will be generated for it. The values will be the
	   character content of the subject tags.

	   If %attrs contains a 'thread' key: a child xml tag with that name
	   will be generated and the value will be the character content.

	   Please note that all attribute values and character data will be
	   filtered by "filter_xml_chars" (see also AnyEvent::XMPP::Util).

       write_error_tag ($error_stanza_node, $error_type, $error)
	   $error_type is one of 'cancel', 'continue', 'modify', 'auth' and
	   'wait'.  $error is the name of the error tag child element. If
	   $error is one of the following:

	      'bad-request', 'conflict', 'feature-not-implemented', 'forbidden', 'gone',
	      'internal-server-error', 'item-not-found', 'jid-malformed', 'not-acceptable',
	      'not-allowed', 'not-authorized', 'payment-required', 'recipient-unavailable',
	      'redirect', 'registration-required', 'remote-server-not-found',
	      'remote-server-timeout', 'resource-constraint', 'service-unavailable',
	      'subscription-required', 'undefined-condition', 'unexpected-request'

	   then a default can be select for $error_type, and the argument can
	   be undefined.

	   Note: This method is currently a bit limited in the generation of
	   the xml for the errors, if you need more please contact me.

AUTHOR
       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"

COPYRIGHT & LICENSE
       Copyright 2007, 2008 Robin Redeker, all rights reserved.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.14.1			  2009-08-14	     AnyEvent::XMPP::Writer(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net