4.3 C99 Alarm Interface

Overview

C99 Alarm provides alarm reset, active alarm list query, and highest-priority alarm query. Alarm details are written into the ArmAlarmInfo structure, and callers are responsible for preparing the output array buffer.

Corresponding header:

• include/c_arm_alarm.h

Interface Signatures

Arm_Alarm_Reset

int Arm_Alarm_Reset(ArmHandle* h);

Item	Description
Description	Resets current alarms
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

Arm_Alarm_GetAllActive

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

Item	Description
Description	Queries the full active alarm list
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first language : int , alarm text language. See LanguageType for values outArray : ArmAlarmInfo* , output array allocated by the caller maxCount : size_t , output array capacity, meaning the maximum number of elements the caller can receive outCount : size_t* , output count pointer. On success, receives the actual count
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes
Notes	The caller allocates the output array. maxCount is the capacity, and outCount returns the actual count

Arm_Alarm_GetTop

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

Item	Description
Description	Queries the highest-priority alarm
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first outAlarm : ArmAlarmInfo* , output parameter allocated by the caller and passed as a valid pointer
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

Array and Language Rules

Item	Rule
language	Language selector. See LanguageType
count-only	When outArray == NULL and outCount != NULL , only the alarm count is written back
Buffer too small	When maxCount is smaller than the actual alarm count, returns BUFFER_TOO_SMALL and sets outCount to 0
Success	Writes the alarm array and writes the actual count to outCount
Reset	Arm_Alarm_Reset() changes controller alarm state

ArmAlarmInfo Fields

Field	Type	Description
user_code	char[64]	User-readable alarm code
inner_code	char[64]	Controller-side alarm code
name	char[128]	Alarm name
reason	char[256]	Alarm cause
suggest	char[256]	Suggested handling action
consequence	char[256]	Possible impact of the alarm
ext_desc	char[256]	Extended description

When there is no active alarm, list query succeeds with return value 0 and outCount set to 0 ; highest-priority alarm query writes an empty structure on success.

Minimal Call Example

#include <stdio.h>     // printf for printing alarm count
#include "c_arm_api.h" // C99 SDK umbrella header

int main(void)
{
    ArmHandle* h = Arm_Create();
    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;
}

Scenario Examples

Query Highest-Priority Alarm

ArmAlarmInfo topAlarm = {0};
int topRet = Arm_Alarm_GetTop(h, &topAlarm);
(void)topRet;

Query Count First, Then Query List

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;

Controlled Reset

/* int resetRet = Arm_Alarm_Reset(h); */

Example code:

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