# Protocol Tools 使用指南 > 本指南首次修订于：2025.6.13 > > 最后修改日期：2025.6.13 Protocol Tools允许您在任何通讯物理层发送信息、接受服务器返回的信息、过滤您的脏数据。 目前工具以发布+订阅的方式处理消息，后续会增加问答的方式处理消息。 本指南中，您将学到以下内容 - 如何在互联网&串口通讯&文件读写&进程吞吐中，发送您的请求，获取您的响应消息。 - 如何自定义消息类，发送您的消息，处理远端响应的消息。 - 自定义插拔式的开启或关闭消息处理功能。 - Protocol Tools的消息解耦原理 Protocol Tools 的结构如下 ```mermaid mindmap root((ProtocolTools)) EGMessage ProtocolSchedule Internet TCPClient TCPServer UDP MQTT SSH WebsocketClient WebsocketServer - Only Godot SerialPort Other FileStream Process Soft CommandLine ``` --- # 目录 [TOC] --- # 发送请求部分 ## 1. 定义您的请求 发送请求是通讯的第一步，如果您只需要连接到对应的服务器，接受对应的推送，而无需发送任何消息请移步至 [4. 定义您的响应](## 4. 定义您的响应) 新建一个结构类`DataStudent` ```csharp public struct DataStudent{ public string Name { get; set; } public int Age; public int ID; public DataStudent(string name,int age){ Name = name; Age = age; ID = 0; } } ``` 实现`IRequest`接口 `IRequest`包含两种输出最终发送结果的方法，如果您需要发送字符类型的数据格式，请实现`ToProtocolData`这个方法，如果您需要发送Hex类型的数据格式，请实现`ToProcotolByteData`这个方法。 注意：切勿实现两个方法，实现两个方法会同时发送字符类型+Hex类型两种数据格式的拼接（字符在前，Hex在后，因为字符根据Encoding会转码成未知的Hex数据，不推荐这样做），请实现其中一个，另外一个使用 `return null` 来填补空缺 ```csharp public struct DataStudent :IRequest{ public string Name { get; set; } public int Age; public int ID; public DataStudent(string name,int age){ Name = name; Age = age; ID = 0; } public string ToProtocolData() { return JsonConvert.SerializeObject(this); } public byte[] ToProtocolByteData() { return null; } } ``` ## 2. 发送您的请求 定义好您的请求后，在特定类的代码域里可以通过`this.EGSendMessage(T t)`发送您的请求，该类需要实现`IEGFramework` 该方法包含三个参数，实现`IRequest`的数据对象，发送对象（sender），以及协议类型。 发送对象一般为注册过的连接，包含IP地址以及端口等参数。 ```csharp public partial class ViewTestStudent : Node,IEGFramework { public override void _Ready() { this.EGSendMessage(new DataStudent(), "127.0.0.1:6000", ProtocolType.TCPClient); } } ``` ## 3. 设定您的发送间隔 您有没有发现，在您连续发送两条消息的时候，会产生一个0.1s左右的间隔，这个设计是为了防止连续多次发送消息的时候产生粘包现象，如果您需要立即发送，或者是延长这个间隔，可以通过以下方式设定发送间隔。 ```csharp // 两消息之间设定无间隔，立刻发送 this.GetModule().SetDelay(0); // 两消息之间设定间隔1s后再发送 this.GetModule().SetDelay(1000); ``` --- # 处理响应部分 ## 4. 定义您的响应 当连接到服务器时，如果您先发起请求，此时服务器会处理您的请求，有一段时间的空白期，或者该服务器是广播型服务器，即使不发送请求，也会推送数据给您。 新建一个结构类`DataStudent` ```csharp public struct DataStudent{ public string Name { get; set; } public int Age; public int ID; public DataStudent(string name,int age){ Name = name; Age = age; ID = 0; } } ``` 实现`IResponse`接口 `IResponse`包含两个输入数据的参数的方法用来过滤请求数据，建议您在这个方法内使用try catch 函数，以防止在程序处理异常时中断程序。如果您需要按照hex格式处理或者按照字符格式处理，请在这个函数里面写明对应的方法。 该实现方法会返回一个布尔值的变量，如果返回true，则认同这个消息为该类型的消息并对该条消息进行事件处理。如果返回false，则不认同，也不会对该条消息进行事件处理。 ```csharp public struct DataStudent :IResponse{ public string Name { get; set; } public int Age; public int ID; public DataStudent(string name,int age){ Name = name; Age = age; ID = 0; } public bool TrySetData(string protocolData, byte[] protocolBytes) { try { DataStudent input = JsonConvert.DeserializeObject(protocolData); if (this.Name == "") { return false; } else { this.Name = input.Name; this.Age = input.Age; this.ID = input.ID; return true; } } catch (System.Exception) { return false; } } } ``` ## 5. 注册响应的处理事件 定义好您的响应后，您可以通过注册响应处理事件`this.EGRegisterMessageEvent(Action a)`实现收到该消息并处理。注册事件中有三个参数可以选择，分别是收到的消息本身的结构体&对象，发送对象（sender），以及协议类型。消息可以无关通讯协议的类型，做到任何连接推送的消息都能收到并按照注册的事件进行处理。 同时，注册事件结束后，必须手动开启消息处理`EGOnMessage`，如果有需要，也可以在处理完消息之后关闭消息处理。 ```csharp public partial class ViewSaveSystem : Node,IEGFramework { public override void _Ready() { this.EGRegisterMessageEvent((data,sender,protocol) => { GD.Print(data.Name); // 关闭消息处理 this.EGOffMessage(); }); // 开启消息处理 this.EGOnMessage(); } } ``` ## 6. 启用对应的协议工具 在场景中的Node下，注册改脚本并启用对应的协议工具，切记，所有通讯工具必须实现`IProtocolReceived`接口，大部分可用的通讯工具均以EG开头。 ```csharp public partial class ViewSaveSystem : Node,IEGFramework { public override void _Ready() { // 启用对应的协议工具,此处以TCP客户端为例，需要其它协议开启对应的工具即可 this.EGEnabledProtocolTool(); // 处理消息部分 this.EGRegisterMessageEvent((data,sender,protocol) => { GD.Print(data.Name); // 关闭消息处理 this.EGOffMessage(); }); // 开启消息处理 this.EGOnMessage(); } } ``` # 补充一点私货 如果您对Protocol Tools的底层运行有兴趣，可以看看这部分。如有不足之处，欢迎提供相关改进建议。 ## 7.关于运行原理 本部分内容可能比较抽象，比较难以用文字表达，故设计了下列若干图来展示具体的内容部分。 ### 消息发送机制 对应函数EGSendMessage --- 注： 1. IProtocolSend表示实现了该发送消息接口的工具类。 2. RequestMsgEvent表示中途构建的消息结构体，结构体的发送内容必须包含：发送内容（实现IRequest，参考上述定义您的请求部分。）、发送对象、协议类型。 3. RequestCache为延时发送的队列，实现延时出队的功能。 4. OnRequest为EasyEvent类型的消息结构体委托，用于推送给所有注册发送功能的具体通讯对象。 --- ```mermaid flowchart LR 1([开始])--IRequest,sender,ProtocolType-->EGSendMessage-- new ResponseMsgEvent-->OnRequest IProtocolSend--EGRegisterSendAction-->OnRequest OnRequest--定时触发-->I(IProtocolSend)-->发送消息-->2([结束]) ``` 消息结构体构建 ```mermaid block-beta columns 6 doc["RequestMsgEvent"]:6 IRequest["IRequest"]:2 sender["sender"]:2 protocolType["protocolType"]:2 string["string"]:1 bytes["bytes"]:1 bytes space:2 tcp tcp["tcp&udp"]:1 etc["..."]:1 ``` 消息发送序列图 ```mermaid sequenceDiagram participant EGSendMessage participant RequestCache participant OnRequest participant IProtocolSend autonumber IProtocolSend->>OnRequest:Regist(SendAction) EGSendMessage->>OnRequest: (No Delay)RequestMsgEvent OnRequest->>IProtocolSend: Invoke(RequestMsgEvent) EGSendMessage->>+RequestCache: (Delay)Enqueue(RequestMsgEvent) loop Every 0.1s RequestCache->>RequestCache: TimerElapsed（delay--Default0.1s） RequestCache->>-OnRequest: Dequeue(RequestMsgEvent) end OnRequest->>IProtocolSend: Invoke(RequestMsgEvent) ``` ### 消息接收机制 对应EG(On&Off)Message，EGRegisterMessageEvent ```mermaid flowchart TD start([开始])-->SourceData subgraph ExecuteResponse SourceData--trysetData(string,bytes)-->IResponse IResponse--Construct-->ResponseMsgEvent end ResponseMsgEvent-->OnResponse EGRegisterMessageEvent-->OnResponse OnResponse--Invoke-->MessageEvent-->over([结束]) IProtocolReceived--GetReceivedMsg-->EGProtocolSchedule EGProtocolSchedule--CheckedProcess(Execute EveryFrame)-->SourceData EGProtocolSchedule<-->EGProtocolScheduleGodot ``` 消息结构体构建 ResponseMsgEvent ```mermaid block-beta columns 6 doc["ResponseMsgEvent"]:6 IResponse["IResponse"]:2 sender["sender"]:2 protocolType["protocolType"]:2 TrySetData["TrySetData(string,byte)"]:2 TrySetData space:2 tcp tcp["tcp&udp"]:1 etc["..."]:1 ``` ResponseMsg ```mermaid block-beta columns 6 doc["ResponseMsg"]:6 stringData["stringData"]:1 byteData["byteData"]:1 sender["sender"]:2 protocolType["protocolType"]:2 ``` 消息接收序列图 注：ReceiveResponse实际为EGOnMessage&EGOffMessage注册的委托 ```mermaid sequenceDiagram participant IProtocolReceived participant EGProtocolSchedule participant EGOnMessage participant OnDataReceived participant ReceiveResponse participant OnResponse participant EGRegisterMessageEvent autonumber EGOnMessage->>+ReceiveResponse:Type ReceiveResponse->>-OnDataReceived:Register EGRegisterMessageEvent->>+OnResponse:Register OnResponse->>-OnResponse:TypeCheck loop Every frame EGProtocolSchedule->>+IProtocolReceived:GetReceivedMsg(ResponseMsg) IProtocolReceived-->>IProtocolReceived:DataReceiveProcess IProtocolReceived->>-EGProtocolSchedule:ResponseMsg end EGProtocolSchedule->>OnDataReceived:ResponseMsg OnDataReceived->>+ReceiveResponse:IResponse,sender,protocolType ReceiveResponse->>ReceiveResponse:CheckIsSet ReceiveResponse->>-OnResponse:if(Set)-Invoke(ResponseMsgEvent) OnResponse->>EGRegisterMessageEvent:Execute ```