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.