4.12 C99 Extension Interface

Overview

C99 Extension is used to query robot-body plugins, toggle plugin enabled state, and call EasyService. JSON results are returned through char* + bufSize .

Prerequisites and Server Ports

Item	Description
Connection dependency	Arm_Extension_GetList , Arm_Extension_Get , Arm_Extension_Toggle , and Arm_Extension_CallService require Arm_Connect() to complete first
Address dependency	Extension APIs use the teach pendant address bound after Arm_Connect() . If not connected or the address is unavailable, they return a not-connected status code
GetRobotIp	Can be called before connection, but not every runtime environment can infer a valid IP. If it cannot infer one, it outputs an empty string
JSON output	All JSON text is output through the caller-provided char* + buf_size

Port	Purpose
5613	Robot-body Pure Web service, used by Arm_Extension_GetRobotIp() environment detection
5615	Robot-body plugin list and detail service
5616	Robot-body EasyService call service

Interface Signatures

Arm_Extension_GetRobotIp

int Arm_Extension_GetRobotIp(ArmHandle* h, char* out_buf, size_t buf_size);

Item	Description
Description	Infers or reads the robot IP from the robot-body runtime environment
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first out_buf : char* , output string buffer allocated by the caller buf_size : size_t , output buffer size, including space for the trailing \0
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	Unsupported robot-body runtime environments return success and output an empty string. If the output buffer is insufficient, the function returns according to the status code

Arm_Extension_GetList

int Arm_Extension_GetList(ArmHandle* h, char* out_buf, size_t buf_size);

Item	Description
Description	Queries the robot-body plugin list
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first out_buf : char* , output string buffer allocated by the caller buf_size : size_t , output buffer size, including space for the trailing \0
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	On success, outputs compact JSON for the plugin list. For field semantics, see Extension types

Arm_Extension_Get

int Arm_Extension_Get(ArmHandle* h, const char* name, char* out_buf, size_t buf_size);

Item	Description
Description	Queries details for one robot-body plugin
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first name : const char* , plugin name. It must not be empty, and may contain only A-Z a-z 0-9 . _ - out_buf : char* , output string buffer allocated by the caller buf_size : size_t , output buffer size, including space for the trailing \0
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	On success, outputs compact JSON for one plugin's details

Arm_Extension_Toggle

int Arm_Extension_Toggle(ArmHandle* h, const char* name);

Item	Description
Description	Toggles plugin enabled state
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first name : const char* , plugin name. It must not be empty, and may contain only A-Z a-z 0-9 . _ -
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	Changes plugin enabled state and has no output buffer

Arm_Extension_CallService

int Arm_Extension_CallService(ArmHandle* h, const char* name, const char* command, const char* params_json, char* out_buf, size_t buf_size);

Item	Description
Description	Calls a plugin EasyService
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first name : const char* , plugin name. It must not be empty, and may contain only A-Z a-z 0-9 . _ - command : const char* , service command name. It must not be empty, and may contain only A-Z a-z 0-9 . _ - params_json : const char* , request parameter JSON. NULL or empty string means no parameters; when non-empty, the root type must be an object out_buf : char* , output string buffer allocated by the caller buf_size : size_t , output buffer size, including space for the trailing \0
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	On success, outputs compact JSON for the EasyService result . If result is missing or null , returns an error code

Parameters and Buffer Rules

Item	Rule
h	Must not be null
out_buf / buf_size	Must be valid for string-output APIs
Buffer too small	Returns BUFFER_TOO_SMALL and writes an empty string
name / command	Must not be empty, and may contain only A-Z a-z 0-9 . _ -
params_json	NULL or empty string means no parameters
params_json root type	Must be a JSON object
params_json value types	Only strings, finite numbers, and booleans are supported

Behavior Conventions

