SharpPcap Documentation

Packet.Net uses a nesting model rather than an inheritance model to represent network layers. Instead of a TcpPacket inheriting fields from an EthernetPacket, packets are composed of layers. A captured packet might follow a structure like: EthernetPacket $\rightarrow$ IPv4Packet $\rightarrow$ TcpPacket.

Accessing Nested Packets

Each packet contains a PayloadPacket property (of type PacketPayloadPacket) and a PayloadData property (of type byte[]).

To avoid manually traversing the PayloadPacket.PayloadPacket chain, use the Packet.Extract(Type type) method. This method uniformly searches the nested layers to find and return the first packet matching the specified type.

Recommended Approach: Instead of manual traversal or the deprecated GetEncapsulated() method, use:

TcpPacket tcpPacket = (TcpPacket)capturedPacket.Extract(typeof(TcpPacket));

For high-performance packet transmission, use the SendQueue class. This is a WinPcap-specific extension that buffers packets at the kernel level, reducing context switches compared to multiple SendPacket() calls.

Key Workflow

1. Initialize: Create a SendQueue with a specified size (in bytes).
2. Queue: Use SendQueue.Add(PcapHeader, buffer/Packet) to add packets. You can pass the same PcapHeader and data received from an OnPacketArrival event.
3. Transmit: Call SendQueue.Transmit(PcapDevice device, SendQueueTransmitModes transmitMode) to send the entire queue.
4. Modes: Using SendQueueTransmitModes.Synchronized ensures that the relative timestamps of the packets are respected during transmission, providing high precision at the cost of high CPU usage.
5. Cleanup: Call SendQueue.Dispose() to free associated buffers.

Warning: Ensure the link-layer of your source (e.g., a capture file) matches the PcapDataLink of the target adapter, otherwise transmission will be ineffective.

You can capture packets asynchronously by registering a handler to the OnPacketArrival event.

Configuration Options for Open()

• DeviceMode.Normal: Captures only packets addressed directly to the adapter.
• DeviceMode.Promiscuous: Captures all packets on the network segment, regardless of destination.
• read_timeout: Specifies the timeout in milliseconds. A value of 0 means no timeout (blocks indefinitely if no packets arrive), and -1 causes the read to return immediately.

Workflow

1. Register the OnPacketArrival event handler.
2. Call Open(DeviceMode mode, int read_timeout).
3. Call StartCapture() to begin non-blocking capture on a new thread.
4. Call StopCapture() to terminate the process.
5. Call Close() to release the device.

// Extract a device from the list
ICaptureDevice device = devices[i];

// Register our handler function to the 'packet arrival' event
device.OnPacketArrival += new SharpPcap.PacketArrivalEventHandler(device_OnPacketArrival);

// Open the device for capturing
int readTimeoutMilliseconds = 1000;
device.Open(DeviceMode.Promiscuous, readTimeoutMilliseconds);

Console.WriteLine("-- Listening on {0}, hit 'Enter' to stop...", device.Description);

// Start the capturing process
device.StartCapture();

// Wait for 'Enter' from the user.
Console.ReadLine();

// Stop the capturing process
device.StopCapture();

// Close the pcap device
device.Close();

// Implementation of the handler
private static void device_OnPacketArrival(object sender, CaptureEventArgs e)
{
    DateTime time = e.Packet.Timeval.Date;
    int len = e.Packet.Data.Length;
    Console.WriteLine("{0}:{1}:{2},{3} Len={4}",
        time.Hour, time.Minute, time.Second, time.Millisecond, len);
}

If you are using WinPcap on Windows, you can use CaptureMode.Statistics to gather network statistics efficiently. This mode uses kernel-level packet filters to classify incoming packets, minimizing data copies and context switches compared to traditional user-level calculation.

To use this feature:

1. Open the adapter using device.Open().
2. Set the device.Mode property to CaptureMode.Statistics.
3. Register a handler for the OnPcapStatistics event.
4. Call device.StartCapture() to begin gathering data.

