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

FreeBSD Manual Pages

  
 
  

home | help
Jabber::Connection(3) User Contributed Perl DocumentationJabber::Connection(3)

NAME
       Connection - Simple connectivity	functions for Jabber

SYNOPSIS
	 # client connection:
	 my $c = new Jabber::Connection(
	   server => 'jabber.org',
	   log	  => 1,
	 );

	 # component connection:
	 # my $c = new Jabber::Connection(
	 #   server    => 'localhost:5700',
	 #   localname => 'comp.localhost',
	 #   ns	       => 'jabber:component:accept',
	 #   log       => 1,
	 #   debug     => 1,
	 # );

	 die "oops: ".$c->lastError unless $c->connect();

	 $c->register_beat(10, \&every_10_seconds);

	 $c->register_handler('presence',\&presence);
	 $c->register_handler('iq',\&handle_iq_conference);
	 $c->register_handler('iq',\&handle_iq_browse);

	 $c->auth('qmacro','password','myresource'); # client auth
	 # $c->auth('secret'); # component auth

	 $c->send('<presence/>');

	 $c->start;

DESCRIPTION
       The Jabber::Connection package provides basic functions for connecting
       clients and components to a Jabber server.

METHODS
       new()
	   The connection constructor. Returns a new Jabber::Connection
	   object.  The	parameters are specified in a

	     param => value

	   list.

	   For a basic client connection, you can specify the minimum

	     my	$c = new Jabber::Connection(server => 'jabber.org');

	   If no port is specified, the	default	5222 will be used.  There are
	   other parameters that can be	passed:

	   ns  the namespace that qualifies the	connection stream. If left
	       unspecified, this will default to 'jabber:client'.  For a TCP
	       socket-based component, specify 'jabber:component:accept'. [
	       *** These are the only two stream namespaces supported now ***
	       ]

	   localname
	       the name	of the component in a component	connection.

	   ssl whether the connection should use SSL [ *** not supported yet!
	       *** ]

	   See the SYNOPSIS for	examples of new().

       connect()
	   Use this to establish the stream to the Jabber server. There	are no
	   parameters required.	If a problem occurs, the function returns 0,
	   and the error reason	is available by	calling	"lastError()".

	   Example:

	     $c->connect();

       disconnect()
	   Use this to terminate the stream and	end the	connection.

	   Example:

	     $c->disconnect();

       process()
	   Call	this function to look for incoming fragments on	the stream.
	   You can specify an optional argument	which is the number of seconds
	   to wait while looking. If no	argument is given, a value of 0	is
	   assumed.

	   An incoming fragment	is parsed and assembled	into a Node object
	   which is dispatched to any handlers that have been registered for
	   the Node object's tag name.

	   Examples:

	     $c->process();   #	look for any fragments but don't
			      #	wait around if there aren't any

	     $c->process(5);  #	wait for up to 5 seconds for fragments
			      #	to come	in on the stream

       auth()
	   Perform authorization. This function	takes either one or three
	   arguments, depending	on what	type of	connection has been made.  If
	   you have made a component connection, the secret must be specified
	   here	as the single argument.	If you have made a client connection,
	   the username, password and resource must be specified.

	   Example:

	     $c->auth('secret'); # component auth
	     $c->auth('user','password','resource'); # client auth

	   For a component authorization, the <handshake/> based process is
	   used. For a client authorization, the JSM is	queried	for the
	   supported authentication methods, and then one is picked, degrading
	   gracefully through zero-k, digest and plaintext methods.

       send()
	   Send	data across the	stream with this function. You can send	either
	   XML in string form, or send a Node object.

	   Examples:

	     $c->send('<presence/>');

	     my	$msg = $nf->newNode('message')->insertTag('body')->data('hello');
	     $msg->attr('to','qmacro@jabber.org');
	     $c->send($msg);

       lastError()
	   Returns the last error that occured.	This will usually be the text
	   from	a stream error.

       ask()
	   Send	something and wait for a response relating to what was sent.
	   This	relation is established	using an id attribute in the top level
	   tag of the node being sent. If there	is no id attribute, one	is
	   inserted with a value automatically assigned.

       register_handler()
	   When	a fragment is received and turned into a Node object, a
	   dispatching process is started which	will call handlers (callbacks)
	   that	you can	set using this function.

	   The function	takes two arguments. The first is used to identify the
	   node	type (the element) - e.g. 'message', 'presence'	or 'iq'. The
	   second is a reference to a subroutine.

	   You can register as many handlers as	you wish. Each of the handlers
	   registered for a specific node type will be called in turn (in the
	   order that they were	registered). Each of the handlers are passed
	   two things -	the node being dispatched, and a 'parcel' which	can be
	   used	to share data between the handlers being called. The parcel
	   value passed	to the first handler in	the call sequence is undef.
	   Whatever value is returned by a particular handler is then passed
	   onto	the next handler.

	   If a	handler	returns	nothing	(e.g. by simply	the "return"
	   statement), then the	parcel data remains unaffected and is passed
	   on intact to	the next handler.

	   (You	don't have to do anything with the parcel; it's	there just in
	   case	you want to pass something along the call sequence.)

	   If a	handler	returns	the special value represented by the constant
	   "r_HANDLED",	the call sequence is ended - no	more handlers in the
	   list	are called in the dispatch for that node.

	   Examples:

	     $c->register_handler(
		    message => sub {
				     ...
				   }
	     );

	     $c->register_handler('iq',	\&handle_version);
	     $c->register_handler('iq',	\&handle_time);
	     $c->register_handler('iq',	\&handle_browse);

       register_beat()
	   You can register subroutines	to be called on	a regular basis	using
	   the "heartbeat" feature. The	first argument is the number of
	   seconds ('every N seconds'),	the second is a	subroutine reference.

	   Example:

	     $c->register_beat(1800, \&getRSS);

	   This	example	registers a subroutine getRSS()	to be called every
	   half	an hour.

	   Note: the heart doesn't start beating until the start() function is
	   called.

       start()
	   Start a process loop. This has a similar effect to something	like

	     while (1) { $c->process(1)	}

	   except that it also maintains a heartbeat (see register_beat()).

SEE ALSO
       Jabber::NodeFactory, Jabber::NS

AUTHOR
       DJ Adams

VERSION
       early

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

perl v5.24.1			  2002-05-06		 Jabber::Connection(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHOR | VERSION | COPYRIGHT

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

home | help