XScript 手册 · Chapter 16

COMMUNICATION — 通信通道控制

通过 COM["名称"] 访问在 Communication Editor 中注册的通信通道(TCP Server/Client、 Serial、Modbus、MES、AWS S3 等)。使用事件函数接收异步接收/连接事件, 并通过 WriteStrSendCustomData 进行发送。

基本示例

xscript
// 连接接收事件
COM["MES"].LinkModuleName = "MES";
COM["MES"].LinkFunctionName = "OnReceiveFromServer";
 
// 连接连接事件
COM["MES"].ConnectedLinkModuleName = "MES";
COM["MES"].ConnectedLinkFunctionName = "OnConnected";
 
FUNCTION OnReceiveFromServer(string data)
{
    Log("READ: '{0}'", data);
 
    array items = STR.ParseCommaString(data);
    for (i, 0, items.Count - 1)
    {
        string line = items[i];
        if (line == "")
        {
            continue;
        }
 
        array pair = STR.ParseSplitString(line, ":");
        string name = pair[0];
        string value = pair[1];
 
        if (TodoSomething(name, value) == false)
        {
            continue;
        }
    }
    return true;
}
 
FUNCTION SendToServer(string data)
{
    if (COM["MES"].WriteStr(data) == false)
    {
        return false;
    }
    return true;
}

实战示例 — TCP 客户端帧收发

构造带有 STX/ETX 的长度+单元编号帧并发送,解析响应后 进行超时等待。

xscript
FUNCTION Send(int unit, string cmd, string data, bool wait)
{
    if (COM["Cube"].IsOpen() == false)
    {
        return false;
    }
 
    int unit_no = Common::GetUnitNo(unit);
    ResponseOk = false;
    string sendData;
 
    if (STR.IsNullOrWhiteSpace(data))
    {
        sendData = MakeSendData(unit_no, cmd);
    }
    else
    {
        sendData = MakeSendData(unit_no, cmd + "," + data);
    }
 
    LastCommand = cmd;
 
    if (COM["Cube"].WriteStr(sendData) == false)
    {
        return false;
    }
 
    if (wait == false)
    {
        return true;
    }
 
    int start = SYS.GetTickCount();
    while (true)
    {
        if (ResponseOk)
        {
            break;
        }
        Sleep(20);
        if (SYS.GetTickCount() - start > TCP_TIMEOUT)
        {
            return false;
        }
    }
 
    return ReplyOk;
}

主要方法

连接控制

签名说明
bool Open(void)开始连接
void Close(void)结束连接
bool IsOpen(void)连接状态
bool IsLiveConnection(void)活动检查
bool OpenTcpIpServer(void) / void CloseServer(void) / bool IsOpenServer(void)服务器模式
int GetCount(void)已连接客户端数量

发送

签名说明
bool WriteStr(string data)字符串发送(协议封装)
bool WriteStrRaw(string data)原始发送
bool SendCustomData(string data)自定义格式发送
bool SendCustomData(string group, string data)指定分组发送
bool SendCommand(string command, string data = "")命令发送

接收 · 解析

签名说明
string ReceiveCustomData(string option = "")自定义格式接收
bool Parse(string data)执行已注册的解析器
void SeparateData(void)帧分离
void StartCustomReadThread(void) / void StopCustomReadThread(void)读取线程
bool ReadCustom(void)单次读取

值通道(计量设备)

签名说明
bool SetValue(double value) / double GetValue(bool wait = false)单一值
bool SetChannelValue(int channel, double value)按通道设置值
double GetChannelValue(int channel)查询通道值
bool SetChannelAll(double value)全部通道
void SetChannelMinMaxValue(int channel, double min, double max)通道范围

其他

签名说明
bool SetCustomConnectionParameters(void)重新设置连接参数
void SetPort(string portName)指定 Serial 端口
void IdleCheckFunc(void)Idle 检查回调
void SendLinkTest(void)发送链路测试帧
string GetDesc(void) / string ToString(void)信息字符串

主要属性

属性类型说明
Name / ClassNamestring标识
Address / PortName / BaudRate / IsBaudRateFix连接参数
Url / AccessKey / SecretKey / RegionstringHTTP/S3 参数
OpenOnStartbool启动时自动打开
Filterstring接收过滤器
MinDataSizeint最小帧大小
CurrentChannel / MaxChannel / IsChannel多通道
PacketStartDelimiter / PacketEndDelimiter / DataDelimiterstring帧分隔符
MaxValue / MinValueint值范围
IdleCheckTimeSec / LinkTestTimeMsecint周期
UseDebugLog / UseLinkTest / UseIdleTimeOut / UseInternalTimerbool选项
OnIdle / IsLinkTestOk / ResponseOkbool状态

事件函数约定

连接字段调用时机
LinkModuleName + LinkFunctionName数据接收
ConnectedLinkModuleName + ConnectedLinkFunctionName连接状态变化
OnParseFunctionName自定义解析器

提示

  • 接收回调在通信线程中被调用 — UI 更新务必通过调度器(dispatcher)进行。
  • 切勿使用无超时的 while 等待 → 用 SYS.GetTickCount() 管理已用时间(elapsed)。
  • 二进制协议采用 WriteStrRaw + PacketStartDelimiter/EndDelimiter 组合更稳定。
  • 服务器 API 调用优先使用 SYS.SendHttpGet/Post/Delete 辅助函数(检查 SYS.HTTP_ERROR_STR 返回值)。