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

FreeBSD Manual Pages

  
 
  

home | help
AnyEvent::XMPP::ConnecUser(Contributed Perl DocumAnyEvent::XMPP::Connection(3)

NAME
       AnyEvent::XMPP::Connection - XML	stream that implements the XMPP	RFC
       3920.

SYNOPSIS
	  use AnyEvent::XMPP::Connection;

	  my $con =
	     AnyEvent::XMPP::Connection->new (
		username => "abc",
		domain => "jabber.org",
		resource => "AnyEvent::XMPP"
	     );

	  $con->reg_cb (stream_ready =>	sub { print "XMPP stream ready!\n" });
	  $con->connect; # will	do non-blocking	connect

DESCRIPTION
       This module represents a	XMPP stream as described in RFC	3920. You can
       issue the basic XMPP XML	stanzas	with methods like "send_iq",
       "send_message" and "send_presence".

       And receive events with the "reg_cb" event framework from the
       connection.

       If you need instant messaging stuff please take a look at
       "AnyEvent::XMPP::IM::Connection".

METHODS
       new (%args)
	   Following arguments can be passed in	%args:

	   language => $tag
	       This should be the language of the human	readable contents that
	       will be transmitted over	the stream. The	default	will be	'en'.

	       Please look in RFC 3066 how $tag	should look like.

	   jid => $jid
	       This can	be used	to set the settings "username",	"domain" (and
	       optionally "resource") from a $jid.

	   username => $username
	       This is your $username (the userpart in the JID);

	       Note: You have to take care that	the stringprep profile for
	       nodes can be applied at:	$username. Otherwise the server	might
	       signal an error.	See AnyEvent::XMPP::Util for utility functions
	       to check	this.

	       NOTE: This field	has no effect if "jid" is given!

	   domain => $domain
	       If you didn't provide a "jid" (see above) you have to set the
	       "username" which	you want to connect as (see above) and the
	       $domain to connect to.

	       NOTE: This field	has no effect if "jid" is given!

	   resource => $resource
	       If this argument	is given $resource will	be passed as desired
	       resource	on resource binding.

	       Note: You have to take care that	the stringprep profile for
	       resources can be	applied	at: $resource. Otherwise the server
	       might signal an error. See AnyEvent::XMPP::Util for utility
	       functions to check this.

	   host	=> $host
	       This parameter specifies	the hostname where we are going	to
	       connect to. The default for this	is the "domain"	of the "jid".

	       NOTE: To	disable	DNS SRV	lookup you need	to specify the port
	       number yourself.	See "port" below.

	   use_host_as_sasl_hostname =>	$bool
	       This is a special parameter for people who might	want to	use
	       GSSAPI SASL mechanism. It will cause the	value of the "host"
	       parameter (see above) to	be passed to the SASL mechanisms,
	       instead of the "domain" of the JID.

	       This flag is provided until support for XEP 0233	is deployed,
	       which will fix the hostname issue w.r.t.	GSSAPI SASL.

	   port	=> $port
	       This is optional, the default value for $port is
	       'xmpp-client=5222', which will used as $service argument	to
	       "tcp_connect" of	AnyEvent::Socket.  NOTE: If you	specify	the
	       port number here	(instead of 'xmpp-client=5222'), no DNS	SRV
	       lookup will be done when	connecting.

	   connect_timeout => $timeout
	       This sets the connection	timeout. If the	socket connect takes
	       too long	a "disconnect" event will be generated with an
	       appropriate error message.  If this argument is not given no
	       timeout is installed for	the connects.

	   password => $password
	       This is the password for	the "username" above.

	   disable_ssl => $bool
	       If $bool	is true	no SSL will be used.

	   old_style_ssl => $bool
	       If $bool	is true	the TLS	handshake will be initiated when the
	       TCP connection was established. This is useful if you have to
	       connect to an old Jabber	server,	with old-style SSL connections
	       on port 5223.

	       But that	practice has been discouraged in XMPP, and a TLS
	       handshake is done after the XML stream has been established.
	       Only use	this option if you know	what you are doing.

	   disable_sasl	=> $bool
	       If $bool	is true	SASL will NOT be used to authenticate with the
	       server, even if it advertises SASL through stream features.
	       Alternative authentication methods will be used,	such as	IQ
	       Auth (XEP-0078) if the server offers it.

	   disable_iq_auth => $bool
	       This disables the use of	IQ Auth	(XEP-0078) for authentication,
	       you might want to exclude it because it's deprecated and
	       insecure. (However, I want to reach a maximum in	compatibility
	       with AnyEvent::XMPP so I'm not disabling	this by	default.

	       See also	"disable_old_jabber_authentication" below.

	   anal_iq_auth	=> $bool
	       This enables the	anal iq	auth mechanism that will first look in
	       the stream features before trying to start iq authentication.
	       Yes, servers don't always advertise what	they can. I only
	       implemented this	option for my test suite.

	   disable_old_jabber_authentication =>	$bool
	       If $bool	is a true value, then the VERY old style
	       authentication method with VERY old jabber server won't be used
	       when a <stream> start tag from the server without version
	       attribute is received.

	       The VERY	old style authentication method	is per default enabled
	       to ensure maximum compatibility with old	jabber
	       implementations.	The old	method works as	follows: When a
	       <stream>	start tag is received from the server with no
	       'version' attribute IQ Auth (XEP-0078) will be initiated	to
	       authenticate with the server.

	       Please note that	the old	authentication method will fail	if
	       "disable_iq_auth" is true.

	   stream_version_override => $version
	       NOTE: Only use if you really know what you are doing!

	       This will override the stream version which is sent in the XMPP
	       stream initiation element. This is currently only used by the
	       tests which set $version	to '0.9' for testing IQ	authentication
	       with ejabberd.

	   whitespace_ping_interval => $interval
	       This will set the whitespace ping interval (in seconds).	The
	       default interval	are 60 seconds.	 You can disable the
	       whitespace ping by setting $interval to 0.

       connect ()
	   Try to connect (non blocking) to the	domain and port	passed in
	   "new".

	   The connection is performed non blocking, so	this method will just
	   trigger the connection process. The event "connect" will be emitted
	   when	the connection was successfully	established.

	   If the connection try was not successful a "disconnect" event will
	   be generated	with an	error message.

	   NOTE: Please	note that you can't reconnect a
	   AnyEvent::XMPP::Connection object. You need to recreate it if you
	   want	to reconnect.

	   NOTE: The "XML" stream initiation is	sent when the connection was
	   successfully	connected.

       is_connected ()
	   Returns true	if the connection is still connected and stanzas can
	   be sent.

       set_default_iq_timeout ($seconds)
	   This	sets the default timeout for IQ	requests. If the timeout runs
	   out the request will	be aborted and the callback called with	a
	   AnyEvent::XMPP::Error::IQ object where the "condition" method
	   returns a special value (see	also "condition" method	of
	   AnyEvent::XMPP::Error::IQ).

	   The default timeout for IQ is 60 seconds.

       send_iq ($type, $create_cb, $result_cb, %attrs)
	   This	method sends an	IQ XMPP	request.

	   If you want to respond to a IQ request you received via the
	   "iq_set_request_xml", and "iq_get_request_xml" events you have to
	   use the "reply_iq_result" or	"reply_iq_error" methods documented
	   below.

	   Please take a look at the documentation for "send_iq" in
	   AnyEvent::XMPP::Writer about	the meaning of $type, $create_cb and
	   %attrs (with	the exception of the 'timeout' key of %attrs, see
	   below).

	   $result_cb will be called when a result was received	or the timeout
	   reached.  The first argument	to $result_cb will be a
	   AnyEvent::XMPP::Node	instance containing the	IQ result stanza
	   contents.

	   If the IQ resulted in a stanza error	the second argument to
	   $result_cb will be "undef" (if the error type was not 'continue')
	   and the third argument will be a AnyEvent::XMPP::Error::IQ object.

	   The timeout can be set by "set_default_iq_timeout" or passed
	   separately in the %attrs array as the value for the key "timeout"
	   (timeout in seconds btw.).

	   This	method returns the newly generated id for this iq request.

       next_iq_id
	   This	method returns the next	IQ id that will	be used.

       reply_iq_result ($req_iq_node, $create_cb, %attrs)
	   This	method will generate a result reply to the iq request
	   "AnyEvent::XMPP::Node" in $req_iq_node.

	   Please take a look at the documentation for "send_iq" in
	   AnyEvent::XMPP::Writer about	the meaning $create_cb and %attrs.

	   Use $create_cb to create the	XML for	the result.

	   The type for	this iq	reply is 'result'.

	   The "to" attribute of the reply stanza will be set to the "from"
	   attribute of	the $req_iq_node. If $req_iq_node had no "from"	node
	   it won't be set. If you want	to overwrite the "to" field just pass
	   it via %attrs.

       reply_iq_error ($req_iq_node, $error_type, $error, %attrs)
	   This	method will generate an	error reply to the iq request
	   "AnyEvent::XMPP::Node" in $req_iq_node.

	   $error_type is one of 'cancel', 'continue', 'modify', 'auth'	and
	   'wait'.  $error is one of the defined error conditions described in
	   "write_error_tag" method of AnyEvent::XMPP::Writer.

	   Please take a look at the documentation for "send_iq" in
	   AnyEvent::XMPP::Writer about	the meaning of %attrs.

	   The type for	this iq	reply is 'error'.

	   The "to" attribute of the reply stanza will be set to the "from"
	   attribute of	the $req_iq_node. If $req_iq_node had no "from"	node
	   it won't be set. If you want	to overwrite the "to" field just pass
	   it via %attrs.

       authenticate
	   This	method should be called	after the "stream_pre_authentication"
	   event was emitted to	continue authentication	of the stream.

	   Usually this	method only has	to be called when you want to register
	   before you authenticate. See	also the documentation of the
	   "stream_pre_authentication" event below.

       send_presence ($type, $create_cb, %attrs)
	   This	method sends a presence	stanza,	for the	meanings of $type,
	   $create_cb and %attrs please	take a look at the documentation for
	   "send_presence" method of AnyEvent::XMPP::Writer.

	   This	methods	does attach an id attribute to the presence stanza and
	   will	return the id that was used (so	you can	react on possible
	   replies).

       send_message ($to, $type, $create_cb, %attrs)
	   This	method sends a message stanza, for the meanings	of $to,	$type,
	   $create_cb and %attrs please	take a look at the documentation for
	   "send_message" method of AnyEvent::XMPP::Writer.

	   This	methods	does attach an id attribute to the message stanza and
	   will	return the id that was used (so	you can	react on possible
	   replies).

       do_rebind ($resource)
	   In case you got a "bind_error" event	and want to retry binding you
	   can call this function to set a new $resource and retry binding.

	   If it fails again you can call this again. Becareful	not to end up
	   in a	loop!

	   If binding was successful the "stream_ready"	event will be
	   generated.

       jid After the stream has	been bound to a	resource the JID can be
	   retrieved via this method.

       features
	   Returns the last received <features>	tag in form of an
	   AnyEvent::XMPP::Node	object.

       stream_id
	   This	is the ID of this stream that was given	us by the server.

EVENTS
       The AnyEvent::XMPP::Connection class is derived from the	Object::Event
       class, and thus inherits	the event callback registering system from it.
       Consult the documentation of Object::Event about	more details.

       NODE: Every callback gets as it's first argument	the
       AnyEvent::XMPP::Connection object. The further callback arguments are
       described in the	following listing of events.

       These events can	be registered on with "reg_cb":

       stream_features => $node
	   This	event is sent when a stream feature (<features>) tag is
	   received. $node is the AnyEvent::XMPP::Node object that represents
	   the <features> tag.

       stream_pre_authentication
	   This	event is emitted after TLS/SSL was initiated (if enabled) and
	   before any authentication happened.

	   The return value of the first event callback	that is	called decides
	   what	happens	next.  If it is	true value the authentication
	   continues. If it is undef or	a false	value authentication is
	   stopped and you need	to call	"authentication" later.	 value

	   This	event is usually used when you want to do in-band
	   registration, see also AnyEvent::XMPP::Ext::Registration.

       stream_ready => $jid
	   This	event is sent if the XML stream	has been established (and
	   resources have been bound) and is ready for transmitting regular
	   stanzas.

	   $jid	is the bound jabber id.

       error =>	$error
	   This	event is generated whenever some error occured.	 $error	is an
	   instance of AnyEvent::XMPP::Error.  Trivial error reporting may
	   look	like this:

	      $con->reg_cb (error => sub { warn	"xmpp error: " . $_[1]->string . "\n" });

	   Basically this event	is a collect event for all other error events.

       stream_error => $error
	   This	event is sent if a XML stream error occured. $error is a
	   AnyEvent::XMPP::Error::Stream object.

       xml_parser_error	=> $error
	   This	event is generated whenever the	parser trips over XML that it
	   can't read. $error is a AnyEvent::XMPP::Error::Parser object.

       tls_error
	   This	event is emitted when a	TLS error occured on TLS negotiation.
	   After this the connection will be disconnected.

       sasl_error => $error
	   This	event is emitted on SASL authentication	error.

       iq_auth_error =>	$error
	   This	event is emitted when IQ authentication	(XEP-0078) failed.

       bind_error => $error, $resource
	   This	event is generated when	the stream was unable to bind to any
	   or the in "new" specified resource. $error is a
	   AnyEvent::XMPP::Error::IQ object. $resource is the errornous
	   resource string or undef if none was	received.

	   The "condition" of the $error might be one of: 'bad-request',
	   'not-allowed' or 'conflict'.

	   Node: this is untested, I couldn't get the server to	send a bind
	   error to test this.

       connect => $host, $port
	   This	event is generated when	a successful TCP connect was performed
	   to the domain passed	to "new".

	   Note: $host and $port might be different from the domain you	passed
	   to "new" if "connect" performed a SRV RR lookup.

	   If this connection is lost a	"disconnect" will be generated with
	   the same $host and $port.

       disconnect => $host, $port, $message
	   This	event is generated when	the TCP	connection was lost or another
	   error occurred while	writing	or reading from	it.

	   $message is a human readable	error message for the failure.	$host
	   and $port were the host and port we were connected to.

	   Note: $host and $port might be different from the domain you	passed
	   to "new" if "connect" performed a SRV RR lookup.

       recv_stanza_xml => $node, $rstop
	   This	event is generated before any processing of a "XML" stanza
	   happens.  $node is the node of the stanza that is being processed,
	   it's	of type	AnyEvent::XMPP::Node.

	   This	method might not be as handy for debugging purposes as
	   "debug_recv".

	   If you want to handle the stanza yourself and don't want this
	   module to take care of it set a true	value to the scalar referenced
	   by $rstop.

       send_stanza_data	=> $data
	   This	event is generated shortly before data is sent to the socket.
	   $data contains a complete "XML" stanza or the end of	stream closing
	   tag.	This method is useful for debugging purposes and I recommend
	   using XML::Twig or something	like that to display it	nicely.

	   See also the	event "debug_send".

       debug_send => $data
	   This	method is invoked whenever data	is written out.	This event is
	   mostly the same as "send_stanza_data".

       debug_recv => $data
	   This	method is invoked whenever a chunk of data was received.

	   It works to filter $data through XML::Twig for debugging display
	   purposes sometimes, but as $data is some arbitrary chunk of bytes
	   you might get a XML parse error (did	I already mention that XMPP's
	   application of "XML"	sucks?).

	   So you might	want to	use "recv_stanza_xml" to detect	complete
	   stanzas. Unfortunately "recv_stanza_xml" doesn't have the bytes
	   anymore and just a data structure (AnyEvent::XMPP::Node).

       send_buffer_empty
	   This	event is VERY useful if	you want to wait (or at	least be
	   notified) when the output buffer is empty. If you got a bunch of
	   messages to sent or even one	and you	want to	do something when the
	   output buffer is empty, you can wait	for this event.	It is emitted
	   every time the output buffer	is completely written out to the
	   kernel.

	   Here	is an example:

	      $con->reg_cb (send_buffer_empty => sub {
		 $con->disconnect ("wrote message, going to disconnect now...");
	      });
	      $con->send_message ("Test	message!" => 'elmex@jabber.org', undef,	'chat');

       presence_xml => $node
	   This	event is sent when a presence stanza is	received. $node	is the
	   AnyEvent::XMPP::Node	object that represents the <presence> tag.

	   If you want to overtake the handling	of the stanza, see "iq_xml"
	   below.

       message_xml => $node
	   This	event is sent when a message stanza is received. $node is the
	   AnyEvent::XMPP::Node	object that represents the <message> tag.

	   If you want to overtake the handling	of the stanza, see "iq_xml"
	   below.

       iq_xml => $node
	   This	event is emitted when a	iq stanza arrives. $node is the
	   AnyEvent::XMPP::Node	object that represents the <iq>	tag.

	   If you want to overtake the handling	of a stanza, you should
	   register a callback for the "before_iq_xml" event and call the
	   "stop_event"	method.	See also Object::Event.	This is	an example:

	      $con->reg_cb (before_iq_xml => sub {
		 my ($con, $node) = @_;

		 if (...) {
		    # and stop_event will stop internal	handling of the	stanza:
		    $con->stop_event;
		 }
	      });

	   Please note that if you overtake handling of	a stanza none of the
	   internal handling of	that stanza will be done. That means you won't
	   get events like "iq_set_request_xml"	anymore.

       iq_set_request_xml => $node, $rhandled
       iq_get_request_xml => $node, $rhandled
	   These events	are sent when an iq request stanza of type 'get' or
	   'set' is received.  $type will either be 'get' or 'set' and $node
	   will	be the AnyEvent::XMPP::Node object of the iq tag.

	   To signal the stanza	was handled set	the scalar referenced by
	   $rhandled to	a true value.  If the stanza was not handled an	error
	   iq will be generated.

       iq_result_cb_exception => $exception
	   If the $result_cb of	a "send_iq" operation somehow threw a
	   exception or	failed this event will be generated.

       send_iq_hook => $id, $type, $attrs, \@create_cb
	   This	event lets you add any desired number of additional create
	   callbacks to	a IQ stanza that is about to be	sent.

	   $id,	$type are described in the documentation of "send_iq" of
	   AnyEvent::XMPP::Writer. $attrs is the hashref to the	%attrs hash
	   that	can be passed to "send_iq" and also has	the exact same
	   semantics as	described in the documentation of "send_iq".

	   You can push	values into "create_cb"	(as documented for "send_iq"),
	   for example a callback that fills the IQ.

	   Example:

	      #	this appends a <test/> element to all outgoing IQs
	      #	and also a <test2/> element to all outgoing IQs
	      $con->reg_cb (send_iq_hook => sub	{
		 my ($con, $id,	$type, $attrs, $create_cb) = @_;
		 push @$create_cb, sub {
		    my $w = shift; # $w	is a XML::Writer instance
		    $w->emptyTag ('test');
		 };
		 push @$create_cb, {
		    node => { name => "test2" }	# see also simxml() defined in AnyEvent::XMPP::Util
		 };
	      });

       send_message_hook => $id, $to, $type, $attrs, \@create_cb
	   This	event lets you add any desired number of additional create
	   callbacks to	a message stanza that is about to be sent.

	   $id,	$to, $type and the hashref $attrs are described	in the
	   documentation for "send_message" of AnyEvent::XMPP::Writer ($attrs
	   is %attrs there).

	   To actually append something	you need to push into "create_cb" as
	   described in	the "send_iq_hook" event above.

       send_presence_hook => $id, $type, $attrs, \@create_cb
	   This	event lets you add any desired number of additional create
	   callbacks to	a presence stanza that is about	to be sent.

	   $id,	$type and the hashref $attrs are described in the
	   documentation for "send_presence" of	AnyEvent::XMPP::Writer ($attrs
	   is %attrs there).

	   To actually append something	you need to push into "create_cb" as
	   described in	the "send_iq_hook" event above.

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

CONTRIBUTORS
       melo - minor fixes

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-02-01	 AnyEvent::XMPP::Connection(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | EVENTS | AUTHOR | CONTRIBUTORS | COPYRIGHT & LICENSE

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

home | help