Table of Contents

Class PacketHandler

Namespace
Shard.Network
Assembly
Shard.Network.dll

Provides outbound routing and inbound packet dispatch.

public abstract class PacketHandler : IPacketReceiver, IConnectionHandler
Inheritance
PacketHandler
Implements
Inherited Members

Constructors

PacketHandler(IChannelConnection)

Initializes a packet handler over the base connection.

public PacketHandler(IChannelConnection channel)

Parameters

channel IChannelConnection

The base connection owned by the handler.

Fields

Channels

The channels affiliated with this handler. Channel 0 is the base channel. Other indices are auxiliary streams.

protected readonly IChannelConnection?[] Channels

Field Value

IChannelConnection[]

QueuePackets

Determines whether to queue packets or send them immediately.

protected bool QueuePackets

Field Value

bool

QueuedPackets

The number of packets currently queued by this handler. Accessed atomically using Interlocked.

protected int QueuedPackets

Field Value

int

Properties

AuxiliaryChannelsCount

Gets the number of currently open auxiliary streams.

public int AuxiliaryChannelsCount { get; }

Property Value

int

Channel

Gets the base game-channel connection.

public IChannelConnection Channel { get; }

Property Value

IChannelConnection

Exceptions

InvalidOperationException

Thrown when the base channel has not been initialized.

DisconnectedReason

Gets the reason for the most recent disconnect.

public PacketHandler.DisconnectReason DisconnectedReason { get; }

Property Value

PacketHandler.DisconnectReason

IsRegistered

Indicates whether this handler currently owns a registered connection phase.

protected bool IsRegistered { get; }

Property Value

bool

Methods

Closed(string?)

Notifies the handler that its connection has closed.

public void Closed(string? reason)

Parameters

reason string

The best-effort transport close reason, if one is available.

CompareAndSetChannel(StreamType, IChannelConnection?, IChannelConnection?)

Atomically replaces the channel for the specified auxiliary stream type only if it currently matches the expected value.

public bool CompareAndSetChannel(StreamType type, IChannelConnection? expected, IChannelConnection? newValue)

Parameters

type StreamType

The auxiliary stream type.

expected IChannelConnection

The expected current channel, or null if no channel is expected.

newValue IChannelConnection

The new channel to associate, or null to remove the current channel.

Returns

bool

true if the operation succeeded; otherwise, false.

Remarks

This prevents a closing stream from overwriting a newly registered replacement channel.

Exceptions

ArgumentException

Thrown if type is Hytale.Protocol.Packets.Stream.StreamType.Game.

Disconnect(FormattedMessage)

Disconnects connection specified formatted message.

public void Disconnect(FormattedMessage message)

Parameters

message FormattedMessage

formatted disconnect message.

GetChannel(NetworkChannel)

Gets the connection for the specified network channel.

public IChannelConnection? GetChannel(NetworkChannel channel)

Parameters

channel NetworkChannel

The network channel.

Returns

IChannelConnection

The connection for the specified channel, or null if no connection has been assigned.

GetChannel(StreamType)

Returns the channel for the given stream type, or null if not set.

public IChannelConnection? GetChannel(StreamType type)

Parameters

type StreamType

The stream type

Returns

IChannelConnection

the channel for the stream type, or null if not set

GetIdentifier() 

public abstract string GetIdentifier()

Returns

string

the unique identifier for this handler

Handle(int, IToServerPacket)

Handles a decoded inbound packet using its exact wire ID.

public void Handle(int packetId, IToServerPacket packet)

Parameters

packetId int

The packet ID produced by the decoder.

packet IToServerPacket

The decoded packet instance.

Remarks

This is the normal codec path. Inbound adapters run before the decoded override, which runs before the callback registered for that wire ID and the unhandled fallback.

HandleClientDisconnect(ClientDisconnect)

Handles a client initiated close without allowing a stale handler to close a newer one.

protected void HandleClientDisconnect(ClientDisconnect packet)

Parameters

packet ClientDisconnect

OnClosed(string?)

Called once when the owning connection reaches its terminal state.

protected virtual void OnClosed(string? reason)

Parameters

reason string

The first best-effort transport close reason.

OnDisconnect(FormattedMessage)

Performs the actual disconnect operation.

protected virtual void OnDisconnect(FormattedMessage message)

Parameters

message FormattedMessage

The formatted disconnect message.

OnRegistered(IChannelConnection)

Called when this handler has been registered with a connection.

protected virtual void OnRegistered(IChannelConnection connection)

Parameters

connection IChannelConnection

The connection this handler was registered with.

OnUnhandledPacket(IToServerPacket)

Called when no typed receive handler is registered for a decoded packet.

protected virtual void OnUnhandledPacket(IToServerPacket packet)

Parameters

packet IToServerPacket

The decoded packet without a registered owner.

OnUnregistered()

Called after this handler has been unregistered and its internal state has been cleaned up.

protected virtual void OnUnregistered()

Register(int, Action<IToServerPacket>)

Registers the callback that owns one decoded packet ID.

