Oakrey.Network.PacketCapture.Device 2.0.4

Oakrey.Network.PacketCapture.Device

High-level .NET device abstraction over Oakrey.Network.PacketCapture.Wrapper. Provides concrete device types for live capture, pcap file I/O, statistics mode, and queue-based transmission on Windows.

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

Features

• Live packet capture with background capture loop (StartCapture / StopCapture) and single-packet polling (GetNextPacket)
• Rx observable stream of PacketAndDevice via IObservable<PacketAndDevice> on all device types
• BPF filter support inherited from the wrapper layer
• pcap file reading (CaptureFileReaderDevice) and writing (CaptureFileWriterDevice) with configurable FileMode
• Statistics-only capture mode (StatisticCaptureDevice) as IObservable<StatisticData>
• Queue-based batch packet transmission (SendQueue, SendWholeQueue) with SendMode.Synchronized / Unsynchronized
• Windows-specific device extensions (WindowCaptureDevice): kernel buffer size, minimum data size to copy, OpenFlags, remote authentication
• AdapterSpecifications with IPv4, IPv6, MAC address enumeration and gateway resolution
• Strongly-typed exceptions: CaptureException, DeviceNotReadyException, InvalidOperationDuringBackgroundCaptureException, NotSupportedOnCaptureFileException

Requirements

• .NET 10 (Windows only, net10.0-windows)
• Npcap or WinPcap installed on the target machine
• 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.Device and install.

.NET CLI

dotnet add package Oakrey.Network.PacketCapture.Device

Package Manager Console

Install-Package Oakrey.Network.PacketCapture.Device

Architecture

classDiagram
    direction TB

    class AdapterBase {
        +Open()
        +Close()
        +StartCapture()
        +StopCapture()
        +GetNextPacket() RawCapture
        +SendPacket(packet)
        +IObservable~PacketAndDevice~
    }

    class CaptureLiveDevice {
        +NonBlockingMode bool
        +Open(DeviceMode, int)
        +SendRawPacket(byte[], int)
    }

    class WindowCaptureDevice {
        +KernelBufferSize int
        +MinimumDataSizeToCopy(int)
        +Open(OpenFlags, int, RemoteAuthentication)
        +SendWholeQueue(SendQueue, SendMode)
    }

    class CaptureFileReaderDevice {
        +FileName string
        +FileBytesSize long
    }

    class CaptureFileWriterDevice {
        +Write(RawCapture)
        +Flush()
    }

    class StatisticCaptureDevice {
        +Open(OpenFlags, int, RemoteAuthentication)
        +StartCapture()
        +StopCapture()
        +IObservable~StatisticData~
    }

    class SendQueue {
        +Add(byte[])
        +Add(RawCapture)
        +Transmit(WindowCaptureDevice, SendMode)
        +CurrentQueueLength int
    }

    AdapterBase <|-- CaptureLiveDevice
    CaptureLiveDevice <|-- WindowCaptureDevice
    AdapterBase <|-- CaptureFileReaderDevice
    AdapterBase <|-- CaptureFileWriterDevice
    StatisticCaptureDevice --> CaptureLiveDevice
    WindowCaptureDevice --> SendQueue

Key types

Usage

Enumerate live devices

// DeviceHandle.FindAllDevices returns InterfaceDescriptionInfo structs
// which are used to construct AdapterSpecifications.
// Typically done via a device enumerator in the application layer.
AdapterSpecifications spec = ...; // from device enumeration
using CaptureLiveDevice device = new(spec);

Background capture with Rx

using WindowCaptureDevice device = new(spec);
device.Open(DeviceMode.Promiscuous, readTimeoutMs: 1000);
device.SetFilter("ip");

using IDisposable subscription = device.Subscribe(packetAndDevice =>
{
    RawCapture raw = packetAndDevice.Packet;
    Console.WriteLine($"Captured {raw.Data.Length} bytes on {raw.LinkLayerType}");
});

device.StartCapture();
// ... wait / process
device.StopCapture();

Single-packet polling

device.Open(DeviceMode.Normal, readTimeoutMs: 500);
RawCapture packet = device.GetNextPacket();

pcap file read

using CaptureFileReaderDevice reader = new("capture.pcap");
// reader is opened in the constructor
using IDisposable sub = reader.Subscribe(p => Console.WriteLine(p.Packet.Data.Length));
reader.StartCapture();

pcap file write

using CaptureFileWriterDevice writer = new("output.pcap", FileMode.Create);
writer.Write(rawCapture);
writer.Flush();

Write file linked to a live device (preserves link layer and snapshot length)

using CaptureFileWriterDevice writer = new(device, "output.pcap");
using IDisposable sub = device.Subscribe(p => writer.Write(p.Packet));
device.StartCapture();

Queue-based batch transmission

SendQueue queue = new(maximumSize: 1024 * 1024);
queue.Add(rawBytes);
queue.Add(rawCapture);

device.SendWholeQueue(queue, SendMode.Synchronized);
queue.Dispose();

Statistics mode

using StatisticCaptureDevice stats = new(spec);
stats.Open(OpenFlags.Promiscuous, readTimeoutMilliseconds: 1000);

using IDisposable sub = stats.Subscribe(data =>
    Console.WriteLine($"Received: {data.ReceivedPackets}, Dropped: {data.DroppedPackets}"));

stats.StartCapture();

Windows-specific device options

using WindowCaptureDevice device = new(spec);
device.Open(OpenFlags.Promiscuous | OpenFlags.NoCaptureLocal, readTimeoutMs: 1000);
device.KernelBufferSize = 4 * 1024 * 1024;
device.MinimumDataSizeToCopy(1);

Development notes

• All device types implement IDisposable. Use using or explicit Dispose() / Close() calls to release native handles.
• AdapterBase manages a background Thread for the capture loop. StopCapture() signals the loop and joins the thread before returning.
• StatisticCaptureDevice internally wraps a CaptureLiveDevice opened in CaptureMode.Statistics and republishes events through its own ReplaySubject<StatisticData>.
• CaptureFileWriterDevice does not support FileMode.Append � this is enforced with an explicit exception at construction time.
• SendQueue is backed by a native pcap_send_queue* through QueueHandle. Call Dispose() explicitly; it does not implement IDisposable via using pattern automatically in all flows.
• This library depends on System.Reactive (Rx.NET 6.1) and Oakrey.Collections.

Project information