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

FreeBSD Manual Pages

  
 
  

home | help
Net::XMPP2::ConnectionUser Contributed Perl DocumentaNet::XMPP2::Connection(3)

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

SYNOPSIS
	  use Net::XMPP2::Connection;

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

	  $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
       "Net::XMPP2::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.

	   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 Net::XMPP2::Util for utility
	       functions to check this.

	   domain => $domain
	       This is the destination host we are going to connect to.	 As
	       the connection won't be automatically connected use "connect"
	       to initiate the connect.

	       Note: A SRV RR lookup will be performed to discover the real
	       hostname	and port to connect to.	See also "connect". This
	       option is usually not very useful if SRV	RR lookup is
	       performed, as it	is only	used as	a fallback.  If	you want to
	       force the hostname to a certain value use "override_host",
	       which also disabled SRV RR lookup.

	   override_host => $host
	       If this option is set no	SRV RR lookup is performed and the
	       $host will be used to connect to.

	   override_port => $port
	       If this option is set the port of the server we are going to
	       connect to is forced to $port (even if SRV RR tells us
	       something different).

	   port	=> $port
	       This is optional, the default port is 5222.

	       Note: A SRV RR lookup will be performed to discover the real
	       hostname	and port to connect to.	See also "connect". This
	       option is usually not very useful if SRV	RR lookup is
	       performed, as it	is only	used as	a fallback.  If	you want to
	       force the port to a certain value use "override_port".

	   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.

	   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 Net::XMPP2::Util for utility functions to
	       check this.

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

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

	   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 Net::XMPP2 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.

	   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.

	   blocking_write => $bool
	       This is a special option	which will make	all send operations
	       "send_message", "send_iq" and "send_presence" block until the
	       output buffer is	empty. If this option is enabled every
	       "send_message", "send_iq" and "send_presence" call will call
	       "drain" internally to block until the output buffer is empty.

	       This option is DISABLED by default and you should only enable
	       it if you know what you are doing.

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

	   A SRV RR lookup will	be performed on	the domain to discover the
	   host	and port to use. If you	don't want this	set $no_srv_rr to a
	   true	value. $no_srv_rr is false by default.

	   As the SRV RR lookup	might return multiple host and you fail	to
	   connect to one you might just call this function again to try a
	   different host.

	   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: 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
	   Net::XMPP2::Error::IQ object	where the "condition" method returns a
	   special value (see also "condition" method of
	   Net::XMPP2::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
	   Net::XMPP2::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
	   Net::XMPP2::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 Net::XMPP2::Error::IQ object.

	   The timeout can be set by "set_default_iq_timeout" or passed
	   seperatly 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
	   "Net::XMPP2::Node" in $req_iq_node.

	   Please take a look at the documentation for "send_iq" in
	   Net::XMPP2::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
	   "Net::XMPP2::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 Net::XMPP2::Writer.

	   Please take a look at the documentation for "send_iq" in
	   Net::XMPP2::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 Net::XMPP2::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 Net::XMPP2::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
	   Net::XMPP2::Node object.

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

       drain
	   This	method will block until	the output buffer is empty.  For
	   example if you want to block	the program until the message sent by
	   "send_message", "send_iq" or	"send_presence"	or any other sending
	   method, is written out to the kernel	completly.

	   NOTE: Use this method only if you know what you are doing!

	   Also	note that this function	will emit the "send_buffer_empty"
	   event when the buffer was emptied successfully. On error the
	   connection is disconnected with the error message.

EVENTS
       The Net::XMPP2::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
       Net::XMPP2::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 Net::XMPP2::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 Net::XMPP2::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 Net::XMPP2::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
	   Net::XMPP2::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 Net::XMPP2::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
	   Net::XMPP2::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 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 connection was lost	or another
	   error occured while writing or reading from it.

	   $message is a humand	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
	   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	Net::XMPP2::Node.

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

	   If you want to handle the stanza yourself and don't want this
	   module to take care of it return a true value from your registered
	   callback.

	   If any of the event callbacks return	a true value this stanza will
	   be ignored.

       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 incoked 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 datastructure (Net::XMPP2::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
	   everytime the output	buffer is completly 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
	   Net::XMPP2::Node object that	represents the <presence> tag.

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

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

       iq_set_request_xml => $node
       iq_get_request_xml => $node
	   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 Net::XMPP2::Node	object of the iq tag.

	   If one of the event callbacks returns a true	value the IQ request
	   will	be considered as handled.  If no callback returned a true
	   value or no value at	all 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
	   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
	   Net::XMPP2::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".

	   The return values of	the event callbacks are	interpreted as
	   $create_cb value as documented for "send_iq". (That means you can
	   for example return 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) = @_;
		 (sub {
		    my $w = shift; # $w	is a XML::Writer instance
		    $w->emptyTag ('test');
		 }, {
		    node => { name => "test2" }	# see also simxml() defined in Net::XMPP2::Util
		 })
	      });

       send_message_hook => $id, $to, $type, $attrs
	   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 Net::XMPP2::Writer ($attrs is
	   %attrs there).

	   To actually append something	you need to return something, what you
	   need	to return is described in the "send_iq_hook" event above.

       send_presence_hook => $id, $type, $attrs
	   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	Net::XMPP2::Writer ($attrs is
	   %attrs there).

	   To actually append something	you need to return something, what you
	   need	to return is 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 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			  2008-08-01	     Net::XMPP2::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=Net::XMPP2::Connection&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help