NAME

Net::Frame::Dump::Online - tcpdump like implementation, online mode

SYNOPSIS

   use Net::Frame::Dump::Online;

   #
   # Simply create a Dump object
   #
   my $oDump = Net::Frame::Dump::Online->new(
      dev => 'eth0',
   );

   $oDump->start;

   # Gather frames
   while (1) {
      if (my $f = $oDump->next) {
         my $raw            = $f->{raw};
         my $firstLayerType = $f->{firstLayer};
         my $timestamp      = $f->{timestamp};
      }
   }

   $oDump->stop;

   #
   # Create a Dump object, using on-event loop
   #
   sub callOnRecv {
      my ($h, $data) = @_;
      print "Data: $data\n";
      my $oSimple = Net::Frame::Simple->newFromDump($h);
      print $oSimple->print."\n";
   }

   my $oDumpEvent = Net::Frame::Dump::Online->new(
      dev         => 'eth0',
      onRecv      => \&callOnRecv,
      onRecvCount => 1,
      onRecvData  => 'test',
   );

   # Will block here, until $onRecvCount packets read, or a stop() call has 
   # been performed.
   $oDumpEvent->start;

   #
   # Default parameters on creation
   #
   my $oDumpDefault = Net::Frame::Dump::Online->new(
      dev            => undef,
      timeoutOnNext  => 3,
      timeout        => 0,
      promisc        => 0,
      unlinkOnStop   => 1,
      file           => "netframe-tmp-$$.$int.pcap",
      filter         => '',
      overwrite      => 0,
      isRunning      => 0,
      keepTimestamp  => 0,
      onRecvCount    => -1,
      frames         => [],
   );

DESCRIPTION

This module implements a tcpdump-like program, for live capture from networks.

ATTRIBUTES

dev: The network interface to listen on. No default value.
timeoutOnNext: Each time you call next method, an internal counter is updated. This counter tells you if you have not received any data since timeoutOnNext seconds. When a timeout occurred, timeout is set to true.
timeout: When timeoutOnNext seconds has been reached, this variable is set to true, and never reset. See timeoutReset if you want to reset it.
snaplen: If you want to capture a different snaplen, set it a number. Default to 1514.
promisc: By default, interface is not put into promiscuous mode, set this parameter to true if you want it.
unlinkOnStop: When you call stop method, the generated .pcap file is removed, unless you set this parameter to a false value.
onRecv: If you place a reference to a sub in this attribute, it will be called each time a packet is received on the interface. See SYNOPSIS for an example usage.
onRecvData: This parameter will store additional data to be passed to onRecv callback.
onRecvCount: By default, it is set to read forever packets that reach your network interface. Set it to a positive value to read only onRecvCount frames.

The following are inherited attributes:

file: Name of the generated .pcap file. See SYNOPSIS for the default name.
filter: Pcap filter to use. Default to no filter.
overwrite: Overwrites a .pcap file that already exists. Default to not.
firstLayer: Stores information about the first layer type contained on read frame. This attribute is filled only after a call to start method.
isRunning: Returns true if a call to start has been done, false otherwise or if a call to stop has been done.
keepTimestamp: Sometimes, when frames are captured and saved to a .pcap file, timestamps sucks. That is, you send a frame, and receive the reply, but your request appear to have been sent after the reply. So, to correct that, you can use Net::Frame::Dump own timestamping system. The default is 0. Set it manually to 1 if you need original .pcap frames timestamps.

METHODS

new
new (hash): Object constructor. You can pass attributes that will overwrite default ones. See SYNOPSIS for default values.
start: When you want to start reading frames from network, call this method.
stop: When you want to stop reading frames from network, call this method.
next: Returns the next captured frame; undef if none awaiting. Each time this method is called, a comparison is done to see if no frame has been captured during timeoutOnNext number of seconds. If so, timeout attribute is set to 1 to reflect the pending timeout.
store (Net::Frame::Simple object): This method will store internally, sorted, the Net::Frame::Simple object passed as a single parameter. getKey methods, implemented in various Net::Frame::Layer objects will be used to efficiently retrieve (via getKeyReverse method) frames.
Basically, it is used to make recv method (from Net::Frame::Simple) to retrieve quickly the reply frame for a request frame.
getFramesFor (Net::Frame::Simple object): This will return an array of possible reply frames for the specified Net::Frame::Simple object. For example, reply frames for a UDP probe will be all the frames which have the same source port and destination port as the request.
flush: Will flush stored frames, the one which have been stored via store method.
timeoutReset: Reset the internal timeout state (timeout attribute).
getStats: Tries to get packet statistics on an open descriptor. It returns a reference to a hash that has to following fields: ps_recv, ps_drop, ps_ifdrop.
isFather
isSon: These methods will tell you if your current process is respectively the father, or son process of Net::Frame::Dump::Online object.

AUTHOR

Patrice <GomoR> Auffret

COPYRIGHT AND LICENSE

You may distribute this module under the terms of the Artistic license. See LICENSE.Artistic file in the source distribution archive.