跳到主要内容

DLL 版本信息

提供 DLL 库的版本信息和元数据查询，用于诊断、日志记录和兼容性检查。

版本信息结构​

typedef struct {
    uint16_t major;          /* 主版本号 */
    uint16_t minor;          /* 次版本号 */
    uint16_t patch;          /* 修订号 */
    uint16_t build;          /* 构建号 */
    char     build_date[32]; /* 构建日期 (ISO 8601 格式) */
} version_info_t;
字段类型说明
majoruint16_t主版本号，主要功能变更时递增
minoruint16_t次版本号，新增功能时递增
patchuint16_t修订号，Bug 修复时递增
builduint16_t构建号，每次编译自动递增
build_datechar[32]构建日期（ISO 8601 格式，如 2026-03-23）

函数​

GetDllVersionInfo()​

const version_info_t* GetDllVersionInfo(void);

获取完整的 DLL 版本信息结构。

返回值:

  • const version_info_t* — 版本信息指针（内部指针，无需释放），失败返回 NULL

示例:

const version_info_t* ver = dll.GetDllVersionInfo();
if (ver) {
    printf("版本: %d.%d.%d.%d\n", ver->major, ver->minor, ver->patch, ver->build);
    printf("构建日期: %s\n", ver->build_date);
}

format_version()​

int format_version(const version_info_t* info, char* buf, int buf_size);

把版本信息格式化为 major.minor.patch.build 字符串,返回写入字节数。

char ver_str[32];
const version_info_t* ver = dll.GetDllVersionInfo();
format_version(ver, ver_str, sizeof(ver_str));
printf("版本: %s, 构建: %s\n", ver_str, ver->build_date);

完整示例​

应用启动版本检查​

#define DYNAMIC_LOAD
#include "ethercat.h"
#include <stdio.h>

int main(void)
{
    dll_t dll;
    if (!LOAD_DLL(&dll, "Darra.Core.dll")) {
        printf("错误: 无法加载 DLL\n");
        return 1;
    }

    /* 显示版本信息 */
    const version_info_t* ver = dll.GetDllVersionInfo();
    if (ver) {
        printf("=== Darra EtherCAT Master ===\n");
        printf("DLL 版本: %d.%d.%d.%d\n", ver->major, ver->minor, ver->patch, ver->build);
        printf("构建日期: %s\n", ver->build_date);
        printf("=============================\n");

        /* 版本兼容性检查 */
        if (ver->major < 1) {
            printf("错误: DLL 版本过低, 需要 v1.0+\n");
            UNLOAD_DLL(&dll);
            return 1;
        }
    }

    /* 业务逻辑... */

    UNLOAD_DLL(&dll);
    return 0;
}

版本兼容性检查​

#define DYNAMIC_LOAD
#include "ethercat.h"
#include <stdio.h>

BOOL check_min_version(dll_t* dll, int min_major, int min_minor)
{
    const version_info_t* ver = dll->GetDllVersionInfo();
    if (!ver) {
        printf("错误: 无法获取 DLL 版本\n");
        return FALSE;
    }

    if (ver->major < min_major ||
        (ver->major == min_major && ver->minor < min_minor)) {
        printf("错误: DLL 版本过低 (%d.%d.%d.%d), 需要 v%d.%d+\n",
               ver->major, ver->minor, ver->patch, ver->build,
               min_major, min_minor);
        return FALSE;
    }

    printf("DLL 版本兼容: %d.%d.%d.%d\n",
           ver->major, ver->minor, ver->patch, ver->build);
    return TRUE;
}

诊断信息收集​

#define DYNAMIC_LOAD
#include "ethercat.h"
#include <stdio.h>

void generate_diagnostics(dll_t* dll)
{
    printf("=== 系统诊断报告 ===\n\n");

    const version_info_t* ver = dll->GetDllVersionInfo();
    if (ver) {
        printf("DLL 信息:\n");
        printf("  版本: %d.%d.%d.%d\n", ver->major, ver->minor, ver->patch, ver->build);
        printf("  构建: %s\n", ver->build_date);
    }
    printf("\n");

#ifdef _WIN32
    printf("  平台: Windows\n");
#else
    printf("  平台: Linux\n");
#endif
}
版本管理

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

相关功能

版本信息常用于主站初始化时的兼容性检查，以及错误日志中记录环境信息。

版本格式化辅助 (utils/version_info.h)​

utils/version_info.h 提供一个轻量内联工具, 把 version_info_t 格式化为可读字符串, 自动根据 build 是否为 0 决定输出 4 段还是 3 段。

format_version()​

int format_version(const version_info_t* info,
                         char* buf, int buf_size);

把版本结构格式化为 MAJOR.MINOR.PATCH[.BUILD] 形式, 当 build == 0 时省略尾段。

参数:

  • info (const version_info_t*) — 由 GetDllVersionInfo() 返回的版本信息
  • buf (char*) — 输出缓冲区
  • buf_size (int) — 缓冲区字节数

返回值:

  • int — 写入的字符数 (不含末尾 NUL), 失败返回 0

示例:

#include "utils/version_info.h"

const version_info_t* ver = dll.GetDllVersionInfo();
char buf[32];
format_version(ver, buf, sizeof(buf));
printf("Darra Core %s\n", buf);

兼容性比较辅助​

可以基于 version_info_t 的字段直接比较, 推荐使用 32 位组合形式做版本门槛判断:

static inline uint32_t version_packed(const version_info_t* v)
{
    return ((uint32_t)v->major << 16) | (uint32_t)v->minor;
}

const version_info_t* ver = dll.GetDllVersionInfo();
if (version_packed(ver) < ((1u << 16) | 5u)) {
    fprintf(stderr, "需要 v1.5 或更高\n");
    return 1;
}
build 字段

开发版构建中 build 通常为非零的 CI 构建号, 正式发版可能置 0。比较时应避免依赖 build 字段做功能门槛, 优先比较 major.minor.patch。