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.