INetProvider

重要 注意 提醒

Coding Style wiki

---

INetProvider 定义 NetFrame 底层网络传输的标准行为，扮演「传输驱动层」的角色，将不同的通信库封装成统一接口，供上层的 NetNode 调用。内置提供 TCP、KCP 与 WebSocket 三种实现，也可自行实现此接口扩展其他传输协议。

命名空间	OxGFrame.NetFrame
类型	public interface
源码	INetProvider.cs

using OxGFrame.NetFrame;

声明

public interface INetProvider

内置实现

实现类	底层库	对应 NetOption	SendMessage 字符串发送
TcpNetProvider	Telepathy	TcpNetOption	不支持（抛出异常）
KcpNetProvider	kcp2k	KcpNetOption	不支持（抛出异常）
WebSocketNetProvider	UnityWebSocket	WebSocketNetOption	支持

提醒

• TcpNetProvider 底层的 Telepathy 已处理 TCP 拆包/粘包问题，会强制在每个数据包前加入 4 bytes 的长度头。
• KcpNetProvider 额外提供 SendBinary(KcpChannel kcpChannel, byte[] buffer) 重载，可指定以 Reliable / Unreliable 通道发送（通过 NetNode.GetNetProvider<KcpNetProvider>() 获取实例后调用）。

成员总览

事件

事件	说明
OnOpen	连接成功开启时触发。
OnBinary	接收到二进制数据时触发。
OnMessage	接收到字符串数据时触发。
OnError	通信发生错误时触发。
OnClose	连接关闭时触发。

方法

方法	说明
CreateConnect	依连接选项开启连接。
IsConnected	返回底层是否处于连接状态。
SendBinary	发送二进制数据。
SendMessage	发送字符串数据。
OnUpdate	驱动底层传输的轮询更新。
Close	关闭连接并清理资源。

---

OnOpen

event EventHandler<object> OnOpen

说明

连接成功开启时触发，payload 为连接信息。NetNode 订阅此事件以驱动 INetTips.OnConnected 与 Connected 回调。

提醒 内置实现的 payload：TcpNetProvider / KcpNetProvider 传入 0；WebSocketNetProvider 传入开启事件参数。

---

OnBinary

event EventHandler<byte[]> OnBinary

说明

接收到二进制数据时触发。NetNode 订阅此事件，并转发给 SetResponseBinaryHandler 所设置的处理器。

---

OnMessage

event EventHandler<string> OnMessage

说明

接收到字符串数据时触发。NetNode 订阅此事件，并转发给 SetResponseMessageHandler 所设置的处理器。

注意 内置实现中仅 WebSocketNetProvider 会触发此事件（TCP / KCP 一律以二进制接收）。

---

OnError

event EventHandler<object> OnError

说明

通信发生错误时触发，payload 为错误信息（内置实现皆传入错误信息字符串）。NetNode 据此驱动 INetTips.OnConnectionError。

---

OnClose

event EventHandler<object> OnClose

说明

连接关闭时触发，payload 为关闭信息。NetNode 据此驱动 INetTips.OnDisconnected，并在非主动关闭时启动自动重连流程。

提醒 内置实现的 payload：TcpNetProvider / KcpNetProvider 传入 -1；WebSocketNetProvider 传入关闭代码（Close Code）。

---

CreateConnect

void CreateConnect(NetOption netOption)

参数

参数	类型	说明
netOption	NetOption	连接选项。实现时需将其转换为对应的派生类（如 TcpNetOption）以获取连接参数。

说明

依连接选项创建并开启连接，由 NetNode.Connect 在连接流程启动时调用。连接成功后应触发 OnOpen 事件通知上层。

---

IsConnected

bool IsConnected()

返回值

bool — 底层传输处于连接状态返回 true。

说明

返回底层传输当前的连接状态。

---

SendBinary

bool SendBinary(byte[] buffer)

参数

参数	类型	说明
buffer	byte[]	要发送的二进制数据。

返回值

bool — 成功交付发送返回 true；未连接或发送失败返回 false。

说明

发送二进制数据，即 NetFrames.Send(byte[], int) 的底层实现。

---

SendMessage

bool SendMessage(string text)

参数

参数	类型	说明
text	string	要发送的字符串数据。

返回值

bool — 成功交付发送返回 true。

说明

发送字符串数据，即 NetFrames.Send(string, int) 的底层实现。

注意 并非所有协议都支持直接发送字符串，内置的 TcpNetProvider 与 KcpNetProvider 会抛出异常；自行实现时可视情况抛出异常，或将字符串转换为 UTF-8 二进制改走 SendBinary。

---

OnUpdate

void OnUpdate()

说明

驱动底层传输的轮询（Polling），由 NetManager 的更新器在每次更新通过 NetNode 调用。通常用于从接收队列提取数据包并触发事件；若底层库自带事件派发（如 UnityWebSocket），可留空实现。

重要 此方法会被高频调用，请确保其中的轮询逻辑足够轻量。

---

Close

void Close()

说明

断开连接并清理底层资源。

---

继承实现示例

以自定义传输库实现 INetProvider 的骨架如下：

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)
    {
        // 转换为对应的 NetOption 派生类，获取连接参数
        // var option = netOption as CustomNetOption;

        // 创建底层连接并绑定事件：
        // 开启 → this.OnOpen?.Invoke(this, payload)
        // 收包 → this.OnBinary?.Invoke(this, data)
        // 错误 → this.OnError?.Invoke(this, error)
        // 关闭 → this.OnClose?.Invoke(this, code)
    }

    public bool IsConnected()
    {
        // 返回底层连接状态
        return false;
    }

    public bool SendBinary(byte[] buffer)
    {
        // 发送二进制数据，成功交付返回 true
        return false;
    }

    public bool SendMessage(string text)
    {
        // 不支持字符串发送时，可抛出异常提示改用 SendBinary
        throw new NotSupportedException();
    }

    public void OnUpdate()
    {
        // 每次更新被调用，驱动底层轮询（提取数据包并触发事件）
    }

    public void Close()
    {
        // 断开连接并清理底层资源
    }
}

实现完成后，创建 NetNode 时传入即可：

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

---