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)  // 예제 프로그램 진입점
{  // 예제 main 함수 시작
    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;  // 조회 결과에 따라 반환
}  // 예제 main 함수 종료

시나리오 예제

최고 우선순위 알람 조회

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