Agilebot Robot SDK
Search K

한국어

中文
English

한국어

中文
English

外观

4.10 C99 FileManager 파일 관리 인터페이스 ​

개요 ​

C99 FileManager 는 컨트롤러 파일 업로드, 다운로드, 삭제, 검색 및 파일 존재 여부 판단에 사용됩니다. 검색 결과는 호출자가 준비한 ArmFileInfo 배열로 반환됩니다.

해당 헤더 파일:

  • include/c_arm_file_manager.h

인터페이스 시그니처 ​

Arm_FileManager_Upload ​

c
int Arm_FileManager_Upload(ArmHandle* h, const char* filePath, const char* fileType, int overwriting);
항목설명
설명파일을 컨트롤러로 업로드합니다.
요청 파라미터h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
filePath : const char* , 업로드할 로컬 파일 경로. 사용자 프로그램, 블록 프로그램 등은 기본 파일명으로 같은 이름의 관련 파일을 찾습니다.
fileType : const char* , 파일 타입 문자열. 값은 아래 fileType 표를 참고하십시오.
overwriting : int , 덮어쓰기 허용 여부. 0 이 아니면 덮어쓰기를 허용합니다.
반환값STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.

Arm_FileManager_Download ​

c
int Arm_FileManager_Download(ArmHandle* h, const char* fileName, const char* localPath, const char* fileType, int overwriting);
항목설명
설명컨트롤러에서 파일을 다운로드합니다.
요청 파라미터h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
fileName : const char* , 컨트롤러 측 파일명 또는 기본명. 사용자 프로그램과 블록 프로그램은 확장자를 포함하지 않아도 됩니다.
localPath : const char* , 로컬 저장 디렉터리. FlyShot 시나리오에서는 대상 파일 경로로 처리합니다.
fileType : const char* , 파일 타입 문자열. 값은 아래 fileType 표를 참고하십시오.
overwriting : int , 덮어쓰기 허용 여부. 0 이 아니면 덮어쓰기를 허용합니다.
반환값STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.

Arm_FileManager_Delete ​

c
int Arm_FileManager_Delete(ArmHandle* h, const char* fileName, const char* fileType);
항목설명
설명컨트롤러 측 파일을 삭제합니다.
요청 파라미터h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
fileName : const char* , 컨트롤러 측 파일명 또는 기본명
fileType : const char* , 파일 타입 문자열. 값은 아래 fileType 표를 참고하십시오.
반환값STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
c
int Arm_FileManager_Search(ArmHandle* h, const char* pattern, ArmFileInfo* outArray, size_t maxCount, size_t* outCount);
항목설명
설명컨트롤러 측 파일을 검색합니다.
요청 파라미터h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
pattern : const char* , glob 스타일 매칭 표현식. 예: *.csv , demo*
outArray : ArmFileInfo* , 호출자가 할당하는 출력 배열
maxCount : size_t , 출력 배열 용량. 호출자가 최대 몇 개의 요소를 받을 수 있는지를 나타냅니다.
outCount : size_t* , 출력 개수 포인터. 성공 시 실제 개수를 씁니다.
반환값STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고배열 출력은 호출자가 할당합니다. maxCount 는 용량을 의미하고, outCount 는 실제 개수를 반환합니다.

Arm_FileManager_IsExist ​

c
int Arm_FileManager_IsExist(ArmHandle* h, const char* fileName, int* outExists);
항목설명
설명컨트롤러 측 파일이 존재하는지 판단합니다.
요청 파라미터h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
fileName : const char* , 컨트롤러 측 파일명 또는 경로
outExists : int* , 존재 여부 출력 포인터. 1 은 존재, 0 은 존재하지 않음을 의미합니다.
반환값STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.

fileType 값 및 파일 확장 규칙 ​

fileType업로드다운로드삭제
Trajectory기본명 기준으로 .trajectory 파일 업로드기본명 기준으로 .trajectory 파일 다운로드전달한 파일명 기준으로 궤적 파일 삭제
UserProgram기본명 기준으로 .json 및 .xml 업로드.json 및 .xml 을 다운로드한 뒤 같은 이름의 .zip 생성같은 이름의 .json 및 .xml 삭제
BlockProgram기본명 기준으로 .block , .json , .xml 업로드.block , .json , .xml 을 다운로드한 뒤 같은 이름의 .zip 생성같은 이름의 .block , .json , .xml 삭제
TrajectoryCsv전달한 파일명에 해당하는 단일 파일 업로드전달한 파일명에 해당하는 단일 파일 다운로드전달한 파일명에 해당하는 단일 파일 삭제
RobotTmp전달한 파일명에 해당하는 단일 파일 업로드전달한 파일명에 해당하는 단일 파일 다운로드전달한 파일명에 해당하는 단일 파일 삭제
FlyShot해당 없음localPath 를 로컬 대상 파일 경로로 처리해당 없음

파라미터 및 규칙 ​

항목규칙
filePath업로드에 사용하는 로컬 파일 경로
fileName컨트롤러 측 파일명 또는 기본명. 사용자 프로그램과 블록 프로그램은 다운로드 및 삭제 시 기본명 기준으로 관련 파일을 확장합니다.
localPath다운로드 대상 로컬 디렉터리. FlyShot 다운로드 시에는 대상 파일 경로입니다.
fileType파일 타입 문자열입니다. 값은 위 표를 참고하십시오. 지원하지 않는 타입은 UNSUPPORTED_FILETYPE 을 반환합니다.
overwriting0 이 아니면 덮어쓰기를 허용합니다.
SearchoutArray == NULL 인 count-only 모드를 지원합니다. maxCount 가 실제 수량보다 작으면 BUFFER_TOO_SMALL 을 반환합니다.
IsExist성공 시 outExists=1 은 존재, 0 은 존재하지 않음을 의미합니다.

