view release on metacpan or  search on metacpan

lib/Net/SloppyXMPP.pm  view on Meta::CPAN

our $VERSION = '0.06';

=head1 NAME

Net::SloppyXMPP - A rather sloppy XMPP client implementation

=head1 DESCRIPTION

In an attempt to drastically reduce external dependencies, this module doesn't use a lot of them.
Therefore, it doesn't do a whole lot via proper standards.

The XML parser is a combination of a mess of regex hacks and some processing through XML::Simple.

XML namespaces aren't really used properly.

There's no guarantee that this will work for anything.

Reinventing the wheel?  You betcha.  Unfortunately, neither L<Net::XMPP> nor L<AnyEvent::XMPP> would
work in the fashion I needed.  It doesn't help that L<Net::XMPP> is unmaintained (or so it seems)
these days.  L<AnyEvent::XMPP> requires LibIDN, which has been too big of an issue to deal with
where I'm needing to implement an XMPP client.

SASL and TLS are both available, but not required.  Just disable one or both of them if you don't
want or can't use them.  SASL features are provided via L<Authen::SASL> and are only used if
C<usesasl> is true (it's true unless you specifically set it to false).  TLS features are provided
via L<Net::SSLeay> and are only used if C<usetls> is true (it's true unless you specifically set
it to false).

One of the goals of this implementation is to ensure that it will work on as many platforms as possible,
especially those that can't use a few of the dependencies of the other XMPP modules available for Perl.

=head1 WHO SHOULD USE THIS?

Probably no one.  It's sloppy.  It's untested.  It's incomplete.  But if the description above didn't
scare you away, you might be a good candidate.  You'll probably need to track down some bugs in it
before you can really use it.  If you're using Openfire 3.6.2 as an XMPP server, you might have good
luck in using it straight away.  If you're using Google's XMPP service, you won't have any luck (yet).

If you really want to use this module, but it doesn't work for you, please post your troubles on the
CPAN bug tracker.  If you need support for additional XMPP servers, I'd love to add such support.
To do that, I might need access to the XMPP server with a test username/password.  I'd really rather not
setup loads of XMPP servers for testing purposes.  Providing me with a test account will help the process
of adding additional XMPP servers.

But like I said, maybe no one should be using this module.  Other seemingly good XMPP modules are
available on CPAN.  Some examples: L<Net::XMPP> and L<AnyEvent::XMPP>.

=head1 EXAMPLE

  use Net::SloppyXMPP;

  my $xmpp = Net::SloppyXMPP->new(
    debug => 1,
    tickdelay => 1,
    #usetls => 0, # set this if you don't want TLS
    #usesasl => 0, # set this if you don't want SASL
    domain => 'yourdomain.xyz',
    username => 'yourusername',
    password => 'yourpassword',
    resource => 'yourresourcename', # or don't set and a default will be supplied
    initialpresence => 'available', # available, busy, dnd, defaults to available
    initialstatus => 'I am alive!', # defaults to ''
    message_callback => \&messageCallback,
  );
  die qq(XMPP didn't create.\n) unless $xmpp;

  sub messageCallback
  {
    my $xmpp = shift;
    my $data = shift;
    print Dumper($data);
  }

  my $xmppConnect = $xmpp->connect;
  die qq(XMPP didn't connect.\n) unless $xmppConnect;

  # if you want SloppyXMPP to control your main loop
  $xmpp->run(\&tick);
  sub tick
  {
    # do stuff in here that needs to happen each loop (use as a main loop)
    my $xmpp = shift; # if you need it, same object as the $xmpp you already used
    print "This runs every $xmpp->{tickdelay} seconds.\n";
  }

  # or if you want to run your own loop, do this:
  sub loop
  {
    print "Doing something useful here...\n";

    # ... more useful code ...

    $xmpp->tick; # runs the SloppyXMPP loop once

    # ... and more useful code ...
  }
  loop();

=head1 ABSTRACT

Not complete, just like the module itself.  Feel free to read the source code to figure out how to
use it.  A bit of help is sprinkled about the page below.

B<WARNING:> Most of these functions are internal functions not to be used outside of the module.
If you use them yourself, I don't want to get bug reports about it.  If it just says
"C<Used internally>" but doesn't say you can't use it, you're probably okay to use it.  If it says
something like "C<Don't use it yourself>", don't use it.  You're likely to upset the delicate
balance of nature and might cause mass casualties, famine, hurricanes, tornadoes, floods, or drought.
You've been warned.

If you've avoided my warning above and are using a function that you really have no business using,
let me know (see my contact info at the end of this doc) so I can create a more proper interface
into whatever it is that you're doing improperly.

=head2 new

  my $xmpp = Net::SloppyXMPP->new(
    someoption => "somevalue",       # see below
    anotheroption => "anothervalue", #   for the options
  );