NAME
    POE::Component::SpreadClient - Handle Spread communications in POE

SYNOPSIS
            POE::Component::SpreadClient->spawn( 'spread' );

            POE::Session->create(
                inline_states => {
                    _start => \&_start,
                    _sp_message => \&do_something,
                    _sp_admin => \&do_something,
                    _sp_connect => \&do_something,
                    _sp_disconnect => \&do_something,
                    _sp_error => \&do_something,
                }
            );

            sub _start {
                    $poe_kernel->alias_set('displayer');
                    $poe_kernel->post( spread => connect => 'localhost', $$ );
                    $poe_kernel->post( spread => subscribe => 'chatroom' );
                    $poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?' );
            }

DESCRIPTION
    POE::Component::SpreadClient is a POE component for talking to Spread
    servers.

    This module should only be used with Spread 3.17.3 ( or compatible
    versions )

    XXX Beware: this module hasn't been tested with Spread 4! XXX

METHODS
  spawn
            POE::Component::Spread->spawn( 'spread' );

            - The alias the component will take ( default: "SpreadClient" )

            Returns the session ID.

Public API
  connect
            $poe_kernel->post( spread => connect => '4444@localhost' );
            $poe_kernel->post( spread => connect => '4444@localhost', 'logger' );

            - The Server location
            - The private name for the Spread connection ( default: "spread-PID" )

            Connect this POE session to the Spread server on port 4444 on localhost.

            Will send a C<_sp_error> event if unable to connect; C<_sp_connect> if successful

  disconnect
            $poe_kernel->post( spread => disconnect );

            Forces this session to disconnect. ( DOES NOT REMOVE ALIAS => look at destroy below )

            Will send a C<_sp_disconnect> event if disconnected; C<_sp_error> if failure

  subscribe
            $poe_kernel->post( spread => subscribe => 'chatroom' );
            $poe_kernel->post( spread => subscribe => [ 'chatroom', 'testing' ] );

            - The group name(s)

            Subscribe to a Spread messaging group. Messages will be sent to C<_sp_message> and
            join/leave/etc to C<_sp_admin> in the registered listeners.

            Automatically adds the session to the registered listeners.

            Will send a C<_sp_error> if unable to subscribe; C<_sp_admin> with join message if successful

  unsubscribe
            $poe_kernel->post( spread => unsubscribe => 'chatroom' );
            $poe_kernel->post( spread => unsubscribe => [ 'foobar', 'chatroom' ] );

            Unsubscribes to a Spread messaging group. Does not remove the session from the listener list.

            Will send a C<_sp_error> if unable to unsubscribe; C<_sp_admin> with self_leave if successful

  publish
            $poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?' );
            $poe_kernel->post( spread => publish => [ 'chatroom', 'stats' ], 'A/S/L?' );
            $poe_kernel->post( spread => publish => 'chatroom', 'special', 5 );
            $poe_kernel->post( spread => publish => 'chatroom', 'A/S/L?', undef, RELIABLE_MESS & SELF_DISCARD );

            - The group name(s)
            - 2nd parameter ( int ) is the Spread mess_type -> application-defined ( default: 0 )
            - The 3rd parameter is the spread message type -> import them from Spread.pm ( default: SAFE_MESS )

            Send a string to the group(s).

            THIS WILL ONLY SEND STRINGS! If you need to send perl structures, use your own serializer/deserializer!

            REMEMBER about the message size limitation

                    From spread-src-3.17.3
                    #define MAX_MESSAGE_BODY_LEN    (MAX_SCATTER_ELEMENTS * (MAX_PACKET_SIZE - 32)) /* 32 is sizeof(packet_header) */
                    #define MAX_SCATTER_ELEMENTS    100
                    #define MAX_PACKET_SIZE 1472    /*1472 = 1536-64 (of udp)*/

                    Therefore max message size is 100 * 1440 =~ 140kB

            Will send a C<_sp_error> if unable to publish

  register
            $poe_kernel->post( spread => register );

            Registers the current session as a "registered listener" and will receive all events.

  unregister
            $poe_kernel->post( spread => unregister );

            Removes the current session from the "registered listeners" list.

  destroy
            $poe_kernel->post( spread => destroy );

            Destroys the session by removing it's alias and disconnecting if needed with C<_sp_disconnect>

