Net::Packet::Frame

Section: User Contributed Perl Documentation (3pm)
Updated: 2009-11-09
Index Return to Main Contents
 

NAME

Net::Packet::Frame - object encapsulator for Net::Packet layers  

SYNOPSIS

   require Net::Packet::Frame;

   # Because we passed a layer 3 object, a Net::Packet::DescL3 object 
   # will be created automatically, by default. See Net::Packet::Env 
   # regarding changing this behaviour. Same for Net::Packet::Dump.
   my $frame = Net::Packet::Frame->new(
      l3 => $ipv4,  # Net::Packet::IPv4 object
      l4 => $tcp,   # Net::Packet::TCP object
                    # (here, a SYN request, for example)
   );

   # Without retries
   $frame->send;
   sleep(3);
   if (my $reply = $frame->recv) {
      print $reply->l3->print."\n";
      print $reply->l4->print."\n";
   }

   # Or with retries
   for (1..3) {
      $frame->reSend;

      until ($Env->dump->timeout) {
         if (my $reply = $frame->recv) {
            print $reply->l3->print."\n";
            print $reply->l4->print."\n";
            last;
         }
      }
   }

 

DESCRIPTION

In Net::Packet, each sent and/or received frame is parsed and converted into a Net::Packet::Frame object. Basically, it encapsulates various layers (2, 3, 4 and 7) into an object, making it easy to get or set information about it.

When you create a frame object, a Net::Packet::Desc object is created if none is found in the default $Env object (from Net::Packet module), and a Net::Packet::Dump object is also created if none is found in this same $Env object. You can change this beheaviour, see Net::Packet::Env.

Two new invocation method exist, one with attributes passing, another with raw attribute. This second method is usually used internally, in order to unpack received frame into all corresponding layers.  

ATTRIBUTES

env
Stores the Net::Packet::Env object. The default is to use $Env from Net::Packet. So, you can send/recv frames to/from different environements.
raw
Pass this attribute when you want to decode a raw string captured from network. Usually used internally.
padding
In Ethernet world, a frame should be at least 60 bytes in length. So when you send frames at layer 2, a padding is added in order to achieve this length, avoiding a local memory leak to network. Also, when you receive a frame from network, this attribute is filled with what have been used to pad it. This padding feature currently works for IPv4 and ARP frames.
l2
Stores a layer 2 object. See Net::Packet for layer 2 classes hierarchy.
l3
Stores a layer 3 object. See Net::Packet for layer 3 classes hierarchy.
l4
Stores a layer 4 object. See Net::Packet for layer 4 classes hierarchy.
l7
Stores a layer 7 object. See Net::Packet::Layer7.
reply
When recv method has been called on a frame object, and a corresponding reply has been catched, a pointer is stored in this attribute.
timestamp
When a frame is packed/unpacked, the happening time is stored here.
encapsulate
Give the type of the first encapsulated layer. It is a requirement to parse a user provided raw string.
 

METHODS

new
Object constructor. If a $Env-desc> object does not exists, one is created by analyzing attributes (so, either one of Net::Packet::DescL2, Net::Packet::DescL3. Net::Packet::DescL4 cannot be created automatically for now). The same behaviour is true for $Env-dump> object. You can change this default creation behaviour, see Net::Packet::Env. Default values:

timestamp: gettimeofday(),

env: $Env

getLengthFromL7
getLengthFromL4
getLengthFromL3
getLengthFromL2
Returns the raw length in bytes from specified layer.
getLength
Alias for getLengthFromL3.
unpack
Unpacks the raw string from network into various layers. Returns 1 on success, undef on failure.
pack
Packs various layers into the raw string to send to network. Returns 1 on success, undef on failure.
send
On the first send invocation in your program, the previously created Net::Packet::Dump object is started (if available). That is, packet capturing is run. The timestamp attribute is set to the sending time. The env attribute is used to know where to send this frame.
reSend
Will call send method if no frame has been recv'd, that is the reply attribute is undef.
getFilter
Will return a string which is a pcap filter, and corresponding to what you should receive compared with the frame request.
recv
Searches framesSorted or frames from Net::Packet::Dump for a matching response. If a reply has already been received (that is reply attribute is already set), undef is returned. It no reply is received, return undef, else the Net::Packet::Frame response.
print
Just returns a string in a human readable format describing attributes found in the layer.
dump
Just returns a string in hexadecimal format which is how the layer appears on the network.
isEth
isRaw
isNull
isSll
isPpp
isArp
isIpv4
isIpv6
isIp - either IPv4 or IPv6
isPpplcp
isVlan
isPppoe
isLlc
isTcp
isUdp
isIcmpv4
isIcmp - currently only ICMPv4
isCdp
isStp
isOspf
isIgmpv4
is7
Returns 1 if the Net::Packet::Frame is of specified layer, 0 otherwise.
 

AUTHOR

Patrice <GomoR> Auffret  

COPYRIGHT AND LICENSE

Copyright (c) 2004-2009, Patrice <GomoR> Auffret

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

RELATED MODULES

NetPacket, Net::RawIP, Net::RawSock


 

Index

NAME
SYNOPSIS
DESCRIPTION
ATTRIBUTES
METHODS
AUTHOR
COPYRIGHT AND LICENSE
RELATED MODULES

This document was created by