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);

---