Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AnyEvent::XMPP(3)     User Contributed Perl Documentation    AnyEvent::XMPP(3)

NAME
       AnyEvent::XMPP -	An implementation of the XMPP Protocol

VERSION
       Version 0.55

SYNOPSIS
	  use AnyEvent::XMPP::Connection;

       or:

	  use AnyEvent::XMPP::IM::Connection;

       or:

	  use AnyEvent::XMPP::Client;

DESCRIPTION
       This is the head	module of the AnyEvent::XMPP XMPP client protocol (as
       described in RFC	3920 and RFC 3921) framework.

       AnyEvent::XMPP::Connection is a RFC 3920	conforming "XML" stream
       implementation for clients, which handles TCP connect up	to the
       resource	binding. And provides low level	access to the XML nodes	on the
       XML stream along	with some high level methods to	send the predefined
       XML stanzas.

       AnyEvent::XMPP::IM::Connection is a more	high level module, which is
       derived from AnyEvent::XMPP::Connection.	It handles all the instant
       messaging client	functionality described	in RFC 3921.

       AnyEvent::XMPP::Client is a multi account client	class. It manages
       connections to multiple XMPP accounts and tries to offer	a nice high
       level interface to XMPP communication.

       For a list of "Supported	extensions" see	below.

       There are also other modules in this distribution, for example:
       AnyEvent::XMPP::Util, AnyEvent::XMPP::Writer, AnyEvent::XMPP::Parser
       and those I forgot :-) Those modules might be helpful and/or required
       if you want to use this framework for XMPP.

       See also	AnyEvent::XMPP::Writer for a discussion	about the brokenness
       of XML in the XMPP specification.

       If you have any questions or seek for help look below under "SUPPORT".

REQUIREMENTS
       One of the major	drawbacks I see	for AnyEvent::XMPP is the long list of
       required	modules	to make	it work.

       AnyEvent
	   For the I/O events, timers, TCP, TLS, DNS and I/O buffering.

       Object::Event
	   The former AnyEvent::XMPP::Event module has been outsourced to the
	   Object::Event module	to provide a more generic way for more other
	   modules to register and call	event callbacks.

       XML::Writer
	   For writing "XML".

       XML::Parser::Expat
	   For parsing partial "XML" stuff.

       MIME::Base64
	   For SASL authentication

       Authen::SASL
	   For SASL authentication

       Net::LibIDN
	   For stringprep profiles to handle JIDs.

       Digest::SHA
	   For component authentication	and old-style authentication.

       And yes,	all these are essential	for XMPP communication.	Even though
       'instant	messaging' and 'presence' is a quite simple problem XMPP
       somehow was successful at making	the task complicated enough to keep me
       busy for	a long time.  But all of that time wasn't only for the
       technology required to get it started, mostly it	was for	all the
       quirks, hacks and badly applied "XML" in	the protocol which complicated
       the matter.

RELEASE	NOTES
       Here are	some notes to the last releases	(release of this version is at
       top):

   Version
       o   0.55

	   Bugfixes, see Changes file.

       o   0.54

	   Add AnyEvent::XMPP::Ext::Receipts, small bugfixes, see Changes
	   file.

       o   0.53

	   Maintenance release.	Patches	for various small issues, see Changes
	   file.

       o   0.52

	   Maintenance release.

       o   0.51

	   Maintenance release.	Added a	patch which fixes Object::Event
	   compatibility and another fix w.r.t.	memory leak in the parser. And
	   added the original node to AnyEvent::XMPP::IM::Message (thanks go
	   to mons@cpan.org).

	   NOTE: Version 0.6 of	AnyEvent::XMPP will be API incompatible! If
	   you are already eager to try	the new	version	out contact me!

       o   0.5

	   Maintenance release.	Added a	patch from Marcus Dubois for
	   Ext::Pubsub.	 Also fixed some memleaks in AnyEvent::XMPP::Parser.

	   Also	wanted to note that the	next version of	AnyEvent::XMPP will
	   have	an incompatible	API. If	you are	eager to try out the new
	   complete rewrite of AnyEvent::XMPP contact me.

       o   0.4

	   Minor fixes and feature enhancements: Added old_style_ssl option
	   for direct port 5223	SSL connections. Providing 'get_own_contact'
	   for keeping track of	own resources.

	   The AnyEvent::XMPP::Ext::MUC	extension was rewritten	and provides a
	   more	sane API now.

	   For details consult the Changes file	in the distribution.

       o   0.3

	   Fixed some small bugs and improved documentation a bit, especially
	   w.r.t.  parameter passing of	host and ports.

       o   0.2

	   Renamed module from Net::XMPP2 to AnyEvent::XMPP. Net::XMPP2	is
	   herby deprecated!

	   Rewrote the low-level socket	stuff to use AnyEvent::Socket and
	   AnyEvent::Handle.  Removed blocking write functionality, which
	   can't be supported that easily with AnyEvent::Handle	(however, if
	   you want to wait until the send-buffer is empty you best use	the
	   "send_buffer_empty" event of	AnyEvent::XMPP::Connection).

	   For more details consult the	Changes	file of	the AnyEvent::XMPP
	   distribution.

       o   older

	   For older release notes please have a look at the Changes file or
	   CPAN.

   TODO
       There are still lots of items on	the TODO list (see also	the TODO file
       in the distribution of AnyEvent::XMPP).

