NAME

       POE::Component::Pcap - POE Interface to Net::Pcap

SYNOPSIS

         use POE::Component::Pcap;

         POE::Component::Pcap->spawn(
                                     Alias => 'pcap',
                                     Device => 'eth0',
                                     Filter => 'host fooble or host blort',
                                     Dispatch => 'got_packet',
                                     Session => $my_session_id,
                                    );

         $poe_kernel->post( pcap => open_live =>
                            'eth0', 80, 1, 100 );

         $poe_kernel->post( pcap => set_filter => 'arp or host zooble' );

         $poe_kernel->post( pcap => set_dispatch => 'target_state' );

         $poe_kernel->post( pcap => 'run' );

         $poe_kernel->post( pcap => 'shutdown' );

DESCRIPTION

       POE::Component::Pcap provides a wrapper for using the Net::Pcap module from POE programs.
       The component creates a separate session which posts events to a specified session and
       state when packets are available.

   ARGUMENTS
       Alias
           The alias for the Pcap session.  Used to post events such as "run" and "shutdown" to
           control the component.  Defaults to "pcap" if not specified.

       Device
           As a shortcut, the device for Net::Pcap to watch may be specified when creating the
           component.  If this argument is used, Net::Pcap::open_live will be called with a
           snaplen of 80 octets, a timeout of 100ms, and the interface will be put in promiscuous
           mode.  If these values are not suitable, post an "open_live" event instead.

       Filter
           Another shortcut, calls Net::Pcap::compile and Net::Pcap::setfilter to set a packet
           filter.  This can only be used if the Device argument is also given; otherwise a
           "set_filter" event should be posted after an "open_live" event (since Net::Pcap must
           have a "pcap_t" descriptor to work with).

       Dispatch
       Session
           These specify the session and state to which events should be posted when packets are
           received.

   EVENTS
       The following examples assume that the component's alias has been set to the default value
       of pcap.

       open_live
             $_[KERNEL]->post( pcap => open_live
                               => 'device', [snaplen], [promsic?], [timeout] );

           Calls Net::Pcap::open_live.  The device name must be specified.  The snaplen,
           promiscuous, and timeout parameters default to 80, 1, and 100 respectively.  This
           event must be posted (or the Device argument must have been passed to spawn()) before
           anything else can be done with the component.

       set_filter
             $_[KERNEL]->post( pcap => set_filter
                               => 'host fooble or host blort' )

           Sets the Net::Pcap capture filter.  See tcpdump(8) for details on the filter language
           used by pcap(3).

       set_dispatch
             $_[KERNEL]->post( pcap => set_dispatch
                               => 'target_state', 'target_session' );

           Sets the state and session to which events are sent when packets are received.  The
           target session will default to the sender of the event if not specified.

           The event posted will have a single argument (available as ARG0) which will be an
           array reference containing the $hdr and $pkt parameters from Net::Pcap.  See the
           Net::Pcap(3) documentation for more details.

       run
             $_[KERNEL]->post( pcap => 'run' );

           Causes the component to register a select_read and start watching for packets.

       shutdown
             $_[KERNEL]->post( pcap => 'shutdown' );

           Shuts the component down.  Causes Net::Pcap::close to be called.

SEE ALSO

       Net::Pcap(3), pcap(3), tcpdump(8), POE(3), POE::Component(3)

AUTHOR

       Mike Fletcher, <fletch@phydeaux.org>

COPYRIGHT

       Copyright 2000-2001, Mike Fletcher.  All Rights Reserved.  This is free software; you may
       redistribute it and/or modify it under the same terms as Perl itself.