1.4 C99 接口总览

概述

C99 接口是 C++17 SDK 的扁平 C ABI 入口。调用方只持有 ArmHandle* ，所有业务能力都通过 Arm_* 函数访问。

典型调用顺序：

1. Arm_Create() 创建会话句柄
2. Arm_Connect() 建立控制器连接
3. 调用 Arm_Info_* 、 Arm_Motion_* 、 Arm_Program_* 等模块函数
4. Arm_Disconnect() 断开连接
5. Arm_Destroy() 释放句柄

会话模型

ArmHandle* Arm_Create(void);
void Arm_Destroy(ArmHandle* h);
int Arm_Connect(ArmHandle* h, const char* controllerIp, const char* teachPanelIp);
void Arm_Disconnect(ArmHandle* h);
int Arm_IsConnected(ArmHandle* h);

项	说明
会话对象	ArmHandle*
创建 / 销毁	Arm_Create / Arm_Destroy
连接 / 断开	Arm_Connect / Arm_Disconnect
连接状态	Arm_IsConnected 返回非 0 表示已连接
多实例	支持多个 handle 并存；每个 handle 是独立会话

C99 调用约定

约定	说明
返回码	大多数函数返回 int ， 0 表示 STATUS_CODE::OK
数据输出	C99 通过 out 参数返回数据，例如 double* outValue 、 ArmMotionPose* outPose
字符串输出	使用 char* outBuf + size_t bufSize ，缓冲区由调用方分配
数组输出	使用 outArray + maxCount + outCount ，数组内存由调用方分配
count-only	部分数组接口允许 outArray == NULL 时只查询数量
资源释放	ArmHandle* 、 ArmModbusSlaveHandle* 、 ArmBasScriptHandle* 等句柄需要对应 Destroy

模块分组

分组页	覆盖头文件	主要内容
4.1-arm	include/c_arm_core.h 、 include/c_arm_api.h	会话生命周期、根入口
4.2-info	include/c_arm_info.h	基础状态、模式、权限和控制动作
4.3-alarm	include/c_arm_alarm.h	报警查询与复位
4.4-motion	include/c_arm_motion.h	运动、位姿、负载
4.5-program	include/c_arm_program.h	程序执行与程序点位
4.6-bas-script	include/c_arm_bas_script.h	BasScript 构造器
4.7-signals	include/c_arm_signals.h	IO 读写与脉冲
4.8-registers	include/c_arm_registers.h	R/PR/SR/MR/MH/MI
4.9-trajectory	include/c_arm_trajectory.h	轨迹、路径、实时轨迹
4.10-file-manager	include/c_arm_file_manager.h	上传、下载、搜索、存在性
4.11-jogging	include/c_arm_jogging.h	步进示教、连续点动、停止
4.12-extension	include/c_arm_extension.h	插件查询、切换、服务调用
4.13-sub-pub	include/c_arm_sub_pub.h	WebSocket 订阅发布
4.14-modbus	include/c_arm_modbus.h	Modbus 参数、从站句柄、读写和串口透传
4.15-coordinate-system	include/c_arm_coordinate.h	用户 / 工具坐标系管理

常用类型

类型	说明
ArmHandle	C99 SDK 会话句柄类型，调用方只持有指针
ArmMotionPose	运动位姿，按 ArmPoseType 解释为关节或笛卡尔
ArmSoftLimit	用户软限位
ArmPayloadInfo	负载详情
ArmPoseRegister	PR 位姿寄存器
ArmRunningProgramInfo	运行中程序信息
ArmAlarmInfo	报警信息
ArmProgramPose	程序点位
ArmTrajectorySegmentC	实时轨迹分片
ArmFileInfo	文件搜索结果
ArmCoordinate / ArmCoordinateInfo	坐标系详情与列表项
ArmModbusSlaveHandle	Modbus 从站句柄
ArmBasScriptHandle	BasScript 构造器句柄
ArmBasExtraParamHandle	BasScript 附加参数构造器句柄

最小接入示例

示例代码

mingw_c99/gcc_capi_info_read/src/main.c

#include <stdio.h>

#include "c_arm_api.h"

