NAME

POE::Component::Audio::Mad::Dispatch - A POE::Component::Audio::Mad frontend
implementing listener based message dispatch.

SYNOPSIS

  use POE;
  use POE::Component::Audio::Mad::Dispatch;

  ## we print some stuff below,  and we don't want it
  ## to get buffered..  so turn on autoflush.
  $| = 1;

  ## create our frontend session,  which will create a decoder and
  ## forward it's messages to all interested listeners..
  create POE::Component::Audio::Mad::Dispatch({ 
  	decoder_play_on_open => 1,
  	alias                => 'mad-decoder'
  });

  POE::Session->create(inline_states => {
  	_start            => \&ex_start,
  	mad_decoder_input => \&ex_input
  });
  
  sub ex_start {
  	my ($kernel, $heap, $session) = @_[KERNEL, HEAP, SESSION];
  	
	## add ourself in as a listener,  and register for the DECODER_FRAME_DATA and
	## IPC_SHUTDOWN_SUCCESS events.  The decoder core will then call the
	## 'mad_decoder_input' state in the current session when these 
	## events arrive.. 
	
	## this also has the added benefit of keeping a reference to our
	## session alive in the event notification list.  Our session will
	## remain alive as long as we are a registered listener..
	
  	$heap->{lid} = $kernel->call('mad-decoder', 'add_listener', $session, 'mad_decoder_input', [
  		'DECODER_FRAME_DATA', 'INPUT_EOF_WARNING'
  	]);
  	
  	## tell our decoder to start playing a stream..
  	$kernel->post('mad-decoder', 'decoder_open', { filename => '/path/to/stream.mp3', play => 1 });
  }
  
  sub ex_input {
  	my ($kernel, $heap, $msg) = @_[KERNEL, HEAP, ARG0];
  	
  	## this is called when the decoder has generated an event
  	## that we have registered for.  the message packet is
  	## contained in ARG0,  and is a hashref with two
  	## fields ->{id} and ->{data}.  id specifies the name
  	## of the event,  and data contains a reference to 
  	## the data included in this event..
  	
  	if ($msg->{id} eq 'DECODER_FRAME_DATA') {

  		## we got a message updating us as to player
  		## progress,  the data part of the event will
  		## contain two values:  ->{played} and ->{progress},
  		## played is the number of seconds of stream
  		## played..

  		print "\rplayed: $msg->{data}->{played}" if (defined($msg->{data}->{played}));
  	} elsif ($msg->{id} eq 'INPUT_EOF_WARNING') {
  	
  		## we got a message telling us that the 
  		## decoder system has come to the end of
  		## the current stream,  use it as a queue
  		## to shutdown..
  		
  		print "\nshutting down..\n";
  		$kernel->post('mad-decoder', 'decoder_shutdown');

  	} else {
  	
  		## unknown messages should never happen,  but
  		## we could do something interesting with them
  		## here..  for simplicity,  we just ignore it.
  		
  		return;
  	}
  }

  ## start this thing..
  $poe_kernel->run();
  exit();
  
  

DESCRIPTION

POE::Component::Audio::Mad::Dispatch implements a multiple dispatch 
front end component for the POE::Wheel::Audio::Mad mpeg decoder. It 
receieves status messages from the decoder and dispatches them to
other registered "listener" sessions.  All of the states listed in
POE::Wheel::Audio::Mad(3) under STATES will be defined within this
components session.  To control the decoder,  simply post the
appropriate POE::Wheel::Audio::Mad STATE to this session.

If you intend to implement a decoder that will be controlled and/or 
monitored by other POE::Session's,  then this is the module you want 
to be using.  If you wish to implement a decoder through an IPC
bridge,  you want POE::Component::Audio::Mad::Handle.

METHODS

create({ ..options.. })

This class method is used to create a new POE session for both the 
decoder core and the front end module.  This constructor does
not specify any options,  but options sent through this
constructor will be sent on to the decoder core.  For more 
information on options available to control the decoder core's
behaviour see POE::Component::Audio::Mad(3)

STATES

These states are specific to this component's session,  and allow
other sessions to register themselvs as a "listener" to specific
decoder status messages.  The states listed in POE::Component::Audio::Mad(3)
under STATES are also defined under this session and may be posted
to.

add_listener

This state adds a new session to the decoders event notification list.  It
accepts three arguments:  (session,  state,  events).  'session' is the name
of (or a reference to) a session that wishes to receive events,  'state' is
the name of a state within the 'session',  and 'events' is an arrayref listing
the names events one wishes to receive.  

This state will return your "listener id number" which is necessary if you wish 
to update the events you are listening for,  or to delete yourself from the event 
notification list.  If you wish to retrieve this number,  you must tell the POE
kernel to ->call() to this state rather than ->post() to it.

For a list of available event names,  see the documentation in 
POE::Component::Audio::Mad(3) section EVENTS.

update_listener

This state updates the list of events that a listener wishes to be notified
of.  It takes two arguments:  (listener id, events).  'listener id' is the
number that was returned to you when you called 'add_listener'.  events is
an arrayref containing an updated list of events you wish to receive.

del_listener

This state removes you from the event notification list.  It takes one
argument,  your 'listener id' which was returned to you when you 
called 'add_listener'.  This completely removes you from the event
notification list.

SEE ALSO

perl(1)

POE::Wheel::Audio::Mad(3)

AUTHOR

Mark McConnell, <mischke@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Mark McConnell

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