• Arm_Extension_GetRobotIp returns OK + empty string in unsupported robot-body runtime environments.
• Arm_Extension_GetList / Arm_Extension_Get output compact JSON. For field semantics, see 2.4-extension-types .
• Arm_Extension_GetList / Arm_Extension_Get return an error code when the HTTP status is not 200 , JSON parsing fails, or the returned structure does not match expectations.
• On success, Arm_Extension_CallService outputs compact JSON for result ; if the result is a string, the output keeps the quotes.
• When params_json is {} , no query string is appended.
• Keys and values in params_json are flattened into the query string. Arrays and nested objects are not supported.
• If result is missing or null , OTHER_ERR is returned.
• Arm_Extension_Toggle changes plugin state and has no output buffer. The toggle operation uses a longer HTTP timeout.

Minimal Call Example

#include <stdio.h>     // Standard output for printing the plugin list
#include "c_arm_api.h" // C99 SDK umbrella header

int main(void)
{
    ArmHandle* h = Arm_Create();
    char listJson[4096] = {0};
    if (h == NULL) {
        return 1;
    }

    if (Arm_Connect(h, "10.27.1.254", NULL) != 0) {
        Arm_Destroy(h);
        return 1;
    }

    int ret = Arm_Extension_GetList(h, listJson, sizeof(listJson));
    if (ret == 0) {
        printf("extensions=%s\n", listJson);
    }
    Arm_Disconnect(h);
    Arm_Destroy(h);
    return ret == 0 ? 0 : 1;
}

Scenario Examples

The snippets below assume there is already a connected ArmHandle* h .

Query Robot IP and Plugin List

char robotIp[128] = {0};
char listJson[4096] = {0};
int ipRet = Arm_Extension_GetRobotIp(h, robotIp, sizeof(robotIp));
int listRet = Arm_Extension_GetList(h, listJson, sizeof(listJson));
(void)ipRet;
(void)listRet;

Query Details and Call a Service

char detailJson[4096] = {0};
char resultJson[4096] = {0};
int getRet = Arm_Extension_Get(h, "demo_extension", detailJson, sizeof(detailJson));
int callRet = Arm_Extension_CallService(h, "demo_extension", "echo", "{\"example\":\"sdk\"}", resultJson, sizeof(resultJson));
(void)getRet;
(void)callRet;

Toggle a Plugin

/* int toggleRet = Arm_Extension_Toggle(h, "demo_extension"); */

Example code:

c99/extension_basic/src/main.cpp

#include <stdio.h>

extern "C" {
#include "c_arm_api.h"
}

int main(void)
{
    // [ZH] 本示例直接在源码中写死连接地址，不解析命令行参数。
    // [EN] This example hard-codes the connection addresses in the source code and does not parse command-line arguments.
    // [ZH] 创建并连接 SDK 句柄。
    // [EN] Create the SDK handle and connect to the robot.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_extension] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_extension] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_extension] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 顺序执行全部插件接口。
    // [EN] Execute all extension APIs in sequence.
    char robotIp[256] = {0};
    char listJson[4096] = {0};
    char detailJson[4096] = {0};
    char resultJson[4096] = {0};
    ret = Arm_Extension_GetRobotIp(handle, robotIp, sizeof(robotIp));
    printf("[c99_extension] GetRobotIp 状态码 / GetRobotIp status code: %d, 机器人 IP / Robot IP: %s\n", ret, robotIp);
    ret = Arm_Extension_GetList(handle, listJson, sizeof(listJson));
    printf("[c99_extension] GetList 状态码 / GetList status code: %d, 列表 JSON / List JSON: %s\n", ret, listJson);
    ret = Arm_Extension_Get(handle, "demo", detailJson, sizeof(detailJson));
    printf("[c99_extension] Get 状态码 / Get status code: %d, 详情 JSON / Detail JSON: %s\n", ret, detailJson);
    ret = Arm_Extension_CallService(handle, "demo", "echo", "{\"example\":\"sdk\",\"count\":1}", resultJson, sizeof(resultJson));
    printf("[c99_extension] CallService 状态码 / CallService status code: %d, 返回值 / Result: %s\n", ret, resultJson);
    ret = Arm_Extension_Toggle(handle, "demo");
    printf("[c99_extension] Toggle 状态码 / Toggle status code: %d\n", ret);

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_extension] 示例结束 / Example finished\n");
    return 0;
}