INetProvider

Important Attention Reminder

Coding Style wiki

---

INetProvider defines the standard behavior of the low-level network transport in NetFrame. Acting as the "transport driver layer", it wraps different communication libraries behind a unified interface consumed by the upper-level NetNode. Three implementations are built in — TCP, KCP, and WebSocket — and you can implement this interface yourself to support other transport protocols.

Namespace	OxGFrame.NetFrame
Type	public interface
Source	INetProvider.cs

using OxGFrame.NetFrame;

Declaration

public interface INetProvider

Built-in Implementations

Implementation	Underlying Library	NetOption	SendMessage (String Sending)
TcpNetProvider	Telepathy	TcpNetOption	Not supported (throws)
KcpNetProvider	kcp2k	KcpNetOption	Not supported (throws)
WebSocketNetProvider	UnityWebSocket	WebSocketNetOption	Supported

Reminder

• Telepathy, the library behind TcpNetProvider, already handles TCP packet framing (fragmentation/sticking) by prepending a 4-byte length header to every packet.
• KcpNetProvider provides an extra SendBinary(KcpChannel kcpChannel, byte[] buffer) overload to send through the Reliable / Unreliable channel explicitly (obtain the instance via NetNode.GetNetProvider<KcpNetProvider>()).

Member Overview

Events

Event	Description
OnOpen	Raised when the connection is successfully opened.
OnBinary	Raised when binary data is received.
OnMessage	Raised when string data is received.
OnError	Raised when a communication error occurs.
OnClose	Raised when the connection is closed.

Methods

Method	Description
CreateConnect	Opens a connection based on the connection options.
IsConnected	Returns whether the underlying transport is connected.
SendBinary	Sends binary data.
SendMessage	Sends string data.
OnUpdate	Drives the polling of the underlying transport.
Close	Closes the connection and cleans up resources.

---

OnOpen

event EventHandler<object> OnOpen

Description

Raised when the connection is successfully opened; the payload carries connection information. NetNode subscribes to this event to drive INetTips.OnConnected and the connected callback.

Reminder Built-in payloads: TcpNetProvider / KcpNetProvider pass 0; WebSocketNetProvider passes the open event args.

---

OnBinary

event EventHandler<byte[]> OnBinary

Description

Raised when binary data is received. NetNode subscribes to this event and forwards the data to the handler assigned via SetResponseBinaryHandler.

---

OnMessage

event EventHandler<string> OnMessage

Description

Raised when string data is received. NetNode subscribes to this event and forwards the data to the handler assigned via SetResponseMessageHandler.

Attention Among the built-in implementations, only WebSocketNetProvider raises this event (TCP / KCP always receive as binary).

---

OnError

event EventHandler<object> OnError

Description

Raised when a communication error occurs; the payload carries the error information (all built-in implementations pass an error message string). NetNode uses it to drive INetTips.OnConnectionError.

---

OnClose

event EventHandler<object> OnClose

Description

Raised when the connection is closed; the payload carries the close information. NetNode uses it to drive INetTips.OnDisconnected and, if the close was not requested manually, starts the auto-reconnection procedure.

Reminder Built-in payloads: TcpNetProvider / KcpNetProvider pass -1; WebSocketNetProvider passes the close code.

---

CreateConnect

void CreateConnect(NetOption netOption)

Parameters

Parameter	Type	Description
netOption	NetOption	Connection options. The implementation must cast it to the matching derived class (e.g., TcpNetOption) to read the connection parameters.

Description

Creates and opens the connection based on the connection options. Called by NetNode.Connect when the connection procedure starts. Once the connection is established, the implementation should raise OnOpen to notify the upper layer.

---

IsConnected

bool IsConnected()

Returns

bool — true if the underlying transport is connected.

Description

Returns the current connection state of the underlying transport.

---

SendBinary

bool SendBinary(byte[] buffer)

Parameters

Parameter	Type	Description
buffer	byte[]	Binary data to send.

Returns

bool — true if the data was successfully handed off for sending; false if not connected or sending failed.

Description

Sends binary data. This is the underlying implementation of NetFrames.Send(byte[], int).

---

SendMessage

bool SendMessage(string text)

Parameters

Parameter	Type	Description
text	string	String data to send.

Returns

bool — true if the message was successfully handed off for sending.

Description

Sends string data. This is the underlying implementation of NetFrames.Send(string, int).

Attention Not every protocol supports sending strings directly — the built-in TcpNetProvider and KcpNetProvider throw an exception. A custom implementation may either throw as well, or convert the string to UTF-8 bytes and send it via SendBinary.

---

OnUpdate

void OnUpdate()

Description

Drives the polling of the underlying transport. Called through NetNode by the NetManager updater on every update. Typically used to dequeue packets from the receive queue and raise events; if the underlying library dispatches events by itself (like UnityWebSocket), the implementation may be left empty.

Important This method is called at high frequency — keep the polling logic inside it lightweight.

---

Close

void Close()

Description

Closes the connection and cleans up the underlying resources.

---

Implementation Example

A skeleton for implementing INetProvider with a custom transport library:

using System;
using OxGFrame.NetFrame;

public class CustomNetProvider : INetProvider
{
    public event EventHandler<object> OnOpen;
    public event EventHandler<byte[]> OnBinary;
    public event EventHandler<string> OnMessage;
    public event EventHandler<object> OnError;
    public event EventHandler<object> OnClose;

    public void CreateConnect(NetOption netOption)
    {
        // Cast to the matching NetOption derived class to read the connection parameters
        // var option = netOption as CustomNetOption;

        // Create the underlying connection and bind its events:
        // opened   → this.OnOpen?.Invoke(this, payload)
        // received → this.OnBinary?.Invoke(this, data)
        // error    → this.OnError?.Invoke(this, error)
        // closed   → this.OnClose?.Invoke(this, code)
    }

    public bool IsConnected()
    {
        // Return the underlying connection state
        return false;
    }

    public bool SendBinary(byte[] buffer)
    {
        // Send binary data; return true when successfully handed off
        return false;
    }

    public bool SendMessage(string text)
    {
        // If string sending is not supported, throw to hint callers to use SendBinary
        throw new NotSupportedException();
    }

    public void OnUpdate()
    {
        // Called on every update to drive the underlying polling (dequeue packets and raise events)
    }

    public void Close()
    {
        // Close the connection and clean up underlying resources
    }
}

Once implemented, pass it in when creating a NetNode:

var netNode = new NetNode(new CustomNetProvider(), new NetTipsExample());
NetFrames.AddNetNode(netNode);

---