EVENTS
  `_sp_connect'
            sub _sp_connect : State {
                    my( $priv_name, $priv_group ) = @_[ ARG0, ARG1 ];
                    # We're connected!
            }

  `_sp_disconnect'
            sub _sp_disconnect : State {
                    my $priv_name = $_[ ARG0 ];
                    # We're disconnected!
            }

  `_sp_error'
            sub _sp_error : State {
                    my( $priv_name, $type, $sperrno, $msg, $data ) = @_[ ARG0 .. ARG4 ];

                    # Handle different kinds of errors
                    if ( $type eq 'CONNECT' ) {
                            # $sperrno = Spread errno/error string, $msg = server name, $data = priv name
                    } elsif ( $type eq 'PUBLISH' ) {
                            # $sperrno = Spread errno, $msg = $groups ( may be undef ), $data = $message ( may be undef )
                    } elsif ( $type eq 'SUBSCRIBE' ) {
                            # $sperrno = Spread errno, $msg = $groups ( may be undef )
                    } elsif ( $type eq 'UNSUBSCRIBE' ) {
                            # $sperrno = Spread errno, $msg = $groups ( may be undef )
                    } elsif ( $type eq 'RECEIVE' ) {
                            # $sperrno = error string
                    }
            }

  `_sp_message'
            sub _sp_message : State {
                    my( $priv_name, $sender, $groups, $mess_type, $message ) = @_[ ARG0 .. ARG4 ];

                    # $mess_type is always 0 unless defined ( mess_type in Spread )
            }

  `_sp_admin'
            sub _sp_admin : State {
                    my( $priv_name, $data ) = @_[ ARG0, ARG1 ];
                    # $data is hashref with several fields:
                    # TYPE => string ( JOIN | LEAVE | DISCONNECT | SELF_LEAVE | TRANSITIONAL | NETWORK )
                    # GROUP => string ( group name )
                    # GID => [ GID1, GID2, GID3 ] ( look at Spread documentation about this! )
                    # MEMBERS => arrayref of member names
                    # WHO => string ( whomever left/join/discon )
                    # INDEX => index of self in group list
                    # MESSAGE => raw unpacked message ( needed for NETWORK's special parsing, not done! )

                    # if TYPE = JOIN | LEAVE | DISCONNECT
                    # GROUP, MEMBERS, WHO, GID, INDEX

                    # if TYPE = SELF_LEAVE
                    # GROUP

                    # if TYPE = TRANSITIONAL
                    # GROUP

                    # if TYPE = NETWORK
                    # GROUP, MEMBERS, GID, INDEX, MESSAGE
            }

SpreadClient Notes
    You can enable debugging mode by doing this:

            sub POE::Component::SpreadClient::DEBUG () { 1 }
            use POE::Component::SpreadClient;

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc POE::Component::SpreadClient

  Websites
    * AnnoCPAN: Annotated CPAN documentation
        http://annocpan.org/dist/POE-Component-SpreadClient

    * CPAN Ratings
        http://cpanratings.perl.org/d/POE-Component-SpreadClient

    * RT: CPAN's request tracker
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-SpreadClient

    * Search CPAN
        http://search.cpan.org/dist/POE-Component-SpreadClient

  Bugs
    Please report any bugs or feature requests to
    `bug-poe-component-spreadclient at rt.cpan.org', or through the web
    interface at
    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-SpreadClien
    t. I will be notified, and then you'll automatically be notified of
    progress on your bug as I make changes.

SEE ALSO
    Spread

    Spread::Message

    POE::Component::Spread

AUTHOR
    Apocalypse <apocal@cpan.org>

    The base for this module was lifted from POE::Component::Spread by Rob
    Partington <perl-pcs@frottage.org>.

COPYRIGHT AND LICENSE
    Copyright 2009 by Apocalypse

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