TEST SUITE
       If you are a developer and want to test either a	server or maybe	just
       whether this module passes some basic tests you might want to run the
       developer test suite.

       This test suite is not enabled by default because it requires some
       human interaction to set	it up, please see AnyEvent::XMPP::TestClient
       for hints about the setup procedure for the test	suite.

       I wrote the test	suite mostly because I wanted to make sure I didn't
       break something essential before	a release. The tests don't cover
       everything and I	don't plan to write a test for every single function
       in the API, that	would slow down	development considerably for me. But I
       hope that some grave show stopper bugs in releases are prevented	with
       this test suite.

       The tests are also useful if you	want to	test a server implementation.
       But there are maybe of course conformance issues	with AnyEvent::XMPP
       itself, so if you find something	where AnyEvent::XMPP doesn't conform
       to the XMPP RFCs	or XEPs	consult	the BUGS section below.

       If you find a server that doesn't handle	something correctly but	you
       need to interact	with it	you are	free to	implement workarounds and send
       me a patch, or even ask me whether I might want to look into the	issue
       (I can't	guarantee anything here, but I want this module	to be as
       interoperable as	possible. But if the implementation of a workaround
       for some	non-conformant software	will complicate	the code too much I'm
       probably	not going to implement it.).

       Of course, if you find a	bug in some server implementation don't	forget
       to file a bugreport to them, one	hack less in AnyEvent::XMPP means more
       time for	bug fixing and improvements and	new features.

Why (yet) another XMPP module?
       The main	outstanding feature of this module in comparison to the	other
       XMPP (aka Jabber) modules out there is the support for AnyEvent.
       AnyEvent	permits	you to use this	module together	with other I/O event
       based programs and libraries (ie. Gtk2 or Event).

       The other modules could often only be integrated	in those applications
       or libraries by using threads. I	decided	to write this module because I
       think CPAN lacks	an event based XMPP module. Threads are	unfortunately
       not an alternative in Perl at the moment	due the	limited	threading
       functionality they provide and the global speed hit. I also think that
       a simple	event based I/O	framework might	be a bit easier	to handle than
       threads.

       Another thing was that I	didn't like the	APIs of	the other modules. In
       AnyEvent::XMPP I	try to provide low level modules for speaking XMPP as
       defined in RFC 3920 and RFC 3921	(see also AnyEvent::XMPP::Connection
       and AnyEvent::XMPP::IM::Connection). But	I also try to provide a	high
       level API for easier usage for instant messaging	tasks and clients (eg.
       AnyEvent::XMPP::Client).

Supported extensions
       See AnyEvent::XMPP::Ext for a list.