protected void Register(int packetId, Action<IToServerPacket> handler)

Parameters

packetId int

The decoded wire ID routed to the callback.

handler Action<IToServerPacket>

The callback that handles packets decoded with that ID.

Exceptions

ArgumentOutOfRangeException

Thrown when packetId is negative.

InvalidOperationException

Thrown when the same packet ID is registered more than once.

RegisterHandlers()

Registers typed inbound packet callbacks for this handler instance.

protected virtual void RegisterHandlers()

Registered(IChannelConnection)

Registers this handler with the specified connection.

public void Registered(IChannelConnection connection)

Parameters

connection IChannelConnection

The connection this handler is associated with.

SetChannel(NetworkChannel, IChannelConnection?)

Sets the connection associated with the specified network channel.

public void SetChannel(NetworkChannel networkChannel, IChannelConnection? channel)

Parameters

networkChannel NetworkChannel

The network channel.

channel IChannelConnection

The connection to associate with the channel, or null to clear it.

SetChannel(StreamType, IChannelConnection?)

Sets or removes a channel for the given auxiliary stream type.

public void SetChannel(StreamType type, IChannelConnection? channel)

Parameters

type StreamType

The stream type

channel IChannelConnection

The channel, or null to remove

Exceptions

ArgumentException

Thrown if type is Hytale.Protocol.Packets.Stream.StreamType.Game.

SetQueuePackets(bool)

Sets whether packets should be queued or sent immediately.

public void SetQueuePackets(bool queuePackets)

Parameters

queuePackets bool

true to queue outgoing packets; otherwise, false to send them immediately.

TryDisconnectCurrent(string)

Closes the connection only while this handler still owns it.

protected bool TryDisconnectCurrent(string reason)

Parameters

reason string

Returns

bool

TryFlush()

Attempts to flush any queued outbound packets for this handler.

public void TryFlush()

Remarks

If no packets have been queued since the last flush, this method returns without flushing any channels.

TryHandleDecoded(int, IToServerPacket)

Gives a derived handler the first chance to process a decoded packet.

protected virtual bool TryHandleDecoded(int packetId, IToServerPacket packet)

Parameters

packetId int

The validated packet ID produced by the decoder.

packet IToServerPacket

The decoded packet instance.

Returns

bool

true when the derived handler claimed the packet.

Unregistered()

Unregisters this handler and releases any pending resources.

public void Unregistered()

Write(IToClientPacket)

Writes an outbound packet after processing it through the registered outbound packet filters and creating a cached copy before sending.

public void Write(IToClientPacket packet)

Parameters

packet IToClientPacket

The packet to send.

Remarks

A cached copy of the packet is created before it is queued for transmission, ensuring that subsequent modifications cannot race with the network write.

Write(params IToClientPacket[])

Writes multiple outbound packets to the same channel.

public void Write(params IToClientPacket[] packets)

Parameters

packets IToClientPacket[]

The packets to send.

Remarks

Each packet is processed through the registered outbound packet filters and cached before being queued for transmission. All packets must target the same network channel.

Exceptions

ArgumentException

Thrown if the packets do not all target the same channel.

Write(IReadOnlyList<IToClientPacket>, IToClientPacket)

Writes a collection of outbound packets followed by a final packet that completes the operation.

public void Write(IReadOnlyList<IToClientPacket> packets, IToClientPacket finalPacket)

Parameters

packets IReadOnlyList<IToClientPacket>

The packets containing the payload.

finalPacket IToClientPacket

The packet that completes the operation.

Remarks

This overload is intended for payloads that are split across multiple packets and finalized by a single packet that references the preceding data. All packets must target the same network channel.

Exceptions

ArgumentException

Thrown if the packets do not all target the same channel.

WriteNoCache(IToClientPacket)

Writes an outbound packet after processing it through the registered outbound packet filters without creating a cached copy.

public void WriteNoCache(IToClientPacket packet)

Parameters

packet IToClientPacket

The packet to send.

Remarks

The original packet instance is sent directly. This should only be used when it is guaranteed that the packet will not be modified after being queued for transmission.

WriteNoCache(params IToClientPacket[])

Writes multiple outbound packets same channel without creating cached copies.

public void WriteNoCache(params IToClientPacket[] packets)

Parameters

packets IToClientPacket[]

packets to send.

Remarks

Use only for packet instances that will not be mutated after being queued. Outbound filters still run before packets are sent.

Exceptions

ArgumentException

Thrown if the packets do not all target the same channel.

WriteNoCache(IReadOnlyList<IToClientPacket>, IToClientPacket)

Writes collection outbound packets followed by final packet without creating cached copies.

public void WriteNoCache(IReadOnlyList<IToClientPacket> packets, IToClientPacket finalPacket)

Parameters

packets IReadOnlyList<IToClientPacket>

packets containing payload.

finalPacket IToClientPacket

packet completes operation.

Remarks

Use only for packet instances that will not be mutated after being queued. This overload preserves grouped write/flush behavior for split payload packets.

Exceptions

ArgumentException

Thrown if the packets do not all target the same channel.