int main(void)
{
    // [ZH] 本示例使用 MinGW/GCC 直接调用 C99 接口，并通过 libAgilebotCppSdk.dll.a 链接 DLL。
    // [EN] This example uses MinGW/GCC to call the C99 API directly and links the DLL through libAgilebotCppSdk.dll.a.
    const char* controller_ip = "10.27.1.2";
    const char* teach_panel_ip = "10.27.1.102";
    int ret = 0;

    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[gcc_capi_info_read] 创建句柄失败 / Failed to create handle\n");
        return 1;
    }

    // [ZH] 连接前先查询一次状态，便于确认 import library、DLL 与基础句柄函数都可用。
    // [EN] Query once before connecting to validate the import library, DLL, and basic handle APIs.
    printf("[gcc_capi_info_read] 连接前状态 / State before connect: %d\n", Arm_IsConnected(handle));

    ret = Arm_Connect(handle, controller_ip, teach_panel_ip);
    if (ret != 0) {
        printf("[gcc_capi_info_read] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[gcc_capi_info_read] 连接后状态 / State after connect: %d\n", Arm_IsConnected(handle));

    // [ZH] 只调用读接口，适合作为客户 MinGW 环境的低风险联调模板。
    // [EN] Only read APIs are used, making this a low-risk integration template for customer MinGW environments.
    char version[128] = {0};
    ret = Arm_Info_GetControllerVersion(handle, version, sizeof(version));
    printf("[gcc_capi_info_read] GetControllerVersion 状态码 / Status code: %d, 版本 / Version: %s\n", ret, version);

    char model[128] = {0};
    ret = Arm_Info_GetArmModelInfo(handle, model, sizeof(model));
    printf("[gcc_capi_info_read] GetArmModelInfo 状态码 / Status code: %d, 型号 / Model: %s\n", ret, model);

    int op_mode = 0;
    ret = Arm_Info_GetOpMode(handle, &op_mode);
    printf("[gcc_capi_info_read] GetOpMode 状态码 / Status code: %d, 操作模式 / Operation mode: %d\n", ret, op_mode);

    int ctrl_status = 0;
    ret = Arm_Info_GetCtrlStatus(handle, &ctrl_status);
    printf("[gcc_capi_info_read] GetCtrlStatus 状态码 / Status code: %d, 控制器状态 / Controller status: %d\n", ret, ctrl_status);

    int robot_status = 0;
    ret = Arm_Info_GetRobotStatus(handle, &robot_status);
    printf("[gcc_capi_info_read] GetRobotStatus 状态码 / Status code: %d, 机器人状态 / Robot status: %d\n", ret, robot_status);

    int servo_status = 0;
    ret = Arm_Info_GetServoStatus(handle, &servo_status);
    printf("[gcc_capi_info_read] GetServoStatus 状态码 / Status code: %d, 伺服状态 / Servo status: %d\n", ret, servo_status);

    int soft_mode = 0;
    ret = Arm_Info_GetSoftMode(handle, &soft_mode);
    printf("[gcc_capi_info_read] GetSoftMode 状态码 / Status code: %d, 软模式 / Soft mode: %d\n", ret, soft_mode);

    // [ZH] 清理连接与句柄。
    // [EN] Clean up connection and handle.
    Arm_Disconnect(handle);
    printf("[gcc_capi_info_read] 断开后状态 / State after disconnect: %d\n", Arm_IsConnected(handle));
    Arm_Destroy(handle);
    printf("[gcc_capi_info_read] 示例结束 / Example finished\n");
    return 0;
}

与 C++17 的对外差异

能力	C++17	C99
会话模型	Arm 对象	ArmHandle*
模块入口	arm.controllerInfo.GetServoStatus()	Arm_Info_GetServoStatus(h, &status)
返回值	STATUS_CODE 或 std::pair<T, STATUS_CODE>	int 状态码 + out 参数
字符串返回	std::string	char* + bufSize
容器返回	std::vector<T>	调用方自备数组缓冲区
回调参数	Json::Value	UTF-8 JSON 文本
生命周期	C++ 对象析构兜底	调用方必须显式 Destroy