4.10 C99 FileManager 文件管理接口

概述

C99 FileManager 用于上传、下载、删除、搜索控制器文件和判断文件是否存在。搜索结果通过调用方准备的 ArmFileInfo 数组返回。

对应头文件：

• include/c_arm_file_manager.h

接口签名

Arm_FileManager_Upload

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

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

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 表示成功，其他值按状态码处理

Arm_FileManager_Search

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

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
overwriting	非 0 表示允许覆盖
Search	支持 outArray == NULL 的 count-only 模式； maxCount 小于实际数量时返回 BUFFER_TOO_SMALL
IsExist	成功时 outExists=1 表示存在， 0 表示不存在

ArmFileInfo 字段

字段	类型	说明
name	char[256]	文件名
created_at	char[64]	创建时间字符串

行为约定

场景	说明
上传	overwriting 为 0 时不覆盖同名文件
下载	下载前检查控制器侧目标文件是否存在；目标不存在时返回 FILE_NOTEXIST
本地覆盖	overwriting 为 0 且本地目标已存在时返回 FAILED_TO_DOWNLOAD_SAME_NAME_FILE
删除	删除前检查控制器侧目标是否存在；目标不存在时返回 FILE_NOTEXIST
搜索	outArray == NULL 时只查询数量；调用是否成功以返回状态码为准，搜索结果可为空
存在性判断	STATUS_CODE 表示查询动作是否成功， outExists 表示文件是否存在

最小调用示例

#include <stdio.h>  // 引入 printf，用于打印文件是否存在
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    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;  // 根据查询结果返回
}  // 结束示例主函数

场景化示例

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

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