ArmFileInfo 필드 ​

필드타입설명
namechar[256]파일명
created_atchar[64]생성 시간 문자열

동작 규칙 ​

시나리오설명
업로드overwriting 이 0 이면 같은 이름의 파일을 덮어쓰지 않습니다.
다운로드다운로드 전에 컨트롤러 측 대상 파일 존재 여부를 확인합니다. 대상이 없으면 FILE_NOTEXIST 를 반환합니다.
로컬 덮어쓰기overwriting 이 0 이고 로컬 대상이 이미 있으면 FAILED_TO_DOWNLOAD_SAME_NAME_FILE 을 반환합니다.
삭제삭제 전에 컨트롤러 측 대상 존재 여부를 확인합니다. 대상이 없으면 FILE_NOTEXIST 를 반환합니다.
검색outArray == NULL 이면 개수만 조회합니다. 호출 성공 여부는 반환 상태 코드로 판단하며 검색 결과는 비어 있을 수 있습니다.
존재 여부 판단STATUS_CODE 는 조회 동작의 성공 여부를 나타내고, outExists 는 파일 존재 여부를 나타냅니다.

최소 호출 예제 ​

c
#include <stdio.h>  // 파일 존재 여부를 출력하기 위한 printf
#include "c_arm_api.h"  // C99 SDK 최상위 헤더
int main(void)  // 예제 프로그램 진입점
{  // 예제 main 함수 시작
    ArmHandle* h = Arm_Create();  // C99 세션 핸들 생성
    int exists = 0;  // 파일 존재 여부 출력 변수 준비
    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_FileManager_IsExist(h, "/root/robot_data/progs/robot_tmp/demo.csv", &exists);  // 컨트롤러 측 파일 존재 여부 판단
    printf("exists=%d\n", exists);  // 존재 여부 출력
    Arm_Disconnect(h);  // 연결 해제
    Arm_Destroy(h);  // 핸들 해제
    return ret == 0 ? 0 : 1;  // 조회 결과에 따라 반환
}  // 예제 main 함수 종료

시나리오 예제 ​

c
ArmFileInfo files[16] = {0};  // 검색 결과 배열 준비
size_t fileCount = 0U;  // 파일 개수 출력 준비
int exists = 0;  // 존재 여부 출력 준비
int searchRet = Arm_FileManager_Search(h, "*.csv", files, 16, &fileCount);  // CSV 파일 검색
int existRet = Arm_FileManager_IsExist(h, "/root/robot_data/progs/robot_tmp/demo.csv", &exists);  // 파일 존재 여부 판단
/* int uploadRet = Arm_FileManager_Upload(h, "D:/sdk-demo/demo.csv", "trajectory_csv", 1); */  // 업로드는 컨트롤러 파일 영역에 쓰므로 확인 후 실행
/* int downloadRet = Arm_FileManager_Download(h, "demo.csv", "D:/sdk-demo", "trajectory_csv", 1); */  // 다운로드는 로컬 파일에 쓰므로 확인 후 실행
/* int deleteRet = Arm_FileManager_Delete(h, "demo.csv", "trajectory_csv"); */  // 컨트롤러 파일 삭제는 확인 후 실행
(void)searchRet;  // 예제에서 검색 상태 코드 보관
(void)existRet;  // 예제에서 존재 여부 상태 코드 보관

예제 코드

c99/file_manager_basic/src/main.cpp
cpp
#include <stdio.h>
#include <string.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_file_manager] 创建句柄失败 / 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_file_manager] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_file_manager] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 在本地创建一个演示文件，供上传接口直接使用。
    // [EN] Create a local demo file so the upload API can use it directly.
    FILE* localFile = fopen("sdk_demo.txt", "wb");
    if (localFile != NULL) {
        const char* text = "sdk example file\n";
        fwrite(text, 1U, strlen(text), localFile);
        fclose(localFile);
    }
    printf("[c99_file_manager] 本地演示文件已准备好 / Local demo file prepared\n");

    // [ZH] 顺序执行全部文件管理接口。
    // [EN] Execute all file-manager APIs in sequence.
    ret = Arm_FileManager_Upload(handle, "sdk_demo.txt", "RobotTmp", 1);
    printf("[c99_file_manager] Upload 状态码 / Upload status code: %d\n", ret);
    ArmFileInfo files[8] = {0};
    size_t fileCount = 0U;
    ret = Arm_FileManager_Search(handle, "*", files, 8U, &fileCount);
    printf("[c99_file_manager] Search 状态码 / Search status code: %d, 数量 / Count: %zu\n", ret, fileCount);
    for (size_t index = 0U; index < fileCount && index < 3U; ++index) {
        printf("[c99_file_manager] 文件 / File #%zu: name=%s, created_at=%s\n", index, files[index].name, files[index].created_at);
    }
    int exists = 0;
    ret = Arm_FileManager_IsExist(handle, "/root/robot_data/progs/robot_tmp/sdk_demo.txt", &exists);
    printf("[c99_file_manager] IsExist 状态码 / IsExist status code: %d, 是否存在 / Exists: %d\n", ret, exists);
    ret = Arm_FileManager_Download(handle, "sdk_demo.txt", ".", "RobotTmp", 1);
    printf("[c99_file_manager] Download 状态码 / Download status code: %d\n", ret);
    ret = Arm_FileManager_Delete(handle, "sdk_demo.txt", "RobotTmp");
    printf("[c99_file_manager] Delete 状态码 / Delete status code: %d\n", ret);

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_file_manager] 示例结束 / Example finished\n");
    return 0;
}

Copyright © 2026-present Agilebot Robotics Co., Ltd.