4.12 C99 Extension 插件接口

概述

C99 Extension 用于查询机器人本体侧插件、切换插件启用状态和调用 EasyService。接口返回 JSON 时使用 char* + bufSize 输出。

前置条件与服务端口

项	说明
连接依赖	`Arm_Extension_GetList` 、 `Arm_Extension_Get` 、 `Arm_Extension_Toggle` 、 `Arm_Extension_CallService` 调用前需要先完成 `Arm_Connect()` 。
地址依赖	插件接口使用 `Arm_Connect()` 后绑定的示教器地址；未连接或地址不可用时返回未连接状态码。
`GetRobotIp`	可在连接前调用，但不保证所有运行环境都能推断出有效 IP；不能推断时输出空字符串。
JSON 输出	所有 JSON 文本都通过调用方提供的 `char* + buf_size` 输出。

端口	用途
`5613`	机器人本体侧 Pure Web 服务，用于 `Arm_Extension_GetRobotIp()` 环境探测
`5615`	机器人本体侧插件列表与详情服务
`5616`	机器人本体侧 EasyService 调用服务

接口签名

`Arm_Extension_GetRobotIp`

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

项	说明
描述	根据机器人本体侧运行环境推断或读取机器人 IP。
请求参数	`h` : `ArmHandle` ，C99 会话句柄，通常来自 `Arm_Create()` ，业务接口需要先连接成功 `out_buf` : `char` ，输出字符串缓冲区，由调用方分配 `buf_size` : `size_t` ，输出缓冲区大小，包含结尾 `\0` 的空间
返回值	STATUS_CODE 整数值； `0` 表示成功，其他值按状态码处理
备注	不支持的机器人本体侧运行环境会返回成功并输出空字符串；输出缓冲区不足时按状态码返回。

`Arm_Extension_GetList`

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

项	说明
描述	查询机器人本体侧插件列表。
请求参数	`h` : `ArmHandle` ，C99 会话句柄，通常来自 `Arm_Create()` ，业务接口需要先连接成功 `out_buf` : `char` ，输出字符串缓冲区，由调用方分配 `buf_size` : `size_t` ，输出缓冲区大小，包含结尾 `\0` 的空间
返回值	STATUS_CODE 整数值； `0` 表示成功，其他值按状态码处理
备注	成功时输出插件列表紧凑 JSON；字段口径见 Extension 类型。

`Arm_Extension_Get`

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

项	说明
描述	查询机器人本体侧单个插件详情。
请求参数	`h` : `ArmHandle` ，C99 会话句柄，通常来自 `Arm_Create()` ，业务接口需要先连接成功 `name` : `const char` ，插件名称，不能为空，只允许 `A-Z a-z 0-9 . _ -` `out_buf` : `char*` ，输出字符串缓冲区，由调用方分配 `buf_size` : `size_t` ，输出缓冲区大小，包含结尾 `\0` 的空间
返回值	STATUS_CODE 整数值； `0` 表示成功，其他值按状态码处理
备注	成功时输出单个插件详情紧凑 JSON。

`Arm_Extension_Toggle`

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

项	说明
描述	切换插件启用状态。
请求参数	`h` : `ArmHandle` ，C99 会话句柄，通常来自 `Arm_Create()` ，业务接口需要先连接成功 `name` : `const char` ，插件名称，不能为空，只允许 `A-Z a-z 0-9 . _ -`
返回值	STATUS_CODE 整数值； `0` 表示成功，其他值按状态码处理
备注	会改变插件启用状态，没有输出缓冲区。

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

项	说明
描述	调用插件 EasyService。
请求参数	`h` : `ArmHandle` ，C99 会话句柄，通常来自 `Arm_Create()` ，业务接口需要先连接成功 `name` : `const char` ，插件名称，不能为空，只允许 `A-Z a-z 0-9 . _ -` `command` : `const char` ，服务命令名，不能为空，只允许 `A-Z a-z 0-9 . _ -` `params_json` : `const char` ，请求参数 JSON， `NULL` 或空串表示无参数，非空时根类型必须是对象 `out_buf` : `char*` ，输出字符串缓冲区，由调用方分配 `buf_size` : `size_t` ，输出缓冲区大小，包含结尾 `\0` 的空间
返回值	STATUS_CODE 整数值； `0` 表示成功，其他值按状态码处理
备注	成功时输出 EasyService `result` 的紧凑 JSON； `result` 缺失或为 `null` 时返回错误码。