Note: This feature is specific to WinPcap and will not work on other platforms or drivers.

// Register our handler function to the
// 'winpcap statistics' event
device.OnPcapStatistics +=
    new WinPcap.StatisticsModeEventHandler(device_OnPcapStatistics);

// Open the device for capturing
int readTimeoutMilliseconds = 1000;
device.Open(DeviceMode.Promiscuous, readTimeoutMilliseconds);

// Handle TCP packets only
device.Filter = "tcp";

// Set device to statistics mode
device.Mode = CaptureMode.Statistics;

// Start the capturing process
device.StartCapture();

// ... later ...
device.StopCapture();
device.Close();

To create a custom network packet, you instantiate individual protocol packets and then 'stitch' them together by assigning them to the PayloadPacket property of the layer above them.

Example: Constructing an Ethernet -> IPv4 -> TCP packet

using PacketDotNet;

// 1. Create the innermost layer (TCP)
ushort tcpSourcePort = 123;
ushort tcpDestinationPort = 321;
var tcpPacket = new TcpPacket(tcpSourcePort, tcpDestinationPort);

// 2. Create the middle layer (IPv4)
var ipSourceAddress = System.Net.IPAddress.Parse("192.168.1.1");
var ipDestinationAddress = System.Net.IPAddress.Parse("192.168.1.2");
var ipPacket = new IPv4Packet(ipSourceAddress, ipDestinationAddress);

// 3. Create the outermost layer (Ethernet)
var sourceHwAddress = "90-90-90-90-90-90";
var ethernetSourceHwAddress = System.Net.NetworkInformation.PhysicalAddress.Parse(sourceHwAddress);
var destinationHwAddress = "80-80-80-80-80-80";
var ethernetDestinationHwAddress = System.Net.NetworkInformation.PhysicalAddress.Parse(destinationHwAddress);

// EthernetPacketType.None allows the protocol type to be updated based on the payload
var ethernetPacket = new EthernetPacket(ethernetSourceHwAddress,
    ethernetDestinationHwAddress,
    EthernetPacketType.None);

// 4. Stitch the packets together
ipPacket.PayloadPacket = tcpPacket;
ethernetPacket.PayloadPacket = ipPacket;

// 5. Use the packet
Console.WriteLine(ethernetPacket.ToString());
byte[] packetBytes = ethernetPacket.Bytes;

using PacketDotNet;

ushort tcpSourcePort = 123;
ushort tcpDestinationPort = 321;
var tcpPacket = new TcpPacket(tcpSourcePort, tcpDestinationPort);

var ipSourceAddress = System.Net.IPAddress.Parse("192.168.1.1");
var ipDestinationAddress = System.Net.IPAddress.Parse("192.168.1.2");
var ipPacket = new IPv4Packet(ipSourceAddress, ipDestinationAddress);

var sourceHwAddress = "90-90-90-90-90-90";
var ethernetSourceHwAddress = System.Net.NetworkInformation.PhysicalAddress.Parse(sourceHwAddress);
var destinationHwAddress = "80-80-80-80-80-80";
var ethernetDestinationHwAddress = System.Net.NetworkInformation.PhysicalAddress.Parse(destinationHwAddress);

// NOTE: using EthernetPacketType.None to illustrate that the Ethernet
//       protocol type is updated based on the packet payload that is
//       assigned to that particular Ethernet packet
var ethernetPacket = new EthernetPacket(ethernetSourceHwAddress,
    ethernetDestinationHwAddress,
    EthernetPacketType.None);

// Now stitch all of the packets together
ipPacket.PayloadPacket = tcpPacket;
ethernetPacket.PayloadPacket = ipPacket;

// and print out the packet to see that it looks just like we wanted it to
Console.WriteLine(ethernetPacket.ToString());

// to retrieve the bytes that represent this newly created EthernetPacket use the Bytes property
byte[] packetBytes = ethernetPacket.Bytes;