4.3 C99 Alarm 报警接口

概述

C99 Alarm 提供报警复位、活动报警列表和最高优先级报警查询。报警详情写入 ArmAlarmInfo 结构体，调用方负责准备数组缓冲区。

对应头文件：

• include/c_arm_alarm.h

接口签名

Arm_Alarm_Reset

int Arm_Alarm_Reset(ArmHandle* h);

项	说明
描述	复位当前报警。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Alarm_GetAllActive

int Arm_Alarm_GetAllActive(ArmHandle* h, int language, ArmAlarmInfo* outArray, size_t maxCount, size_t* outCount);

项	说明
描述	查询全部活动报警列表。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 language : int ，报警文本语言，取值见 LanguageType outArray : ArmAlarmInfo* ，输出数组，由调用方分配 maxCount : size_t ，输出数组容量，表示调用方最多可接收多少个元素 outCount : size_t* ，输出数量指针，成功时写入实际数量
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理
备注	数组输出由调用方分配， maxCount 表示容量， outCount 返回实际数量。

Arm_Alarm_GetTop

int Arm_Alarm_GetTop(ArmHandle* h, ArmAlarmInfo* outAlarm);

项	说明
描述	查询最高优先级报警。
请求参数	h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功 outAlarm : ArmAlarmInfo* ，输出参数，由调用方分配并传入有效指针
返回值	STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

数组与语言规则

项	规则
language	语言选择，取值见 LanguageType
count-only	outArray == NULL 且 outCount != NULL 时，只回写报警数量
缓冲区不足	maxCount 小于实际报警数时返回 BUFFER_TOO_SMALL ，并把 outCount 置 0
成功	写入报警数组，并把实际条数写回 outCount
复位	Arm_Alarm_Reset() 会改变控制器报警状态

ArmAlarmInfo 字段

字段	类型	说明
user_code	char[64]	用户可读报警码
inner_code	char[64]	控制器侧报警码
name	char[128]	报警名称
reason	char[256]	报警原因
suggest	char[256]	建议处理方式
consequence	char[256]	报警可能造成的影响
ext_desc	char[256]	扩展描述

当前没有活动报警时，列表查询成功返回 0 且 outCount 为 0 ；最高优先级报警查询成功时会写入空值结构。

最小调用示例

#include <stdio.h>  // 引入 printf，用于打印报警数量
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    ArmAlarmInfo alarms[8] = {0};  // 准备活动报警输出数组
    size_t count = 0U;  // 准备接收报警数量
    if (h == NULL) {  // 判断句柄是否创建失败
        return 1;  // 创建失败时退出
    }  // 结束句柄判断
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // 连接控制器
        Arm_Destroy(h);  // 连接失败时销毁句柄
        return 1;  // 返回错误
    }  // 结束连接判断
    int ret = Arm_Alarm_GetAllActive(h, 0, alarms, 8, &count);  // 查询活动报警列表
    printf("alarm_count=%zu\n", count);  // 打印报警数量
    Arm_Disconnect(h);  // 断开连接
    Arm_Destroy(h);  // 销毁句柄
    return ret == 0 ? 0 : 1;  // 根据查询结果返回
}  // 结束示例主函数

场景化示例

查询最高优先级报警

ArmAlarmInfo topAlarm = {0};  // 准备最高优先级报警输出结构体
int topRet = Arm_Alarm_GetTop(h, &topAlarm);  // 查询最高优先级报警
(void)topRet;  // 示例中保留查询状态码

先查数量再查列表

size_t requiredCount = 0U;  // 准备接收报警总数
int countRet = Arm_Alarm_GetAllActive(h, 0, NULL, 0, &requiredCount);  // 只查询活动报警数量
ArmAlarmInfo alarms[16] = {0};  // 准备固定容量报警数组
size_t actualCount = 0U;  // 准备接收实际写入数量
int listRet = Arm_Alarm_GetAllActive(h, 0, alarms, 16, &actualCount);  // 查询活动报警详情
(void)countRet;  // 示例中保留数量查询状态码
(void)listRet;  // 示例中保留列表查询状态码

受控复位

/* int resetRet = Arm_Alarm_Reset(h); */  // 报警复位会改变控制器状态，确认后再执行

示例代码

c99/alarm_query/src/main.cpp

#include <stdio.h>
#include <stdlib.h>

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

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

    // [ZH] 显式使用英文，验证活动报警列表和后续详情查询使用同一语言参数。
    // [EN] Use English explicitly to verify list and detail queries share it.
    const int alarmLanguage = 1;

    // [ZH] 分两阶段读取全部活动报警。
    // [EN] Read all active alarms in two phases.
    size_t alarmCount = 0U;
    ret = Arm_Alarm_GetAllActive(handle, alarmLanguage, NULL, 0U, &alarmCount);
    printf(
        "[c99_alarm] GetAllActive(计数) 状态码 / "
        "GetAllActive(count) status code: %d, 数量 / Count: %zu\n",
        ret,
        alarmCount
    );
    if (ret == 0 && alarmCount > 0U) {
        ArmAlarmInfo* alarms =
            (ArmAlarmInfo*)calloc(alarmCount, sizeof(ArmAlarmInfo));
        if (alarms == NULL) {
            printf("[c99_alarm] 分配报警数组失败 / Failed to allocate alarm array\n");
        } else {
            ret = Arm_Alarm_GetAllActive(
                handle,
                alarmLanguage,
                alarms,
                alarmCount,
                &alarmCount
            );
            printf(
                "[c99_alarm] GetAllActive(数据) 状态码 / "
                "GetAllActive(data) status code: %d\n",
                ret
            );
            for (size_t index = 0U; index < alarmCount; ++index) {
                printf(
                    "[c99_alarm] 活动报警 / Active alarm #%zu: "
                    "user_code=%s, inner_code=%s, name=%s, reason=%s\n",
                    index,
                    alarms[index].user_code,
                    alarms[index].inner_code,
                    alarms[index].name,
                    alarms[index].reason
                );
            }
            free(alarms);
        }
    }

    // [ZH] 读取最高优先级报警。该接口本身没有语言入参。
    // [EN] Read the top-priority alarm. This API has no language parameter.
    ArmAlarmInfo topAlarm = {0};
    ret = Arm_Alarm_GetTop(handle, &topAlarm);
    printf(
        "[c99_alarm] GetTop 状态码 / GetTop status code: %d, "
        "最高报警 / Top alarm: user_code=%s, name=%s\n",
        ret,
        topAlarm.user_code,
        topAlarm.name
    );

    // [ZH] 报警复位会改变控制器状态，默认不执行，只保留受控调用入口。
    // [EN] Resetting alarms changes controller state, so keep the controlled call disabled by default.
    const int reset_alarm = 0;
    if (reset_alarm != 0) {
        ret = Arm_Alarm_Reset(handle);
        printf(
            "[c99_alarm] Reset 状态码 / Reset status code: %d\n",
            ret
        );
    }
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_alarm] 示例结束 / Example finished\n");
    return 0;
}