4. 消息头解析：HSMS 消息头结构

HSMS（High-Speed SECS Message Services）消息头是设备端与主机之间所有通信的固定前置结构。无论消息类型是 Data Message 还是 Control Message，前 10 个字节都遵循完全相同的布局。解析引擎必须准确提取这 10 字节中的每一个字段，并正确处理 Big-Endian 字节序，才能将后续消息体交给正确的 Stream/Function 处理器。

4.1 HSMS 消息头 10 字节布局

下表列出了 HSMS 消息头各字段的偏移、长度、名称及用途。所有多字节字段均采用 Big-Endian（大端序）编码。

4.2 字节序处理：Big-Endian 详解

SECS/GEM 协议族规定所有多字节字段使用 Big-Endian（大端序）编码。这意味着最高有效字节（MSB）存储在最低内存地址。在 x86/ARM 等小端序平台上，解析引擎必须显式进行字节序转换。

以下代码展示了在 C++ 中从原始字节缓冲区安全提取 16 位 Big-Endian 整数的两种方式：

// 方式一：手动移位（无符号 16 位）
uint16_t read_uint16_be(const uint8_t* buf) {
    return (static_cast<uint16_t>(buf[0]) << 8) |
            static_cast<uint16_t>(buf[1]);
}

// 方式二：使用 ntohs（网络序转主机序）
#include <arpa/inet.h>
uint16_t session_id = ntohs(*(reinterpret_cast<const uint16_t*>(buf + 0)));

4.3 消息头解析状态机

设备端消息解析引擎通常使用有限状态机（FSM）来管理消息头的接收与验证。下图展示了从 TCP 字节流中解析 HSMS 消息头的核心状态转换：

4.4 字段详解与解析要点

4.4.1 Session ID（设备标识）

• 范围：0x0000 – 0xFFFE（有效设备 ID），0xFFFF 为广播地址。
• 解析动作：读取 2 字节 Big-Endian 值后，与设备自身配置的 Device ID 比对。不匹配时，根据设备策略决定丢弃或转发。
• 性能提示：Session ID 比较是消息头解析中最频繁的操作之一，建议使用位掩码快速过滤广播地址。

4.4.2 Header Byte Count（消息头长度）

• 固定值：0x000A（10 字节）。
• 校验逻辑：如果该字段不等于 10，说明协议版本不匹配或数据损坏，应立即丢弃消息。

4.4.3 Stream / Function（消息类型）

• Stream：1 字节无符号整数，范围 0–127。Stream 0 专用于控制消息（SType ≠ 0）。
• Function：1 字节无符号整数，范围 0–255。Function 0–63 为标准 SECS-II 消息，64–127 为设备自定义，128–255 保留。
• 解析动作：将 Stream 和 Function 组合为 SxFy 格式（如 S1F13），用于查找对应的消息处理器。

4.4.4 PType / SType（协议与会话类型）

• PType：处理类型。0 表示 SECS-II 数据，非 0 值在标准实现中通常被丢弃。
• SType：会话类型。0 表示 Data Message（普通 SECS-II 消息），1–9 表示 HSMS 控制消息（如 Select.req、Linktest.req）。
• 解析动作：SType 决定消息体解析路径：0 走 SECS-II 消息体解析器，非 0 走 HSMS 控制消息处理器。

4.4.5 System Bytes（系统事务 ID）

• 长度：2 字节，Big-Endian 编码。
• 用途：用于匹配请求与响应。设备端发送请求时生成唯一 System ID，接收响应时通过该 ID 查找等待队列中的回调。
• 性能提示：System ID 的查找通常使用哈希表（unordered_map），键为 16 位无符号整数，查找时间复杂度 O(1)。

4.5 消息头解析的 C++ 实现骨架

以下代码展示了设备端消息头解析的核心结构体与解析函数。该实现注重内存安全与字节序正确性：

#include <cstdint>
#include <cstring>
#include <arpa/inet.h>

// HSMS 消息头结构体（主机字节序）
struct HsmsHeader {
    uint16_t session_id;
    uint16_t header_byte_count;
    uint8_t  stream;
    uint8_t  function;
    uint8_t  ptype;
    uint8_t  stype;
    uint16_t system_bytes;
} __attribute__((packed));

// 从网络字节序缓冲区解析消息头
bool parse_hsms_header(const uint8_t* raw_buf, HsmsHeader& out) {
    // 1. 读取多字节字段（Big-Endian -> 主机序）
    out.session_id       = ntohs(*(reinterpret_cast<const uint16_t*>(raw_buf + 0)));
    out.header_byte_count = ntohs(*(reinterpret_cast<const uint16_t*>(raw_buf + 2)));
    out.stream           = raw_buf[4];
    out.function         = raw_buf[5];
    out.ptype            = raw_buf[6];
    out.stype            = raw_buf[7];
    out.system_bytes     = ntohs(*(reinterpret_cast<const uint16_t*>(raw_buf + 8)));

    // 2. 校验 Header Byte Count
    if (out.header_byte_count != 10) {
        return false;  // 协议错误
    }

    // 3. 校验 PType（仅支持 SECS-II）
    if (out.ptype != 0) {
        return false;
    }

    return true;
}

4.6 常见解析错误与避坑指南