Table of Contents

Class IpPacket

Namespace
VpnHood.Net.Packets
Assembly
VpnHood.Net.Packets.dll

Represents an IPv4 or IPv6 packet over a buffer, which it reads and writes in place.

public abstract class IpPacket : IDisposable
Inheritance
IpPacket
Implements
Derived
Inherited Members

Remarks

The packet makes no copy: its fields are read from and written to the buffer it was made on, so a change through the packet shows in the buffer. A change made to the buffer around the packet shows in the next read, except in what the packet keeps: SourceAddress and DestinationAddress, made once, and an IPv6 packet's extension-header layout, read when it is parsed. Make one with PacketBuilder, or with the IpV4Packet and IpV6Packet constructors.

A packet made on a PacketMemory that gives it the memory, from an IMemoryOwner<T> or an array rented from an ArrayPool<T>, owns that memory, and Dispose() returns it once; then Buffer throws ObjectDisposedException, and every view taken from the packet before, such as its Payload or a TcpPacket, must no longer be used. A packet never disposed never returns its memory, which is left to the garbage collector. A packet made on a Memory<T> or an array leaves it to the caller. An instance is not thread-safe.

Constructors

IpPacket(PacketMemory)

Represents an IPv4 or IPv6 packet over a buffer, which it reads and writes in place.

protected IpPacket(PacketMemory memory)

Parameters

memory PacketMemory

The packet's bytes, exactly as long as the packet, and who takes them back when it is disposed.

Remarks

The packet makes no copy: its fields are read from and written to the buffer it was made on, so a change through the packet shows in the buffer. A change made to the buffer around the packet shows in the next read, except in what the packet keeps: SourceAddress and DestinationAddress, made once, and an IPv6 packet's extension-header layout, read when it is parsed. Make one with PacketBuilder, or with the IpV4Packet and IpV6Packet constructors.

A packet made on a PacketMemory that gives it the memory, from an IMemoryOwner<T> or an array rented from an ArrayPool<T>, owns that memory, and Dispose() returns it once; then Buffer throws ObjectDisposedException, and every view taken from the packet before, such as its Payload or a TcpPacket, must no longer be used. A packet never disposed never returns its memory, which is left to the garbage collector. A packet made on a Memory<T> or an array leaves it to the caller. An instance is not thread-safe.

Properties

Buffer

Gets the packet's bytes, header and payload.

public Memory<byte> Buffer { get; }

Property Value

Memory<byte>

Exceptions

ObjectDisposedException

The packet is disposed.

DestinationAddress

Gets or sets the destination address.

public IPAddress DestinationAddress { get; set; }

Property Value

IPAddress

Remarks

The getter makes the IPAddress once and returns the same instance until the address changes through this packet. Code that runs per packet reads DestinationAddressValue, which makes no object.

Exceptions

ArgumentNullException

The value is null.

ArgumentException

The value is not of the packet's IP version.

DestinationAddressSpan

Gets or sets the destination address as the header's bytes: 4 for IPv4, 16 for IPv6.

public ReadOnlySpan<byte> DestinationAddressSpan { get; set; }

Property Value

ReadOnlySpan<byte>

Remarks

The getter returns a view of the header, not a copy.

Exceptions

ArgumentException

The value's length is not that of the packet's IP version.

DestinationAddressValue

Gets or sets the destination address as a value.

public IpAddressValue DestinationAddressValue { get; set; }

Property Value

IpAddressValue

Remarks

The getter makes no object: it reads the header, or the IPAddress the packet keeps for DestinationAddress, which carries the scope id a set gave it. A set writes the address's bytes; a header has no room for a scope id, so a scoped address is kept as that IPAddress, as the DestinationAddress setter keeps its value, and an address without one drops the kept address.

Exceptions

ArgumentException

The value is not of the packet's IP version, or holds no address.

Header

Gets the bytes before the upper layer: the IP header with its options, and IPv6's extension headers.

public abstract Memory<byte> Header { get; }

Property Value

Memory<byte>

