1.4 C99 API Overview

Overview

The C99 API is the flat C ABI entry point of the C++17 SDK. Callers only hold ArmHandle* , and all business capabilities are accessed through Arm_* functions.

Typical call order:

1. Arm_Create() creates the session handle
2. Arm_Connect() establishes the controller connection
3. Call module functions such as Arm_Info_* , Arm_Motion_* , and Arm_Program_*
4. Arm_Disconnect() disconnects
5. Arm_Destroy() releases the handle

Session Model

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);

Item	Description
Session object	ArmHandle*
Create / destroy	Arm_Create / Arm_Destroy
Connect / disconnect	Arm_Connect / Arm_Disconnect
Connection state	Arm_IsConnected returns non- 0 when connected
Multiple instances	Multiple handles are supported; each handle is an independent session

C99 Calling Convention

Convention	Description
Return codes	Most functions return int ; 0 means STATUS_CODE::OK
Data output	C99 returns data through out parameters, such as double* outValue or ArmMotionPose* outPose
String output	Uses char* outBuf + size_t bufSize ; the caller allocates the buffer
Array output	Uses outArray + maxCount + outCount ; the caller allocates array memory
count-only	Some array APIs allow outArray == NULL to query count only
Resource release	Handles such as ArmHandle* , ArmModbusSlaveHandle* , and ArmBasScriptHandle* require a matching Destroy

Module Groups

Group Page	Covered Headers	Main Content
4.1-arm	c_arm_core.h , c_arm_api.h	Session lifecycle, root entry
4.2-info	c_arm_info.h	Basic status, modes, permissions, control actions
4.3-alarm	c_arm_alarm.h	Alarm query and reset
4.4-motion	c_arm_motion.h	Motion, pose, payload
4.5-program	c_arm_program.h	Program execution and program poses
4.6-bas-script	c_arm_bas_script.h	BasScript builder
4.7-signals	c_arm_signals.h	IO read/write and pulse triggering
4.8-registers	c_arm_registers.h	R/PR/SR/MR/MH/MI
4.9-trajectory	c_arm_trajectory.h	Trajectory, path, and real-time trajectory
4.10-file-manager	c_arm_file_manager.h	Upload, download, delete, and search
4.11-jogging	c_arm_jogging.h	Step jogging, continuous jogging, stop
4.12-extension	c_arm_extension.h	Extension query, switching, and service calls
4.13-sub-pub	c_arm_sub_pub.h	WebSocket subscription/publish
4.14-modbus	c_arm_modbus.h	Modbus parameters, slave handles, and read/write
4.15-coordinate-system	c_arm_coordinate.h	User/tool coordinate system management

Common Types

Type	Description
ArmHandle	C99 SDK session handle type; callers only hold the pointer
ArmMotionPose	Motion pose, interpreted as joint or Cartesian by ArmPoseType
ArmSoftLimit	User soft limit
ArmPayloadInfo	Payload details
ArmPoseRegister	PR pose register
ArmRunningProgramInfo	Running program information
ArmAlarmInfo	Alarm information
ArmProgramPose	Program pose
ArmTrajectorySegmentC	Real-time trajectory segment
ArmFileInfo	File search result
ArmCoordinate / ArmCoordinateInfo	Coordinate system details and list item
ArmModbusSlaveHandle	Modbus slave handle
ArmBasScriptHandle	BasScript builder handle
ArmBasExtraParamHandle	BasScript extra parameter builder handle

Minimal Integration Example

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;
}

Differences from C++17

Capability	C++17	C99
Session model	Arm object	ArmHandle*
Module entry	arm.controllerInfo.GetServoStatus()	Arm_Info_GetServoStatus(h, &status)
Return value	STATUS_CODE or std::pair<T, STATUS_CODE>	int status code + out parameters
String return	std::string	char* + bufSize
Container return	std::vector<T>	Caller-provided array buffer
Callback parameter	Json::Value	UTF-8 JSON text
Lifecycle	C++ object destructor fallback	Caller must call Destroy explicitly