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 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고	성공 시 플러그인 목록을 compact 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 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고	성공 시 단일 플러그인 상세 정보를 compact 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 를 compact 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 은 compact JSON을 출력합니다. 필드 기준은 2.4-extension-types를 참고하십시오.
• Arm_Extension_GetList / Arm_Extension_Get 은 HTTP가 200 이 아니거나, JSON 파싱에 실패하거나, 반환 구조가 맞지 않으면 오류 코드를 반환합니다.
• Arm_Extension_CallService 는 성공 시 result 를 compact JSON으로 출력합니다. 결과가 문자열이면 출력에 따옴표가 유지됩니다.
• params_json 이 {} 이면 query string을 추가하지 않습니다.
• params_json 의 키-값은 query string으로 평탄화됩니다. 배열이나 중첩 객체는 지원하지 않습니다.
• result 가 없거나 null 이면 OTHER_ERR 를 반환합니다.
• Arm_Extension_Toggle 은 플러그인 상태를 변경하며 출력 버퍼가 없습니다. 전환 작업에는 더 긴 HTTP timeout이 사용됩니다.

최소 호출 예제

#include <stdio.h>  // 플러그인 목록을 출력하기 위한 표준 출력
#include "c_arm_api.h"  // C99 SDK 최상위 헤더
int main(void)  // 예제 프로그램 진입점
{  // 예제 main 함수 시작
    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;  // 조회 결과에 따라 예제 상태 반환
}  // 예제 main 함수 종료

시나리오 예제

아래 조각은 연결에 성공한 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

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