IsFragment

Gets a value indicating whether the packet is a fragment: a piece of a datagram, whose upper-layer packet no single piece holds whole.

public abstract bool IsFragment { get; }

Property Value

bool

IsV4

Gets whether the packet is an IPv4 packet.

public bool IsV4 { get; }

Property Value

bool

true if the packet is IPv4; otherwise, false.

IsV6

Gets whether the packet is an IPv6 packet.

public bool IsV6 { get; }

Property Value

bool

true if the packet is IPv6; otherwise, false.

PacketLength

Gets the packet's length in bytes, header included. It can be read after the packet is disposed.

public int PacketLength { get; }

Property Value

int

Payload

Gets the bytes after Header: the upper-layer packet, such as a TCP segment.

public Memory<byte> Payload { get; }

Property Value

Memory<byte>

Exceptions

ObjectDisposedException

The packet is disposed.

PayloadPacket

Gets or sets the parsed form of the packet's payload, such as a TcpPacket, or null when none has been made.

public IPayloadPacket? PayloadPacket { get; set; }

Property Value

IPayloadPacket

Remarks

The Extract and Build methods of IpPacketExtensions set it and return it on later calls.

Exceptions

InvalidOperationException

The value's buffer is not this packet's Payload.

Protocol

Gets the protocol of the upper layer the payload carries, such as TCP.

public abstract IpProtocol Protocol { get; }

Property Value

IpProtocol

Remarks

An IPv6 packet reads through its extension headers to the upper layer; when it stops at one it does not read through, it names that header instead (see HasUnreadExtensionHeader).

SourceAddress

Gets or sets the source address.

public IPAddress SourceAddress { get; set; }

Property Value

IPAddress

Remarks

The getter makes the IPAddress once and returns the same instance until the address changes through this packet. Code that runs per packet reads SourceAddressValue, which makes no object.

Exceptions

ArgumentNullException

The value is null.

ArgumentException

The value is not of the packet's IP version.

SourceAddressSpan

Gets or sets the source address as the header's bytes: 4 for IPv4, 16 for IPv6.

public ReadOnlySpan<byte> SourceAddressSpan { get; set; }

Property Value

ReadOnlySpan<byte>

Remarks

The getter returns a view of the header, not a copy.

Exceptions

ArgumentException

The value's length is not that of the packet's IP version.

SourceAddressValue

Gets or sets the source address as a value.

public IpAddressValue SourceAddressValue { get; set; }

Property Value

IpAddressValue

Remarks

The getter makes no object: it reads the header, or the IPAddress the packet keeps for SourceAddress, which carries the scope id a set gave it. A set writes the address's bytes; a header has no room for a scope id, so a scoped address is kept as that IPAddress, as the SourceAddress setter keeps its value, and an address without one drops the kept address.

Exceptions

ArgumentException

The value is not of the packet's IP version, or holds no address.

TimeToLive

Gets or sets the number of hops the packet may still take: IPv4's time to live, IPv6's hop limit.

public abstract byte TimeToLive { get; set; }

Property Value

byte

Version

Gets the packet's IP version.

public IpVersion Version { get; }

Property Value

IpVersion

Methods

Dispose()

Disposes the packet and returns the memory it owns, if any. Its buffer must not be used afterwards.

public void Dispose()

Dispose(bool)

Returns the memory the packet owns, if any, and marks the packet disposed. A second call does nothing.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

GetPacketVersion(ReadOnlySpan<byte>)

Reads the IP version from a packet's first byte, without checking it.

public static IpVersion GetPacketVersion(ReadOnlySpan<byte> buffer)

Parameters

buffer ReadOnlySpan<byte>

The packet's bytes.

Returns

IpVersion

The version field; a value other than 4 or 6 means the bytes are no IP packet.

Exceptions

IndexOutOfRangeException

buffer is empty.

ToString()

Returns a one-line description of the packet for logs: its addresses, protocol and lengths.

public override string ToString()

Returns

string

The description; for a disposed packet, only its length.