EXAMPLES
       Following examples are included in this distribution:

       samples/simple_example_1
	   This	example	script just connects to	a server and sends a message
	   and also displays incoming messages on stdout.

       samples/conference_lister
	   See below.

       samples/room_lister
	   See below.

       samples/room_lister_stat
	   These three scripts implements a global room	scan.
	   "conference_lister" takes a list of servers (the file is called
	   "servers.xml" which has the same format as the xml file at
	   <http://www.jabber.org/servers.xml>). It then scans all servers for
	   chat	room services and lists	them into a file "conferences.stor",
	   which is a Storable dump.

	   "room_lister" then reads that file and queries all services for
	   rooms, and then all rooms for their occupants. The output file is
	   "room_data.stor", also a Storable dump, which in turn can be	read
	   with	"room_lister_stat", which transform the	data structures	into
	   something human readable.

	   These scripts are a bit hacky and quite complicated,	but maybe it's
	   of any value	for someone. You might note "EVQ.pm" in	samples	which
	   is a	module that handles request-throttling (You don't want to
	   flood the server and	risk getting the admins	attention :).

       samples/simple_component
	   This	is a (basic) skeleton for a jabber component.

       samples/simple_oob_retriever
	   This	is a simple out	of band	file transfer receiver bot.  It	uses
	   "curl" to fetch the files and also has the sample functionality of
	   sending a file url for someone who sends the	bot a 'send
	   <filename>' message.

       samples/simple_register_example
	   This	is a example script which allows you to	register, unregister
	   and change your password for	accounts. Execute it without arguments
	   for more details.

       samples/disco_info
	   This	is a small example tool	that allows you	to fetch the software
	   version, disco info and disco items information about a JID.

       samples/talkbot
	   This	is a simple bot	that will read lines from a file and recite
	   them	when you send it a message. It will also automatically allow
	   you to subscribe to it. Start it without commandline	arguments to
	   be informed about the usage.

       samples/retrieve_roster
	   This	is a simple example script that	will retrieve the roster for
	   an account and print	it to stdout. You start	it like	this:

	      samples/#	./retrieve_roster <jid>	<password>

       samples/display_avatar
	   This	is just	a small	example	which should display the avatar	of the
	   account you connect to. It can be used like this:

	      samples/#	./display_avatar <jid> <password>

       For others, which the author might forgot or didn't want	to list	here
       see the "samples/" directory.

       More examples will be included in later releases, please	feel free to
       ask the "AUTHOR"	if you have any	questions about	the API. There is also
       an IRC channel, see "SUPPORT".

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

BUGS
       Please note that	I'm currently (July 2007) the only developer on	this
       project and I'm very busy with my studies in Computer Science. If you
       want to ease my workload	or want	timely releases, please	send me
       patches instead of bug reports or feature requests. I won't forget the
       reports or requests if you can't	or didn't send patches,	but I can't
       gurantee	immediate response. But	I will of course try to	fix/implement
       them as soon as possible!

       Also try	to be as precise as possible with bug reports, if you can't
       send a patch, it	would be best if you find out which code doesn't work
       and tell	me why.

       Please report any bugs or feature requests to "bug-net-xmpp2 at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-XMPP>.	I will
       be notified and then you'll automatically be notified of	progress on
       your bug	as I make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc AnyEvent::XMPP

       You can also look for information at:

       o   IRC:	AnyEvent::XMPP IRC Channel

	     IRC Network: http://freenode.net/
	     Server	: chat.freenode.net
	     Channel	: #ae_xmpp

	     Feel free to join and ask questions!

       o   AnyEvent::XMPP Project Site

	   <http://www.ta-sa.org/net_xmpp2>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/AnyEvent-XMPP>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/AnyEvent-XMPP>

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=AnyEvent-XMPP>

       o   Search CPAN

	   <http://search.cpan.org/dist/AnyEvent-XMPP>

ACKNOWLEDGEMENTS
       Thanks to the XSF for the development of	an open	instant	messaging
       protocol	(even though it	uses "XML").

       And thanks to all people	who had	to listen to my	desperate curses about
       the brokenness/braindeadness of XMPP. Without you I would've never
       brought this module to a	usable state.

       Thanks to:

       o   J. Cameijo Cerdeira

	   For pointing	out a serious bug in "split_jid" in
	   AnyEvent::XMPP::Util	and suggesting to add a	timeout	argument to
	   the "connect" method	of AnyEvent::XMPP::SimpleConnection.

       o   Carlo von Loesch (aka lynX) <http://www.psyced.org/>

	   For pointing	out some typos.

       o   All other people ..

	   ... I mentioned in the CONTRIBUTORS file which comes	with the
	   AnyEvent::XMPP distribution.

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.32.0			  2014-03-01		     AnyEvent::XMPP(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | REQUIREMENTS | RELEASE NOTES | TEST SUITE | Why (yet) another XMPP module? | Supported extensions | EXAMPLES | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AnyEvent::XMPP&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help