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.

METHODS

spawn

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

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

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 );

- The group name(s)
- Adding the last parameter ( int ) is the Spread mess_type -> application-defined ( default: 0 )

Send a simple message to a Spread group(s). This uses the Spread message type 'SAFE_MESS'

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 )
	}
}

_sp_message

sub _sp_message : state {
	my( $priv_name, $type, $sender, $groups, $mess_type, $message ) = @_[ ARG0 .. ARG5 ];

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

_sp_admin

sub _sp_admin : state {
	my( $priv_name, $type, $sender, $groups, $mess_type, $message ) = @_[ ARG0 .. ARG5 ];
	# Could be somebody quit/join or something else?
}

SpreadClient Notes

You can enable debugging mode by doing this:

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

BUGS

- Need to expand documentation so the message types in _sp_admin is more understandable
- Would love to have more message handling - a simple look at the Spread User's Guide shows a lot of message variety!
- Need to be tested more!

SEE ALSO

Spread

POE::Component::Spread

CREDITS

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

COPYRIGHT AND LICENSE

Copyright 2006 by Apocalypse

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

cpanm POE::Component::SpreadClient

perl -MCPAN -e shell
install POE::Component::SpreadClient