4.10 C99 FileManager Interface

Overview

C99 FileManager uploads, downloads, deletes, and searches controller files, and checks whether files exist. Search results are returned through an ArmFileInfo array prepared by the caller.

Corresponding header:

• include/c_arm_file_manager.h

Interface Signatures

Arm_FileManager_Upload

int Arm_FileManager_Upload(ArmHandle* h, const char* filePath, const char* fileType, int overwriting);

Item	Description
Description	Uploads a file to the controller
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first filePath : const char* , local file path to upload. User programs, block programs, and similar file groups are resolved by base file name fileType : const char* , file type string. See the fileType table below overwriting : int , whether overwrite is allowed. Non- 0 allows overwrite
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

Arm_FileManager_Download

int Arm_FileManager_Download(ArmHandle* h, const char* fileName, const char* localPath, const char* fileType, int overwriting);

Item	Description
Description	Downloads a file from the controller
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first fileName : const char* , controller-side file name or base name. User programs and block programs do not need extensions localPath : const char* , local save directory. For FlyShot , this is treated as the target file path fileType : const char* , file type string. See the fileType table below overwriting : int , whether overwrite is allowed. Non- 0 allows overwrite
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

Arm_FileManager_Delete

int Arm_FileManager_Delete(ArmHandle* h, const char* fileName, const char* fileType);

Item	Description
Description	Deletes a controller-side file
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first fileName : const char* , controller-side file name or base name fileType : const char* , file type string. See the fileType table below
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

Arm_FileManager_Search

int Arm_FileManager_Search(ArmHandle* h, const char* pattern, ArmFileInfo* outArray, size_t maxCount, size_t* outCount);

Item	Description
Description	Searches controller-side files
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first pattern : const char* , glob-style match pattern such as *.csv or demo* outArray : ArmFileInfo* , 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_FileManager_IsExist

int Arm_FileManager_IsExist(ArmHandle* h, const char* fileName, int* outExists);

Item	Description
Description	Checks whether a controller-side file exists
Request Parameters	h : ArmHandle* , C99 session handle, usually from Arm_Create() ; business APIs require connection first fileName : const char* , controller-side file name or path outExists : int* , existence output pointer. 1 means exists, 0 means does not exist
Return Value	STATUS_CODE integer value; 0 means success, other values should be handled as status codes

fileType Values and File Expansion Rules

fileType	Upload	Download	Delete
Trajectory	Uploads the .trajectory file by base name	Downloads the .trajectory file by base name	Deletes the trajectory file by passed file name
UserProgram	Uploads .json and .xml by base name	Downloads .json and .xml , then creates a same-name .zip	Deletes same-name .json and .xml
BlockProgram	Uploads .block , .json , and .xml by base name	Downloads .block , .json , and .xml , then creates a same-name .zip	Deletes same-name .block , .json , and .xml
TrajectoryCsv	Uploads the single file matching the passed file name	Downloads the single file matching the passed file name	Deletes the single file matching the passed file name
RobotTmp	Uploads the single file matching the passed file name	Downloads the single file matching the passed file name	Deletes the single file matching the passed file name
FlyShot	Not applicable	Treats localPath as the local target file path	Not applicable

Parameters and Rules

Item	Rule
filePath	Local file path used for upload
fileName	Controller-side file name or base name. User programs and block programs expand related files by base name during download and delete
localPath	Local target directory for download. For FlyShot , it is the target file path
fileType	File type string from the table above. Unsupported types return UNSUPPORTED_FILETYPE
overwriting	Non- 0 means overwrite is allowed
Search	Supports count-only mode with outArray == NULL ; if maxCount is smaller than the actual count, returns BUFFER_TOO_SMALL
IsExist	On success, outExists=1 means exists and 0 means does not exist

ArmFileInfo Fields

Field	Type	Description
name	char[256]	File name
created_at	char[64]	Creation time string

Behavior Conventions

Scenario	Description
Upload	When overwriting is 0 , a same-name file is not overwritten
Download	Before downloading, the SDK checks whether the controller-side target exists. If it does not exist, FILE_NOTEXIST is returned
Local overwrite	When overwriting is 0 and the local target already exists, FAILED_TO_DOWNLOAD_SAME_NAME_FILE is returned
Delete	Before deletion, the SDK checks whether the controller-side target exists. If it does not exist, FILE_NOTEXIST is returned
Search	When outArray == NULL , only the count is queried. Use the return status code to determine whether the call succeeded; the search result may be empty
Existence check	STATUS_CODE indicates whether the query action succeeded; outExists indicates whether the file exists

Minimal Call Example

#include <stdio.h>     // printf for printing whether the file exists
#include "c_arm_api.h" // C99 SDK umbrella header

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

Scenario Examples

ArmFileInfo files[16] = {0};
size_t fileCount = 0U;
int exists = 0;
int searchRet = Arm_FileManager_Search(h, "*.csv", files, 16, &fileCount);
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;

Example code:

c99/file_manager_basic/src/main.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;
}