/ 
POE-Component-SpreadClient-0.06
River stage one • 1 direct dependent • 1 total dependent
/ POE::Component::SpreadClient

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

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;

BUGS

- Need to be tested more!
- Endian mis-match is simply a warn, should it be added to _sp_message ?

SEE ALSO

Spread

Spread::Message

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 2008 by Apocalypse

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