参数与缓冲区规则

项	规则
`h`	不能为空
`out_buf` / `buf_size`	输出字符串接口中必须有效
缓冲区不足	返回 `BUFFER_TOO_SMALL` ，并写入空字符串
`name` / `command`	不能为空，只允许 `A-Z a-z 0-9 . _ -`
`params_json`	`NULL` 或空串表示无参数
`params_json` 根类型	必须是 JSON 对象
`params_json` 值类型	只支持字符串、有限数字、布尔

行为约定

Arm_Extension_GetRobotIp 在不支持的机器人本体侧运行环境下返回 OK + 空字符串 。
Arm_Extension_GetList / Arm_Extension_Get 输出紧凑 JSON，字段口径见 2.4-extension-types。
Arm_Extension_GetList / Arm_Extension_Get 在 HTTP 非 200 、JSON 解析失败或返回结构不匹配时返回错误码。
Arm_Extension_CallService 成功时输出 result 的紧凑 JSON；如果结果是字符串，输出中会保留引号。
params_json 为 {} 时，不追加 query string。
params_json 中的键值会被平铺成 query string，不支持数组或嵌套对象。
result 缺失或为 null 时返回 OTHER_ERR 。
Arm_Extension_Toggle 会改变插件状态，且没有输出缓冲区；切换操作使用较长 HTTP 超时。

最小调用示例

#include <stdio.h>  // 引入标准输出，用于打印插件列表
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    char listJson[4096] = {0};  // 准备插件列表 JSON 输出缓冲区
    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));  // 查询插件列表 JSON
    if (ret == 0) {  // 判断插件列表查询是否成功
        printf("extensions=%s\n", listJson);  // 打印插件列表 JSON
    }  // 结束插件列表结果判断
    Arm_Disconnect(h);  // 断开机器人连接
    Arm_Destroy(h);  // 销毁会话句柄
    return ret == 0 ? 0 : 1;  // 根据查询结果返回示例状态
}  // 结束示例主函数

场景化示例

下面片段默认已经有连接成功的 ArmHandle* h 。

查询机器人 IP 与插件列表

char robotIp[128] = {0};  // 准备机器人 IP 输出缓冲区
char listJson[4096] = {0};  // 准备插件列表 JSON 输出缓冲区
int ipRet = Arm_Extension_GetRobotIp(h, robotIp, sizeof(robotIp));  // 推断机器人 IP
int listRet = Arm_Extension_GetList(h, listJson, sizeof(listJson));  // 查询插件列表
(void)ipRet;  // 示例中保留机器人 IP 查询状态码
(void)listRet;  // 示例中保留插件列表查询状态码

查询详情并调用服务

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));  // 调用插件 EasyService
(void)getRet;  // 示例中保留详情查询状态码
(void)callRet;  // 示例中保留服务调用状态码

切换插件

/* int toggleRet = Arm_Extension_Toggle(h, "demo_extension"); */  // 切换插件启用状态会影响现场服务，确认后再执行

示例代码

c99/extension_basic/src/main.cpp

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

1 概览与接入

2 数据结构

3 方法

4 C99 接口

6 其他语言接入

4.12 C99 Extension 插件接口

概述

前置条件与服务端口

接口签名

`Arm_Extension_GetRobotIp`

`Arm_Extension_GetList`

`Arm_Extension_Get`

`Arm_Extension_Toggle`

`Arm_Extension_CallService`

参数与缓冲区规则

行为约定

最小调用示例

场景化示例

查询机器人 IP 与插件列表

查询详情并调用服务

切换插件

4.12 C99 Extension 插件接口 ​

概述 ​

前置条件与服务端口 ​

接口签名 ​

Arm_Extension_GetRobotIp ​

Arm_Extension_GetList ​

Arm_Extension_Get ​

Arm_Extension_Toggle ​

Arm_Extension_CallService ​

参数与缓冲区规则 ​

行为约定 ​

最小调用示例 ​

场景化示例 ​

查询机器人 IP 与插件列表 ​

查询详情并调用服务 ​

切换插件 ​

4.12 C99 Extension 插件接口

概述

前置条件与服务端口

接口签名

`Arm_Extension_GetRobotIp`

`Arm_Extension_GetList`

`Arm_Extension_Get`

`Arm_Extension_Toggle`

`Arm_Extension_CallService`

参数与缓冲区规则

行为约定

最小调用示例

场景化示例

查询机器人 IP 与插件列表

查询详情并调用服务

切换插件