NAME

    Protocol::XMPP - Protocol-level support for XMPP interaction

SYNOPSIS

     my $xmpp = Protocol::XMPP::Stream->new;
     $xmpp->();

DESCRIPTION

    This module provides an API for the Extensible Message Passing
    Protocol. This is commonly used for integration with Jabber servers and
    Google Talk, although XMPP itself supports a number of extended
    features for a distributed multi-server, multi-client message exchange
    system.

    The primary implementation is based on RFC3920bis, which is still in
    flux. The instant message support is defined by RFC3921bis.

    The two main classes used here are Protocol::XMPP::Stream, which
    provides hooks for the underlying XML message stream, and
    Protocol::XMPP::Handler, which passes the SAX events from this stream
    on to appropriate handlers.

    Client or server implementations should create an instance of the
    Protocol::XMPP::Stream class for each connection, passing callbacks to
    allow the protocol implementation to send data over the connection and
    process received data.

IMPLEMENTATION

    An overview of the connection lifetime for a typical client session:

      * Connect to server

      * Establish session, including authentication and stream requirements
      such as TLS or compression

      * Retrieve roster

      * Send presence update to server

      * Send and receive messages as required

      * Terminate session

    The details of connecting to sockets and upgrading to TLS are left to
    the implementation. This module deals with the underlying protocol
    stream only, providing hooks that the implementation can call rather
    than attempting to implement the functionality directly.

 Roster

    A roster is a list of contacts, each of which may also have presence
    information. This list is stored on the server, although each client
    may also maintain a cached copy of the list.

    Roster information is exchanged using Protocol::XMPP::IQ::Roster
    queries and responses.

    Roster includes the ver information which is an opaque server token
    used to identify the version of the roster information.

    A roster query has a single item, and the response can have multiple.

    Each item may also belong to zero or more groups.

    Subscription states:

      * none - neither source nor destination contact have an existing
      subscription.

      * to - we have a subscription to the contact, but they don't have us.

      * from - they have us, we don't have them.

      * both - mutual subscription.

MOTIVATION

    This distribution is written with the intention to provide a base for
    XMPP implementations which can work on an event-based ("asynchronous")
    or standard blocking model. It uses XML::LibXML::SAX::ChunkedParser to
    deal with the XML fragments required by the protocol, and attempts to
    minimise any blocking operations.

SEE ALSO

      * AnyEvent::XMPP - this is an event-based implementation of XMPP,
      seems to support the core protocol and some key XEPs such as
      multi-user chat. The documentation is somewhat terse (rants about XML
      notwithstanding) but more detailed than Protocol::XMPP.

      * Net::XMPP - another implementation, sadly the XML parser is
      blocking so although it provides the Net::XMPP::Protocol abstraction
      layer for the XMPP protocol, which probably has better feature
      support than this module, it's not too suitable for dealing with
      asynchronous / event-based implementations. Also, I wasn't too keen
      on some of the implementation details, such as the direct checking
      for ref and callback handling.

      * Net::XMPP3::Protocol - seems to be the same module as above, under
      a slightly different namespace

AUTHOR

    Tom Molesworth <protocol-xmpp@entitymodel.com>

CONTRIBUTORS

    With thanks to the following for contribution:

      * Arthur Axel "fREW" Schmidt for testing, documentation, pointing out
      some of my mistakes, that sort of thing

      * Paul "LeoNerd" Evans for adding Futures to IO::Async (and writing
      both in the first place)

      * Matt Trout for testing early versions

LICENSE

    Copyright Tom Molesworth 2010-2026. Licensed under the same terms as
    Perl itself.

