DLL 版本信息

darra::ethercat::statics 命名空间提供 DLL 库的版本信息和元数据查询, 用于诊断、日志记录和兼容性检查。

通过 darra::ethercat::statics 静态函数访问。

版本信息属性

dll_version()

namespace darra::ethercat::statics {
std::optional<DllVersionInfo> dll_version(dll_t& dll);
}

获取完整的 DLL 版本信息结构。读取失败返回 std::nullopt。

返回值:

• std::optional<DllVersionInfo> — 包含版本号、构建日期、校验和等完整信息

相关结构:

struct DllVersionInfo {
    uint16_t major;          // 主版本号
    uint16_t minor;          // 次版本号
    uint16_t patch;          // 修订号
    uint16_t build;          // 构建号
    std::string build_date;  // 构建日期 (ISO 8601)
};

示例:

auto info = darra::ethercat::statics::dll_version(dll);
if (info) {
    printf("DLL 版本: %u.%u.%u.%u\n",
           info->major, info->minor, info->patch, info->build);
    printf("构建日期: %s\n", info->build_date.c_str());
}

版本号 / 构建日期 / 校验和

SDK 仅提供 dll_version() 一个版本查询入口。版本号字符串、构建日期、校验和等信息可直接从返回的 DllVersionInfo 结构字段组合得到，SDK 不再提供单独的 version_number() / build_date() / checksum() 函数。

完整示例

应用程序日志

在日志中记录 DLL 版本信息:

#include "ethercat.hpp"
using namespace darra::ethercat;

int main() {
    dll_t dll;
    auto info = statics::dll_version(dll);

    printf("=== Darra EtherCAT Master ===\n");
    if (info) {
        printf("DLL 版本: %u.%u.%u.%u\n",
               info->major, info->minor, info->patch, info->build);
        printf("构建日期: %s\n", info->build_date.c_str());
    }
    printf("============================\n");
    return 0;
}

版本兼容性检查

确保应用程序与 DLL 版本兼容:

bool check_minimum_version(dll_t& dll, int min_major, int min_minor) {
    auto info = darra::ethercat::statics::dll_version(dll);
    if (!info) {
        printf("错误: 无法获取 DLL 版本\n");
        return false;
    }
    if (info->major < min_major ||
        (info->major == min_major && info->minor < min_minor)) {
        printf("错误: DLL 版本过低 (%u.%u.%u.%u), 需要 v%d.%d+\n",
               info->major, info->minor, info->patch, info->build,
               min_major, min_minor);
        return false;
    }
    printf("DLL 版本兼容: %u.%u.%u.%u\n",
           info->major, info->minor, info->patch, info->build);
    return true;
}

诊断信息收集

生成诊断报告:

std::string generate_report(dll_t& dll) {
    std::ostringstream oss;
    oss << "=== 系统诊断报告 ===\n\n";
    oss << "DLL 信息:\n";
    auto info = darra::ethercat::statics::dll_version(dll);
    if (info) {
        oss << "  版本: " << info->major << "." << info->minor
            << "." << info->patch << "." << info->build << "\n";
        oss << "  构建: " << info->build_date << "\n";
    }
    return oss.str();
}

唯一标识符生成

为日志文件或会话生成唯一标识符:

std::string create_session_id(dll_t& dll) {
    auto info = darra::ethercat::statics::dll_version(dll);
    char ver[32] = "UNKNOWN";
    if (info)
        std::snprintf(ver, sizeof(ver), "%u_%u_%u_%u",
                      info->major, info->minor, info->patch, info->build);
    auto t = std::time(nullptr);
    char buf[32];
    std::strftime(buf, sizeof(buf), "%Y%m%d%H%M%S", std::localtime(&t));
    return std::string("SESSION_") + ver + "_" + buf;
}

授权状态 (License Status)

除了版本号, SDK 还提供运行时授权状态查询, 便于应用在启动时判断当前许可是否有效。

授权状态是一个枚举 enum class LicenseStatus (规范要求状态返回枚举, 不返回裸 int):

枚举值	数值	含义
NotActivated	0	未激活
Verifying	1	校验中
Verified	2	已验证 (有效)
Failed	3	失败
Expired	4	已过期

"有效"判据

有效授权的唯一判据 = 状态等于 Verified (== 2)。其余取值表示授权当前不可用, 应按对应原因处理 (激活 / 等待校验 / 续期)。

授权的状态查询接口 Authorization::GetLicenseStatus() 返回 LicenseStatus 枚举。版本信息 (本页 dll_version()) 与授权状态是两类独立信息: 版本用于兼容性诊断, 授权状态用于运行许可判断。激活操作步骤详见授权相关章节。

注意事项

版本管理

在生产环境中, 建议记录 DLL 版本信息到应用程序日志, 便于问题追溯和版本管理。

相关功能

版本信息常用于 主站构造 时的兼容性检查, 以及 错误处理 中的日志记录。