跳转至

API 约定

本文档描述 One SDK 两套接口（C API 和 .NET API）共同遵守的设计约定。

错误模型

C API：返回码

C API 所有 DLL* 函数返回 ErrorCode 枚举值。调用方必须在返回值非 NoError 时进行处理：

ErrorCode err = DLLSysConnect(&handle);
if (err != NoError) {
    // 查询详细错误信息
    char detail[256];
    DLLGetLastCommandDetail(detail, sizeof(detail));
}

.NET API：异常

.NET API 将所有 ErrorCode 映射为 OneException 及其子类，通过 ExceptionResolver 在 P/Invoke 边界自动转换。调用方通过捕获 OneException 处理错误：

try {
    controller.Commands.Motion.MoveAbs("X", 10.0, 10.0);
}
catch (OneException ex) {
    Console.WriteLine($"控制器错误: {ex.Message}");
}

详见 Exceptions。

句柄模型

C API

DLLSysConnect 通过输出参数 INT_PTR* phClientHandle 返回客户端句柄。该句柄后续用于所有操作，生命周期由调用方管理。DLLSysDisconnect 释放句柄。

.NET API

Controller 门面类内部管理原生句柄，进程级单例 Controller.ConnectedController 持有当前连接实例。调用 Controller.Connect() 建立连接，Controller.Disconnect() 断开并释放资源。

缓冲区 in/out 约定

C API

模式 约定
输入（in） 调用方分配并填充，函数读取后返回
输出（out） 调用方分配，* outValue 写入结果；int* inOutCount 同时用于传入缓冲区容量和传出实际写入大小
字符串 char* outBuffer, int bufferSize，调用方保证缓冲区足够大

.NET API

  • 字符串参数直接使用 string / StringBuilder，SDK 内部处理编解码
  • 数组参数按 C API 约定，SDK 负责边界检查

平台限制

项目 说明
仅 x64 One SDK 仅支持 Windows x64，不支持 x86

连接与寻址

默认地址

控制器默认监听 127.0.0.1:60049（回环地址）。Controller.Connect() 使用该默认地址。

自定义地址与控制器发现

.NET SDK 不提供客户网络配置 API。控制器目标地址与控制器发现由 Setup Manager 应用统一配置：在 Setup Manager 中连接目标控制器后，SDK 进程即可使用默认地址 127.0.0.1:60049 连接。

C/C++ 客户可继续使用 DLLSetControllerAddress / DLLDiscoverControllers（见 C API 参考）。

Controller 单例限制

Controller.Connect() 是进程级单例：同一进程中同时只能有一个活动连接。新调用 Connect 前自动断开旧连接。ConnectedController 静态属性获取当前连接实例。

线程模型

约束 说明
线程安全 SDK 内部通过锁保护共享状态，支持多线程调用不同实例方法
UI 线程 WPF/WinForms 应用中，UI 线程直接调用 SDK 方法无需切换线程（内部自动 dispatch）
事件 .NET SDK 当前无公开事件回调；轴故障与运动完成通过状态查询（Commands.Status）获取

相关页面