Oakrey.Network.PacketCapture.Wrapper 2.0.3

Oakrey.Network.PacketCapture.Wrapper

A managed .NET wrapper for WinPcap/Npcap on Windows. Exposes packet capture, Berkeley Packet Filter (BPF) compilation, queue-based transmission, device configuration, and capture statistics through a P/Invoke layer over wpcap.dll.

• NuGet: Oakrey.Network.PacketCapture.Wrapper
• Repository: Azure DevOps
• License: MIT

Features

• Packet capture via pcap_next_ex and pcap_dispatch callback loop
• Berkeley Packet Filter (BPF) compilation and application (CompileFilter, SetFilter)
• Raw packet transmission (SendPacket) and queue-based batch transmission (SendQueue, AddPacket)
• Device configuration: kernel buffer size, capture mode, blocking/non-blocking mode, minimum copy size
• Capture statistics retrieval (GetCaptureStatistics)
• Network address parsing: IPv4, IPv6, MAC (AddressContainer)
• Safe handle types for all native resources (DeviceHandle, QueueHandle, DumpHandle, StatisticHandle)
• Utility extensions for unmanaged memory allocation and marshalling (PointerExtension)

Requirements

• .NET 10 (Windows only, net10.0-windows)
• Npcap or WinPcap installed on the target machine (wpcap.dll must be present)
• Administrator or elevated privileges are typically required for live capture

Installation

NuGet Package Manager

1. Open Visual Studio.
2. Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
3. Search for Oakrey.Network.PacketCapture.Wrapper and install.

.NET CLI

dotnet add package Oakrey.Network.PacketCapture.Wrapper

Package Manager Console

Install-Package Oakrey.Network.PacketCapture.Wrapper

Architecture

graph TD
    Consumer["Consumer code"]
    PCC["PacketCaptureWrapper\n(static extension methods)"]
    WCW["WindowsCaptureWrapper\n(Windows-specific extensions)"]
    SNM["SafeNativeMethods\n(P/Invoke to wpcap.dll)"]
    Handles["Handles\nDeviceHandle / QueueHandle\nDumpHandle / StatisticHandle"]
    DataTypes["DataTypes\nBPF / CaptureStatistics\nPacketCaptureHeader / etc."]
    Wpcap["wpcap.dll\n(Npcap / WinPcap)"]

    Consumer --> PCC
    Consumer --> WCW
    PCC --> SNM
    WCW --> SNM
    PCC --> Handles
    WCW --> Handles
    SNM --> Handles
    SNM --> DataTypes
    SNM --> Wpcap

Key types

Usage

The API is exposed as extension methods on DeviceHandle. All handle types implement IDisposable and should be used inside using blocks.

Read packets in a dispatch loop

// DeviceHandle is obtained from a higher-level device abstraction
// (e.g. Oakrey.Network.PacketCapture.Device).
using DeviceHandle handle = ...; // open device

handle.SetFilter("ip and tcp");

ReadResult result = handle.ReadPackets(
    (param, header, data) =>
    {
        PacketCaptureHeader pktHeader = header.ToStruct<PacketCaptureHeader>();
        byte[] bytes = new byte[pktHeader.CaptureLength];
        Marshal.Copy(data, bytes, 0, bytes.Length);
        // process bytes
    },
    packetCount: 100);

Read one packet at a time

IntPtr header = IntPtr.Zero;
IntPtr data   = IntPtr.Zero;
handle.GetNextPacketPointers(ref header, ref data);

Compile and apply a BPF filter manually

IntPtr bpfProgram = handle.CompileFilter("udp port 53", mask: 0);
// bpfProgram is freed automatically after SetFilter
handle.SetFilter("udp port 53");

Send a raw packet

byte[] rawPacket = ...; // pre-built Ethernet frame
handle.SendPacket(rawPacket, rawPacket.Length);

Queue-based batch transmission (Windows only)

using QueueHandle queue = ...;

PacketCaptureHeader header = new() { CaptureLength = (uint)packet.Length, PacketLength = (uint)packet.Length };
queue.AddPacket(packet, header);

handle.SendQueue(queue, SendMode.Synchronized);

Capture statistics

CaptureStatistics stats = handle.GetCaptureStatistics();
Console.WriteLine($"Received: {stats.Received}, Dropped: {stats.Dropped}");

Device configuration (Windows only)

handle.SetKernelBufferSize(4 * 1024 * 1024);   // 4 MB kernel buffer
handle.SetMode(CaptureMode.Capture);
handle.SetBlocking(false);
handle.MinimumDataSizeToCopy(1);

Library version

string? version = PacketCaptureWrapper.Version;
// e.g. "Npcap version 1.79, based on libpcap version 1.10.4"

Development notes

• The project enables AllowUnsafeBlocks for unmanaged memory operations.
• SafeNativeMethods is decorated with [SuppressUnmanagedCodeSecurity] for performance; callers are responsible for security validation.
• Most P/Invoke declarations use [LibraryImport] (source-generated marshalling, .NET 7+). A few fallbacks use [DllImport] where source generation is not applicable.
• PointerExtension provides Alloc/Free/ToStruct helpers used throughout the wrapper to reduce Marshal boilerplate.
• This library is intentionally low-level. For a higher-level device abstraction see Oakrey.Network.PacketCapture.Device.

Project information